wx/hl-api-changelog

派生 0

文件

T

yaosutu 0e8500103a

changelog-filename-gate / validate (push) Failing after 1s

详情

docs(changelog): #8663 公司借款域往来单位放开员工类型 + 归还归支付管理 + 双 tab

2026-09-30 21:14:16 +08:00

9.0 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8663	公司借款域：往来单位放开员工类型 + 归还菜单归支付管理 + 归还列表改双 tab（#8663）	admin	yst(GIT)	修改接口	deployed	not_required	pending				2026-09-30	公司借款域四项调整。①借入/借出往来单位放开单位类型（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。	2026-09-30	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`

{
  "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`

{
  "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 →

[{"dictLabel":"供应商","dictValue":"SUPPLIER"},{"dictLabel":"员工","dictValue":"STAFF"}]

借款状态 status（出参）

APPROVED 已登记 / PAID 已收付 / SETTLING 核销中 / SETTLED 已核销

7. 错误码

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

8. 示例

8.1 典型：创建员工类型借入

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）

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 异常：结算单位类型不符

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：wx/HL#8663
PR：wx/HL#8668
merge commit：154e2ac75a
后端负责人：腰苏图

9.0 KiB 原始文件 Blame 文件历史 Unescape Escape