---
schema: "hl-changelog/v2"
ticket: "8663"
title: "公司借款域：往来单位放开员工类型 + 归还菜单归支付管理 + 归还列表改双 tab（#8663）"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "hl-admin(claude-opus-4-8)"
frontend_ref: "305ba037d1a184c9bd6bc131d004abd1f1bd6349"
target_release: "v2.1"
verified_at: "2026-10-01"
status_note: "2026-10-01 hl-admin 交付：①登记表单加单位类型 select(字典 fin_unit_type 优先+本地两码兜底),SUPPLIER 走供应商弹窗/STAFF 走 employee-options(adminId 作 unitId),切类型清空已选防串单,payload 带 unitType,列表单位类型列补 STAFF 中文；②Cashier 聚合行 unitType 带回明细查询与 settle(599312 拦截器透 message);③页体 git mv payable/company-loan-repay→pay/company-loan-repay+路由 spec 同步;④IN 收银台 n-tabs 双 tab,已还台账=repays/page?direction=IN 手工分页+只读查看弹窗。4 spec 45 例全绿,ref 305ba037。公司借款域四项调整。①借入/借出往来单位放开单位类型（unitType），供应商 SUPPLIER 与员工 STAFF 二选一，按类型联动供应商/员工选择框；②归还/回收结算请求 VO 新增可选入参 unitType（连同 unitId 一起校验归属，防两套 ID 空间同数值串单），additive 兼容不传按旧口径；③「公司借款归还」菜单从付款管理搬到支付管理（path /finance/payable/company-loan-repay → /finance/pay/company-loan-repay），前端路由需同步，否则点菜单 404；④借入列表删「去还款」按钮、归还列表改「待还款/已还台账」双 tab（后端零新增接口，复用现成收银台与流水接口）。新增数据字典 fin_unit_type（供应商/员工）。settle 单位一致性守卫加 unit_type 比对，勾选单与入参单位类型不符报 599312。"
updated_at: "2026-09-30"
base: "dev-v3"
---

# finance：公司借款域往来单位放开员工类型 + 归还归支付管理 + 双 tab（管理后台）

> ⚠️ **菜单路由变更**：「公司借款归还」从付款管理搬到支付管理，path 由 `/finance/payable/company-loan-repay` 改为 `/finance/pay/company-loan-repay`。前端路由必须同步，否则点菜单 404。
> ⚠️ **入参变更**：结算接口新增可选 `unitType`；**出参变更**：列表/聚合/流水行新增 `unitType` 字段；**枚举变更**：新增 `FinUnitTypeEnum`（SUPPLIER/STAFF）+ 数据字典 `fin_unit_type`。

## 1. 接口背景

财务「收款管理/公司借入」登记公司向外部单位借入的款项，「支付管理/公司借款归还」由出纳按单位聚合归还。原实现往来单位**只支持供应商**（unit_type 恒 SUPPLIER），业务需支持员工；且「归还」本质是出纳选付款账户实付，原挂在付款管理（台账/审批层）不对称；已核销单从归还列表消失无处查看。

本次合并处理四块：①往来单位放开单位类型（供应商/员工）+ 选择框联动；②结算守卫防供应商/员工 ID 同数值串单；③归还菜单归支付管理；④借入列表删还款按钮、归还列表改双 tab。

## 2. 变更清单

| # | 项 | 变更 | 端点 |
|---|---|---|---|
| 1 | 往来单位类型 | 新增可选入参 `unitType`（SUPPLIER/STAFF，默认 SUPPLIER），出参行新增 `unitType` | 创建/列表/回收聚合/归还聚合 |
| 2 | 结算归属校验 | 新增可选入参 `unitType`，连同 `unitId` 一起校验 | repay-cashier/settle、recover/settle |
| 3 | 菜单迁移 | 归还菜单付款管理→支付管理，path 变更 | （前端路由） |
| 4 | 列表职责 | 借入列表删「去还款」按钮；归还列表改「待还款/已还台账」双 tab | （前端 UI，后端复用现成接口） |
| 5 | 数据字典 | 新增 `fin_unit_type`：SUPPLIER 供应商 / STAFF 员工 | dict/data/fin_unit_type |

## 3. 接口详情

统一前缀 `POST|GET /admin/finance/company-loans/**`（业务调用**不带** `/hl-order-service-v3` 前缀，网关按 `/admin/finance/**` 路由）。

## 4. 入参

### 4.1 创建借入 `POST /admin/finance/company-loans`
```json
{
  "direction": "IN",
  "unitType": "SUPPLIER 或 STAFF（可选，默认 SUPPLIER）",
  "unitId": "按类型：供应商ID 或 员工 adminId",
  "handlerStaffId": "经办人 adminId（必填）",
  "amount": "借款金额>0",
  "feeRate": "手续费率‰，空按0",
  "loanDate": "借款日期",
  "dueDate": "约定归还日期（必填）",
  "purpose": "借款用途（必填）"
}
```
> `unitName` / `handlerStaffName` 不用前端传（服务端反查覆盖快照，前端传值不生效）。

### 4.2 归还结算 `POST /admin/finance/company-loans/repay-cashier/settle`
```json
{
  "unitId": "单位ID",
  "unitType": "SUPPLIER 或 STAFF（建议必传，防串单）",
  "loanIds": ["整笔归还的借入单ID，≥1，每笔还欠还全额"],
  "fundAccountId": "出账资金账户ID（必填，出纳选从哪张卡出钱）",
  "feeRate": "手续费率‰，默认0",
  "voucherUrl": "付款凭证影像URL"
}
```

