docs(changelog): #8663 公司借款域往来单位放开员工类型 + 归还归支付管理 + 双 tab
changelog-filename-gate / validate (push) Failing after 1s
changelog-filename-gate / validate (push) Failing after 1s
这个提交包含在：
yaosutu
@@ -0,0 +1,171 @@
|
|||||||
|
---
|
||||||
|
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: "pending"
|
||||||
|
frontend_owner: ""
|
||||||
|
frontend_ref: ""
|
||||||
|
target_release: ""
|
||||||
|
verified_at: "2026-09-30"
|
||||||
|
status_note: "公司借款域四项调整。①借入/借出往来单位放开单位类型（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
|
||||||
|
- 后端负责人：腰苏图
|
||||||
在新工单中引用
屏蔽一个用户