diff --git a/changelogs-v2/2026-09/30_8663_公司借款往来单位放开员工类型+归还归支付管理+双tab-修改接口-管理后台.md b/changelogs-v2/2026-09/30_8663_公司借款往来单位放开员工类型+归还归支付管理+双tab-修改接口-管理后台.md new file mode 100644 index 00000000..911695fb --- /dev/null +++ b/changelogs-v2/2026-09/30_8663_公司借款往来单位放开员工类型+归还归支付管理+双tab-修改接口-管理后台.md @@ -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 +- 后端负责人:腰苏图