### 4.3 回收结算 `POST /admin/finance/company-loans/recover/settle`
同 4.2 结构（借出方向回收），`unitType` 同为可选。

## 5. 出参

### 5.1 借款行 `CompanyLoanRowRespVO`（GET /page）
`id, loanNo, direction, unitType🆕, unitId, unitName, handlerStaffId, handlerStaffName, amount, repaidAmount, outstandingAmount, purpose, loanDate, dueDate, status, operatorName, createTime`（ID 均字符串）

### 5.2 归还单位聚合 `CompanyLoanRepayUnitRespVO`（GET /repay-cashier/units）
`unitType🆕, unitId, unitName, loanCount, totalOutstanding, nearestDueDate`

### 5.3 还款流水行 `CompanyLoanRepayRowRespVO`（GET /repays/page）
`id, repayNo(GH-前缀), loanId, loanNo, direction, unitName, amount, fundAccountId, repaidAt, voucherUrl`

## 6. 枚举/数据字典

### FinUnitTypeEnum（往来单位类型，枚举）
| 值 | 含义 |
|---|---|
| SUPPLIER | 供应商（资源域 supplier_main） |
| STAFF | 员工（用户域 admin_user，名称取企微快照） |

### 数据字典 `fin_unit_type`
`GET /admin/dict/data/fin_unit_type` →
```json
[{"dictLabel":"供应商","dictValue":"SUPPLIER"},{"dictLabel":"员工","dictValue":"STAFF"}]
```

### 借款状态 status（出参）
APPROVED 已登记 / PAID 已收付 / SETTLING 核销中 / SETTLED 已核销

## 7. 错误码
| 码 | 含义 |
|---|---|
| 599304 | 往来单位非法（不存在/不可选/类型非法/员工未登记真名） |
| 599305 | 经办人非法（不存在或未登记真名） |
| 599312 | 勾选单与入参单位不一致（unit_id 或 unit_type 不符，防串单） |

## 8. 示例

### 8.1 典型：创建员工类型借入
```http
POST /admin/finance/company-loans
{"direction":"IN","unitType":"STAFF","unitId":"2021059720172838914","handlerStaffId":"2085621600417148929","amount":5000,"loanDate":"2026-09-30","dueDate":"2026-10-30","purpose":"员工临时周转"}
→ {"code":0,"data":{"id":"...","loanNo":"GS-202609300005"}}
```

### 8.2 边界：归还按单位聚合（待还款 tab）
```http
GET /admin/finance/company-loans/repay-cashier/units?unitName=王
→ {"code":0,"data":[{"unitType":"STAFF","unitId":"2021...","unitName":"王骁","loanCount":1,"totalOutstanding":5000,"nearestDueDate":"2026-10-30"}]}
```
点单位看明细：`GET /repay-cashier/units/{unitId}?unitType=STAFF`（**unitType 必传**，从聚合行带回）。

### 8.3 异常：结算单位类型不符
```http
POST /repay-cashier/settle  {"unitId":"X","unitType":"STAFF","loanIds":[...], "fundAccountId":"..."}
# 该 unitId 实为 SUPPLIER 类型借款
→ {"code":599312,"msg":"勾选单与入参单位不一致"}
```

## 9. 业务边界

- 借入列表（收款管理）`GET /page?direction=IN`：`status` 不传即全量（含 SETTLED），删「去还款」按钮后纯台账。
- 待还款 tab 复用 `/repay-cashier/units` + `/repay-cashier/units/{unitId}`，**只返回未核销单**（PAID/SETTLING），已核销不出现。
- 已还台账 tab 用 `GET /repays/page?direction=IN`，每行一笔已还款事实，只读「查看」。

## 10. 修改前后对比

| 项 | 修改前 | 修改后 |
|---|---|---|
| 往来单位类型 | 恒供应商 | 供应商/员工二选一（unitType 联动选择框） |
| 归还菜单位置 | 付款管理/公司借款归还 | 支付管理/公司借款归还 |
| 菜单 path | /finance/payable/company-loan-repay | /finance/pay/company-loan-repay |
| 借入列表 | 行有「去还款」按钮 | 删按钮，纯台账 |
| 归还列表 | 已核销单消失无处查 | 待还款/已还台账双 tab |
| settle 归属校验 | 只比 unit_id | 加 unit_type 比对（防串单） |

## 11. 影响评估/回滚

- 入参 `unitType` 为可选 additive，不传按旧口径（SUPPLIER）兼容，旧前端不炸。
- 出参新增 `unitType` 字段为 additive，旧前端忽略即可。
- **菜单 path 变更为破坏性**：前端路由必须同步，否则点菜单 404。
- 回滚：菜单迁移走 sys_menu UPDATE（带守卫+幂等），可回写旧 path。

## 12. 注意事项

- ⚠️ 归还单单位明细接口 `unitType` **建议必传**（防供应商/员工 ID 同数值串单），从聚合行带回。
- 员工选择框数据源 `GET /admin/user/employee-options`（取 `adminId` 作 unitId，`enterpriseWechatName` 为空回落 `username`）。
- 供应商选择框数据源 `GET /admin/supplier/items/page?status=ACTIVE`（取 `supplierId` 作 unitId）。
- 员工未登记企微真名时报 599304（后端 fail-fast）。

## 13. 关联/联系人
- Issue：https://git.1814.love/wx/HL/issues/8663
- PR：https://git.1814.love/wx/HL/pulls/8668
- merge commit：154e2ac75a
- 后端负责人：腰苏图