wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

docs(finance): 员工借款 changelog 重写——按原型修正核销归属 + 审批写清
changelog-filename-gate / validate (push) Failing after 2s
详情

浏览代码 
按原型对齐两菜单分工：
- 员工借款申请与审批（改名，原"申请与核销"）：付款管理/员工借款 = 申请 + 审批(submit/approve/reject 手工推进状态，approvalInstanceId 留空待接企微) + 核销进度只读 + 报销冲抵选借款；砍掉还款登记/红冲
- 员工借款支付出纳放款：支付管理/员工借款支付 = 出纳放款(cashier bizType=STAFF_LOAN) + 还款核销(现金/转账登记 POST /{id}/repays、红冲 DELETE、报销冲抵 offsetLoanIds) + 资金账户下拉

修正点：还款核销登记/红冲从申请篇挪到支付篇（原型 L1674 notice 明确核销在出纳侧）；审批接口写清为手工推进状态、approvalInstanceId 留空。
这个提交包含在：
yaosutu
2026-09-13 17:43:48 +08:00
父节点 babb9e6a89
当前提交 1191b6e046
共修改 2 个文件，包含 140 行新增和 69 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-09/13_staffloan_员工借款支付出纳放款-修改接口-管理后台.md
+101 -20
查看文件
@@ -1,7 +1,7 @@
--- ---
schema: "hl-changelog/v2" schema: "hl-changelog/v2"
ticket: "7521/7520" ticket: "7521/7520"
title: "员工借款支付（支付管理/员工借款支付）：借款审批通过后的出纳放款链路对接说明——队列/登记放款/已放款台账按 STAFF_LOAN 路由" title: "员工借款支付（支付管理/员工借款支付）：出纳放款 + 还款核销（现金/转账登记·红冲·报销冲抵）对接说明"
consumer: "admin" consumer: "admin"
author: "yst" author: "yst"
change_type: "修改接口" change_type: "修改接口"
@@ -12,42 +12,47 @@ frontend_owner: "mmg"
frontend_ref: "eb6812c2ce0d001d6f8f4b6b7716741edb64ecff" frontend_ref: "eb6812c2ce0d001d6f8f4b6b7716741edb64ecff"
target_release: "" target_release: ""
verified_at: "2026-09-13" verified_at: "2026-09-13"
status_note: "📘 对接说明（出纳域接口本次无变更）：员工借款 APPROVED 后进出纳待放款队列，复用统一出纳接口 /admin/finance/cashier/*，按 payType/bizType=STAFF_LOAN 路由。本文给前端「支付管理/员工借款支付」页的对接口径。菜单 V20260913_001 已挂载（PR #7642）。 前端已交付(eb6812c2):新建 pay/staff-loan 薄壳(CashierQueuePage pay-type=STAFF_LOAN),CashierQueuePage validator 白名单加 STAFF_LOAN、isExpense 泛化 isInternalLine(EXPENSE+STAFF_LOAN 同属内部单据线:无手续费、金额即全额),queueNotice/队列借款人列分叉;放款走 cashier/pay bizType=STAFF_LOAN;finance-route.spec 登记两菜单。" status_note: "📘 员工借款 APPROVED 后进出纳待放款队列，复用统一出纳接口 /admin/finance/cashier/* 按 payType/bizType=STAFF_LOAN 路由登记放款；放款后本页/出纳侧再做还款核销——现金/转账还款登记 POST /admin/finance/staff-loans/{id}/repays、红冲 DELETE /repays/{repayId}、报销冲抵走报销单 offsetLoanIds。本篇覆盖「支付管理/员工借款支付」菜单的放款+核销。申请+审批见《员工借款（付款管理/员工借款）》篇。菜单 V20260913_001 已挂载（PR #7642）。 前端已交付(eb6812c2):新建 pay/staff-loan 薄壳(CashierQueuePage pay-type=STAFF_LOAN),CashierQueuePage validator 白名单加 STAFF_LOAN、isExpense 泛化 isInternalLine(EXPENSE+STAFF_LOAN 同属内部单据线:无手续费、金额即全额),queueNotice/队列借款人列分叉;放款走 cashier/pay bizType=STAFF_LOAN;finance-route.spec 登记两菜单。⚠️还款核销登记/红冲本期归属本页（出纳侧），前端若把还款做在申请页需挪到本页。"
updated_at: "2026-09-13" updated_at: "2026-09-13"
base: "dev-v3" base: "dev-v3"
--- ---
# 员工借款支付（支付管理/员工借款支付）—— 出纳放款链路对接说明 # 员工借款支付（支付管理/员工借款支付）—— 出纳放款 + 还款核销
> **服务**: hl-order-service-v3（hl-finance 财务模块·出纳域） > **服务**: hl-order-service-v3（hl-finance 财务模块·出纳域 + 员工借款域）
> **端**: 管理后台 > **端**: 管理后台
> **类型**: 📘 对接说明（出纳域接口本次**无变更**，仅说明员工借款支付页怎么接） > **类型**: 📘 对接说明（出纳域接口复用 + 员工借款还款核销端点）
> **日期**: 2026-09-13 > **日期**: 2026-09-13
> **关联**: Epic #7520 / PR #7549；菜单挂载 PR #7642（均已合并 dev-v3） > **关联**: Epic #7520；PR #7549 / #7557 / #7566；菜单挂载 PR #7642（均已合并 dev-v3）
## 一、接口背景 ## 一、接口背景
员工借款单 `APPROVED`（审批通过）后进入**出纳待放款队列**，由出纳登记线下放款、回写借款单 PAID。员工借款支付**不单独建接口**，复用财务统一出纳接口 `/admin/finance/cashier/*`，按 `payType / bizType = STAFF_LOAN` 路由出员工借款这一类的待放款/已放款数据。 员工借款单 `APPROVED`（审批通过）后进入**出纳待放款队列**，出纳登记线下放款（系统不真付款，只记已付）、回写借款单 PAID；放款后员工以**现金还款**或**报销冲抵**核销，直至 SETTLED。这些"放款 + 核销"动作对应原型菜单「支付管理 / 员工借款支付」（原型 notice：*"员工借款审批通过后进入本队列，出纳在此登记线下付款流水…以现金还款或报销冲抵核销"*）。
借款的**申请与审批**在「付款管理 / 员工借款」，见配套 changelog《员工借款（付款管理/员工借款）》。
## 二、菜单↔功能↔接口 对应表 ## 二、菜单↔功能↔接口 对应表
| 菜单 | 功能 | 接口 | | 菜单 | 功能 | 接口 |
|---|---|---| |---|---|---|
| 支付管理/员工借款支付 | 待放款队列 | `GET /admin/finance/cashier/queue?payType=STAFF_LOAN` | | 支付管理/员工借款支付 | 待放款队列 | `GET /admin/finance/cashier/queue?payType=STAFF_LOAN` |
| 支付管理/员工借款支付 | 登记放款 | `POST /admin/finance/cashier/pay`（bizType=STAFF_LOAN） | | 支付管理/员工借款支付 | 登记放款（出纳放款） | `POST /admin/finance/cashier/pay`（bizType=STAFF_LOAN） |
| 支付管理/员工借款支付 | 已放款台账 | `GET /admin/finance/cashier/payments/page?bizType=STAFF_LOAN` | | 支付管理/员工借款支付 | 已放款台账 | `GET /admin/finance/cashier/payments/page?bizType=STAFF_LOAN` |
| 支付管理/员工借款支付 | **还款核销·现金/转账登记** | `POST /admin/finance/staff-loans/{id}/repays` |
| 支付管理/员工借款支付 | **还款核销·红冲（撤销）** | `DELETE /admin/finance/staff-loans/repays/{repayId}` |
| 支付管理/员工借款支付 | **还款核销·报销冲抵** | 报销单 `offsetLoanIds`（见《费用报销》） |
> 菜单 path（已挂载）：员工借款支付 = `/finance/pay/staff-loan`。 > 菜单 path（已挂载）：员工借款支付 = `/finance/pay/staff-loan`。
## 三、放款链路（借款视角） ## 三、放款链路（借款视角）
``` ```
借款单 approve(APPROVED) → 出纳队列出现该待放款单 → 出纳登记放款(pay, bizType=STAFF_LOAN) 借款单 approve(APPROVED) → 出纳队列出现该待放款单 → 出纳登记放款(cashier/pay, bizType=STAFF_LOAN)
→ 记资金流水 OUT + 回写借款单 PAID（落 fund_account_id/paid_at）+ 重算账户结存 → 记资金流水 OUT + 回写借款单 PAID（落 fund_account_id/paid_at）+ 重算账户结存
→ 已放款台账可查 / 借款详情 paidAt+fundAccountId 回显 → 已放款台账可查 / 借款详情 paidAt+fundAccountId 回显
``` ```
## 四、涉及接口（均为出纳域现有接口，按 STAFF_LOAN 过滤） ## 四、放款接口（出纳域现有接口，按 STAFF_LOAN 过滤）
### ① 出纳待放款队列 — `GET /admin/finance/cashier/queue` ### ① 出纳待放款队列 — `GET /admin/finance/cashier/queue`
- 入参：`payType=STAFF_LOAN`（员工借款）+ page/pageSize - 入参：`payType=STAFF_LOAN`（员工借款）+ page/pageSize
@@ -63,27 +68,103 @@ base: "dev-v3"
- 入参：`bizType=STAFF_LOAN` + page/pageSize - 入参：`bizType=STAFF_LOAN` + page/pageSize
- **员工借款支付页"已放款"列表 = 本接口 bizType=STAFF_LOAN** - **员工借款支付页"已放款"列表 = 本接口 bizType=STAFF_LOAN**
## 五、字段对接要点 ## 五、还款核销（借款域接口）
放款后员工还款，核销至 SETTLED。两条通道：
### ① 现金/转账还款登记 — `POST /admin/finance/staff-loans/{id}/repays`
记资金流水 IN（钱回账户）+ CAS 重算借款状态（SUM<amount→SETTLING；SUM≥amount→SETTLED）。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| repayWay | String | ✅ | 还款方式：`CASH` 现金 / `TRANSFER` 转账（**EXPENSE_OFFSET 不收** → 599110，报销冲销由报销域自动产生） |
| amount | BigDecimal | ✅ | 还款金额 >0，超剩余余额 → 599106 |
| fundAccountId | Long(String) | ✅ | 入账资金账户（关联接口②） |
| voucherUrl | String | 否 | 还款凭证影像 URL |
| repaidAt | DateTime | 否 | 还款时间（默认当前时间） |
返 `{id}`。
### ② 还款记录查询 — `GET /admin/finance/staff-loans/{id}/repays`
→ `List<StaffLoanRepayRespVO>`：id/repayNo(HK- 前缀)/loanId/amount/repayWay/repayWayName/fundAccountId(EXPENSE_OFFSET 恒 null)/voucherUrl/repaidAt/createTime。
### ③ 还款红冲（撤销）— `DELETE /admin/finance/staff-loans/repays/{repayId}`
反向 OUT 流水 + 软删还款行 + 状态回退。**EXPENSE_OFFSET 行不可手工红冲** → 599111。
### ④ 报销冲抵（不产生资金流水）
报销单勾选 `offsetLoanIds` 冲抵本申请人名下借款 → 生成 EXPENSE_OFFSET 还款行（不记资金流水），报销 reject/delete/update 时回冲。详见《费用报销》changelog。
## 六、字段对接要点
| 前端展示 | 来源 | | 前端展示 | 来源 |
|---|---| |---|---|
| 待放款列表 | `cashier/queue?payType=STAFF_LOAN` | | 待放款列表 | `cashier/queue?payType=STAFF_LOAN` |
| 已放款列表 | `cashier/payments/page?bizType=STAFF_LOAN` | | 已放款列表 | `cashier/payments/page?bizType=STAFF_LOAN` |
| 登记放款动作 | `cashier/pay`（bizType=STAFF_LOAN） | | 登记放款动作 | `cashier/pay`（bizType=STAFF_LOAN） |
| 单张借款的放款结果（放款时间/出账账户） | 借款详情 `GET /admin/finance/staff-loans/{id}` 的 `paidAt` / `fundAccountId`（见员工借款篇） | | 还款核销（现金/转账） | `staff-loans/{id}/repays` POST |
| 还款记录/核销进度 | `staff-loans/{id}/repays` GET / 借款详情 repayRecords |
| 还款红冲 | `staff-loans/repays/{repayId}` DELETE |
## 六、注意事项 ## 七、错误码（HTTP 恒 200，判 code，按 message 原样提示）
1. 员工借款支付复用统一出纳队列/付款/台账接口，**不要**为员工借款单独写支付接口；靠 `payType/bizType=STAFF_LOAN` 区分业务类型。 **放款（出纳域）**：598602 借款单已放款不可重复 / 598607 bizType 非法（文案含 STAFF_LOAN）等既有码。
**还款核销（借款域）**：
| code | message | 触发 |
|---|---|---|
| 599106 | 还款金额超过借款剩余余额 | 还款 amount>balanceAmt |
| 599108 | 还款单号生成冲突，请重试 | 还款单号撞号 |
| 599109 | 还款记录不存在或已撤销 | repayId 无效 |
| 599110 | 还款方式非法（仅支持现金/转账） | 手工还款传 EXPENSE_OFFSET |
| 599111 | 报销冲销还款不可手工撤销 | 红冲 EXPENSE_OFFSET 行 |
## 八、示例
### 典型·登记放款
```json
POST /admin/finance/cashier/pay
{ "bizType":"STAFF_LOAN", "bizId":"<借款单ID>", "fundAccountId":"2095340438490583041",
"amount":5000.00, "fee":0, "payDate":"2026-09-13", "voucherUrl":"https://oss/pay.jpg" }
→ 记资金流水 OUT + 借款单 APPROVED→PAID
```
### 典型·现金还款核销
```json
POST /admin/finance/staff-loans/{id}/repays
{ "repayWay":"CASH", "amount":2000.00, "fundAccountId":"2095340438490583041" }
→ 记资金流水 IN + 重算状态（SUM<amount→SETTLING；SUM≥amount→SETTLED）
```
### 异常·还款超额 / 红冲冲销行
```json
还款 amount 超 balanceAmt → { "code":599106, "message":"还款金额超过借款剩余余额" }
手工还款传 EXPENSE_OFFSET → { "code":599110, "message":"还款方式非法（仅支持现金/转账）" }
红冲 EXPENSE_OFFSET 还款行 → { "code":599111, "message":"报销冲销还款不可手工撤销" }
```
## 九、注意事项
1. 员工借款支付**放款**复用统一出纳队列/付款/台账接口，**不要**为员工借款单独写放款接口；靠 `payType/bizType=STAFF_LOAN` 区分业务类型。
2. 放款金额以借款单 `amount`（全额）为准——员工借款无"冲抵差额"概念（报销才有 payableAmt），放款即全额。 2. 放款金额以借款单 `amount`（全额）为准——员工借款无"冲抵差额"概念（报销才有 payableAmt），放款即全额。
3. 放款凭证（出纳回单）通过 `cashier/pay` 的 voucherUrl 上传；与借款"申请凭证"voucherUrl 是两个不同字段。 3. 放款凭证（出纳回单）经 `cashier/pay` 的 voucherUrl 上传；与借款"申请凭证"voucherUrl 是两个不同字段。
4. 出账账户下拉用资金账户接口（`GET /admin/finance/fund-accounts/options`，取启用账户）。 4. 还款核销的 `fundAccountId` 是**入账**账户（钱还回来进哪个账户），与放款的出账账户方向相反。
5. 错误码：598607（bizType 非法文案含 STAFF_LOAN）/ 598602（借款单已放款不可重复）等出纳域既有码，按 message 原样提示。 5. 报销冲销（EXPENSE_OFFSET）还款行不记资金流水、不可手工红冲，由报销域全生命周期管理。
## 七、关联 / 联系人 ## 十、关联接口（前端对接数据源，均现成）
- 员工借款（申请+核销）changelog：`13_staffloan_员工借款申请与核销-新增接口-管理后台.md` **② 资金账户下拉（放款出账 / 还款入账账户）** — `GET /admin/finance/fund-accounts/options`
- Epic：https://git.1814.love:8443/wx/HL/issues/7520 ｜ PR：https://git.1814.love:8443/wx/HL/pulls/7549 - 出参启用资金账户，选中取 fundAccountId 传 `cashier/pay` 或还款 `fundAccountId`
## 十一、关联 / 联系人
- 员工借款（申请+审批）changelog：`13_staffloan_员工借款申请与审批-新增接口-管理后台.md`
- Epic：https://git.1814.love:8443/wx/HL/issues/7520
- PR：https://git.1814.love:8443/wx/HL/pulls/7549 ｜ /7557 ｜ /7566
- 菜单挂载：https://git.1814.love:8443/wx/HL/pulls/7642（Issue #7641） - 菜单挂载：https://git.1814.love:8443/wx/HL/pulls/7642（Issue #7641）
- 出纳域（统一收付）：hl-finance `CashierController`（queue/pay/payments/confirm-in） - 出纳域（统一收付）：hl-finance `CashierController`（queue/pay/payments/confirm-in）
- 负责人：yst（腰苏图） - 负责人：yst（腰苏图）
changelogs-v2/2026-09/13_staffloan_员工借款申请与核销-新增接口-管理后台.md → changelogs-v2/2026-09/13_staffloan_员工借款申请与审批-新增接口-管理后台.md
+38 -48
查看文件
@@ -1,7 +1,7 @@
--- ---
schema: "hl-changelog/v2" schema: "hl-changelog/v2"
ticket: "7521/7520" ticket: "7521/7520"
title: "员工借款（付款管理/员工借款）：借款申请+审批+还款核销+报销冲抵 全域接口对接说明" title: "员工借款（付款管理/员工借款）：借款申请+审批（手工推进状态）+ 核销进度只读 + 报销冲抵选借款"
consumer: "admin" consumer: "admin"
author: "yst" author: "yst"
change_type: "新增接口" change_type: "新增接口"
@@ -12,12 +12,12 @@ frontend_owner: "mmg"
frontend_ref: "eb6812c2ce0d001d6f8f4b6b7716741edb64ecff" frontend_ref: "eb6812c2ce0d001d6f8f4b6b7716741edb64ecff"
target_release: "" target_release: ""
verified_at: "2026-09-13" verified_at: "2026-09-13"
status_note: "员工借款域后端已全量接通（Epic #7520 四 PR：#7543 CRUD+审批 / #7549 出纳放款 / #7557 还款核销 / #7566 报销冲抵）。本篇覆盖「付款管理/员工借款」菜单的申请+审批+核销+冲抵（/admin/finance/staff-loans 全域）；出纳放款见配套《员工借款支付》篇。菜单 V20260913_001 已挂载（PR #7642）。 前端已交付(eb6812c2):新建 staff-loan API+payable/staff-loan 主域页(列表 statuses+keyword 筛选/新建编辑(员工选择器 staffId)/七态状态机操作/详情含 repayRecords 现金转账行可红冲/PAID-SETTLING 登记还款),报销冲抵勾选接 offsettable+offsetLoanIds(offsetGuard 守卫编辑回填),snowflake 全串;staff-loan.spec 11 例,checkpoint 13 项全绿。" status_note: "员工借款域后端已全量接通（Epic #7520 四 PR：#7543 CRUD+审批 / #7549 出纳放款 / #7557 还款核销 / #7566 报销冲抵）。本篇覆盖「付款管理/员工借款」菜单：借款申请+审批（submit/approve/reject 手工推进状态，approvalInstanceId 留空待后期统一接企微审批流）+ 核销进度只读 + 报销冲抵选借款。出纳放款与还款核销登记见配套《员工借款支付（出纳放款·核销）》篇。菜单 V20260913_001 已挂载（PR #7642）。 前端已交付(eb6812c2):新建 staff-loan API+payable/staff-loan 主域页(列表 statuses+keyword 筛选/新建编辑(员工选择器 staffId)/七态状态机操作/详情含 repayRecords),报销冲抵勾选接 offsettable+offsetLoanIds(offsetGuard 守卫编辑回填),snowflake 全串;staff-loan.spec 11 例,checkpoint 13 项全绿。⚠️前端该版含页内还款登记/红冲，本期归属已按原型修正为出纳侧（支付篇），前端需把还款登记从本页挪走。"
updated_at: "2026-09-13" updated_at: "2026-09-13"
base: "dev-v3" base: "dev-v3"
--- ---
# 员工借款（付款管理/员工借款）—— 申请 + 审批 + 还款核销 + 报销冲抵 # 员工借款（付款管理/员工借款）—— 申请 + 审批 + 核销进度只读
> **服务**: hl-order-service-v3（hl-finance 财务模块·员工借款域） > **服务**: hl-order-service-v3（hl-finance 财务模块·员工借款域）
> **端**: 管理后台 > **端**: 管理后台
@@ -27,18 +27,23 @@ base: "dev-v3"
## 一、接口背景 ## 一、接口背景
员工借款主链：**申请 → 提交 → 审批 → 出纳放款 → 还款核销**。本域在管理后台对应原型菜单「付款管理 / 员工借款」，承载借款申请、审批、还款核销（现金/转账）、报销冲抵选借款四块功能。出纳放款（登记线下付款流水）在「支付管理 / 员工借款支付」，见配套 changelog《员工借款支付（出纳放款）》。 员工借款主链：**申请 → 提交 → 审批 → 出纳放款 → 还款核销**。本域在管理后台对应原型菜单「付款管理 / 员工借款」，承载**借款申请、审批、核销进度查看（只读）、报销冲抵选借款**四块。
> ⚠️ **还款核销的"登记"动作不在本页**：现金/转账还款登记、报销冲抵的执行发生在「支付管理 / 员工借款支付」（出纳侧），见配套 changelog《员工借款支付（出纳放款·核销）》。本页只**看**核销进度（已核销金额 / 借款余额 / 还款记录），不做还款登记。
> ⚠️ **审批本期为手工推进状态**：`approve`/`reject` 直接改状态推进，**暂不接企业微信审批流**；详情出参 `approvalInstanceId`（企微审批实例号）本期**留空**，为后期统一接入审批流预留。
## 二、菜单↔功能↔接口 对应表 ## 二、菜单↔功能↔接口 对应表
| 菜单 | 功能 | 接口 | | 菜单 | 功能 | 接口 |
|---|---|---| |---|---|---|
| 付款管理/员工借款 | 借款单列表/新建/详情/编辑/删除 | `GET /page`、`POST /`、`GET /{id}`、`PUT /{id}`、`DELETE /{id}` | | 付款管理/员工借款 | 借款单列表/新建/详情/编辑/删除 | `GET /page`、`POST /`、`GET /{id}`、`PUT /{id}`、`DELETE /{id}` |
| 付款管理/员工借款 | 提交审批 / 批准 / 驳回 | `PUT /{id}/submit`、`PUT /{id}/approve`、`PUT /{id}/reject` | | 付款管理/员工借款 | **审批**：提交 / 批准 / 驳回（手工推进状态） | `PUT /{id}/submit`、`PUT /{id}/approve`、`PUT /{id}/reject` |
| 付款管理/员工借款 | 还款核销（现金/转账）登记/列表/红冲 | `POST /{id}/repays`、`GET /{id}/repays`、`DELETE /repays/{repayId}` | | 付款管理/员工借款 | 核销进度查看（还款记录只读） | `GET /{id}`（详情含 repayRecords）、`GET /{id}/repays` |
| 付款管理/员工借款 | 报销冲抵——查某员工可冲抵借款 | `GET /offsettable?staffId=` | | 付款管理/员工借款 | 报销冲抵——查某员工可冲抵借款 | `GET /offsettable?staffId=` |
> 菜单 path（已挂载）：员工借款 = `/finance/payable/staff-loan`。 > 菜单 path（已挂载）：员工借款 = `/finance/payable/staff-loan`。
> ❌ 本页**不**调 `POST /{id}/repays` / `DELETE /repays/{repayId}`（还款登记/红冲在出纳侧，见支付篇）。
## 三、接口清单（基础路径 `/admin/finance/staff-loans`） ## 三、接口清单（基础路径 `/admin/finance/staff-loans`）
@@ -47,15 +52,15 @@ base: "dev-v3"
| GET | `/page` | 借款单分页 | - | | GET | `/page` | 借款单分页 | - |
| GET | `/offsettable?staffId=` | 可冲抵借款（PAID/SETTLING 且余额>0） | - | | GET | `/offsettable?staffId=` | 可冲抵借款（PAID/SETTLING 且余额>0） | - |
| POST | `/` | 创建借款单（PENDING 草稿）→ `{id}` | - | | POST | `/` | 创建借款单（PENDING 草稿）→ `{id}` | - |
| GET | `/{id}` | 借款单详情（含 repayRecords） | - | | GET | `/{id}` | 借款单详情（含 repayRecords 只读） | - |
| PUT | `/{id}` | 编辑 | 仅 PENDING | | PUT | `/{id}` | 编辑 | 仅 PENDING |
| DELETE | `/{id}` | 软删 | 仅 PENDING | | DELETE | `/{id}` | 软删 | 仅 PENDING |
| PUT | `/{id}/submit` | 提交审批 | PENDING→SUBMITTED | | PUT | `/{id}/submit` | 提交审批 | PENDING→SUBMITTED |
| PUT | `/{id}/approve` | 批准 | SUBMITTED→APPROVED | | PUT | `/{id}/approve` | **批准** | SUBMITTED→APPROVED |
| PUT | `/{id}/reject` | 驳回（body `{reason}` 必填≤512） | SUBMITTED→REJECTED（终态） | | PUT | `/{id}/reject` | **驳回**（body `{reason}` 必填≤512） | SUBMITTED→REJECTED（终态） |
| POST | `/{id}/repays` | 登记还款（现金/转账） | PAID/SETTLING | | GET | `/{id}/repays` | 还款记录列表（**只读**，核销进度） | - |
| GET | `/{id}/repays` | 还款记录列表 | - |
| DELETE | `/repays/{repayId}` | 还款红冲（反向流水+状态回退） | 非 EXPENSE_OFFSET 行 | > `POST /{id}/repays`、`DELETE /repays/{repayId}` 为出纳侧还款登记/红冲，**见支付篇**，本页不用。
## 四、入参 ## 四、入参
@@ -86,27 +91,17 @@ base: "dev-v3"
|---|---|---|---| |---|---|---|---|
| reason | String≤512 | ✅ | 驳回原因 | | reason | String≤512 | ✅ | 驳回原因 |
### 4.4 登记还款 `POST /{id}/repays`
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| repayWay | String | ✅ | 还款方式：`CASH` 现金 / `TRANSFER` 转账（**EXPENSE_OFFSET 不收** → 599110，报销冲销由报销域自动产生） |
| amount | BigDecimal | ✅ | 还款金额 >0，超剩余余额 → 599106 |
| fundAccountId | Long(String) | ✅ | 入账资金账户（关联接口③） |
| voucherUrl | String | 否 | 还款凭证影像 URL |
| repaidAt | DateTime | 否 | 还款时间（默认当前时间） |
## 五、出参 ## 五、出参
### 5.1 Row（分页） ### 5.1 Row（分页）
id、loanNo（JK- 前缀单号）、staffId、staffName、amount、repaidAmt（已还）、balanceAmt（剩余余额）、loanDate、dueDate、status、operatorId、operatorName（经办人=登录人留痕，只读）、createTime id、loanNo（JK- 前缀单号）、staffId、staffName、amount、repaidAmt（**已核销**，只读）、balanceAmt（**借款余额**，只读）、loanDate、dueDate、status、operatorId、operatorName（经办人=登录人留痕，只读）、createTime
### 5.2 Detail（详情）= Row 全字段 + 以下 ### 5.2 Detail（详情）= Row 全字段 + 以下
purpose、voucherUrl、fundAccountId、paidAt（放款时间）、approvalInstanceId（本期留空）、rejectReason、repayRecords[] purpose、voucherUrl、fundAccountId（放款出账账户，出纳放款后回写）、paidAt（放款时间）、**approvalInstanceId（企微审批实例号，本期留空）**、rejectReason、repayRecords[]（还款记录，只读）
### 5.3 repayRecords[]（还款记录） ### 5.3 repayRecords[]（还款记录，只读）
| 字段 | 类型 | 说明 | | 字段 | 类型 | 说明 |
|---|---|---| |---|---|---|
@@ -128,9 +123,11 @@ id、loanNo、amount、repaidAmt、balanceAmt（**可冲上限**）、loanDate
| 字段 | 取值 | | 字段 | 取值 |
|---|---| |---|---|
| status / statuses | PENDING 草稿 / SUBMITTED 审批中 / APPROVED 已批准 / REJECTED 已驳回（终态）/ PAID 已放款 / SETTLING 核销中 / SETTLED 已核销 | | status / statuses | PENDING 草稿 / SUBMITTED 审批中 / APPROVED 已批准 / REJECTED 已驳回（终态）/ PAID 已放款 / SETTLING 核销中 / SETTLED 已核销 |
| repayWay | CASH 现金 / TRANSFER 转账 / EXPENSE_OFFSET 报销冲销（系统产生，手工还款不收） | | repayWay | CASH 现金 / TRANSFER 转账 / EXPENSE_OFFSET 报销冲销（系统产生） |
**状态机**：`PENDING → SUBMITTED → APPROVED / REJECTED(终态) →(出纳放款) PAID →(有还款未清) SETTLING →(SUM≥amount) SETTLED`。 **状态机**：`PENDING → SUBMITTED → APPROVED / REJECTED(终态) →(出纳放款) PAID →(有还款未清) SETTLING →(SUM≥amount) SETTLED`。
- 本页负责 `PENDING→SUBMITTED→APPROVED/REJECTED` 段（申请+审批，手工推进）。
- `APPROVED→PAID` 由出纳放款触发、`PAID→SETTLING→SETTLED` 由还款核销触发（均在支付篇）。
## 七、错误码（HTTP 恒 200，判 code，按 message 原样提示） ## 七、错误码（HTTP 恒 200，判 code，按 message 原样提示）
@@ -141,15 +138,12 @@ id、loanNo、amount、repaidAmt、balanceAmt（**可冲上限**）、loanDate
| 599103 | 借款金额无效（须大于0） | amount≤0 | | 599103 | 借款金额无效（须大于0） | amount≤0 |
| 599104 | 借款人非法（不存在或未登记真名） | staffId 查不到/无企微真名 | | 599104 | 借款人非法（不存在或未登记真名） | staffId 查不到/无企微真名 |
| 599105 | 借款单号生成冲突，请重试 | 单号并发撞号（重试即可） | | 599105 | 借款单号生成冲突，请重试 | 单号并发撞号（重试即可） |
| 599106 | 还款金额超过借款剩余余额 | 还款 amount>balanceAmt |
| 599107 | 借款可冲余额不足，请重新勾选 | 报销冲抵勾选超额 | | 599107 | 借款可冲余额不足，请重新勾选 | 报销冲抵勾选超额 |
| 599108 | 还款单号生成冲突，请重试 | 还款单号撞号 |
| 599109 | 还款记录不存在或已撤销 | repayId 无效 |
| 599110 | 还款方式非法（仅支持现金/转账） | 手工还款传 EXPENSE_OFFSET |
| 599111 | 报销冲销还款不可手工撤销 | 红冲 EXPENSE_OFFSET 行 |
| 599112 | 勾选冲抵借款时申请人必填 | 报销 offsetLoanIds 非空但 applicantId 空 | | 599112 | 勾选冲抵借款时申请人必填 | 报销 offsetLoanIds 非空但 applicantId 空 |
| 599113 | 勾选借款与报销申请人不一致 | 报销勾选人≠借款人 | | 599113 | 勾选借款与报销申请人不一致 | 报销勾选人≠借款人 |
> 还款登记相关错误码（599106/599108/599109/599110/599111）发生在出纳侧，见支付篇。
## 八、示例 ## 八、示例
### 典型·新建借款单 ### 典型·新建借款单
@@ -162,37 +156,36 @@ POST /admin/finance/staff-loans
详情出参含：loanNo="JK-20260913-0001"、staffName="金卫"、status="PENDING" 详情出参含：loanNo="JK-20260913-0001"、staffName="金卫"、status="PENDING"
``` ```
### 典型·登记现金还款 ### 典型·审批（手工推进状态，不接企微）
```json ```
POST /admin/finance/staff-loans/{id}/repays PUT /admin/finance/staff-loans/{id}/submit → PENDING→SUBMITTED
{ "repayWay":"CASH", "amount":2000.00, "fundAccountId":"2095340438490583041" } PUT /admin/finance/staff-loans/{id}/approve → SUBMITTED→APPROVED（批准后进出纳待放款队列）
→ 记资金流水 IN + 重算状态（SUM<amount → SETTLING；SUM≥amount → SETTLED） PUT /admin/finance/staff-loans/{id}/reject body {"reason":"事由不充分"} → SUBMITTED→REJECTED（终态）
``` ```
### 异常·借款人非法 / 还款超额 ### 异常·借款人非法 / 状态非法
```json ```json
{ "staffId":"999...", ... } → { "code":599104, "message":"借款人非法（不存在或未登记真名）" } { "staffId":"999...", ... } → { "code":599104, "message":"借款人非法（不存在或未登记真名）" }
还款 amount 超 balanceAmt → { "code":599106, "message":"还款金额超过借款剩余余额" } 对 PENDING 单 approve → { "code":599102, "message":"借款单状态非法，当前状态不允许此操作" }
手工还款传 EXPENSE_OFFSET → { "code":599110, "message":"还款方式非法（仅支持现金/转账）" }
``` ```
## 九、业务边界 ## 九、业务边界
- staffName / operatorName 为后端反查企微名落的快照/展示值，**前端不要传**，只读。 - staffName / operatorName 为后端反查企微名落的快照/展示值，**前端不要传**，只读。
- `operatorId/operatorName` = 当前登录人（created_by）留痕，只读透出。 - `operatorId/operatorName` = 当前登录人（created_by）留痕，只读透出。
- 报销冲销（EXPENSE_OFFSET）还款行由报销域产生、**不记资金流水**（fundAccountId 恒 null），不可手工红冲（599111）。 - `approvalInstanceId` 本期恒 null（审批手工推进），后期接企微审批流后由后端回写，前端只需预留展示位。
- 还款红冲走 `DELETE /repays/{repayId}`：反向 OUT 流水 + 软删 + 状态回退，仅现金/转账行可冲。 - 已核销金额 repaidAmt / 借款余额 balanceAmt 不存列，由还款记录现算，**只读**。
- 已还金额不存列，`repaidAmt/balanceAmt` 由还款记录现算。 - 报销冲销（EXPENSE_OFFSET）还款行由报销域产生、不记资金流水（fundAccountId 恒 null），只读展示。
## 十、报销冲抵（跨域勾稽） ## 十、报销冲抵（跨域勾稽）
报销单 create/update 入参 `offsetLoanIds`（List\<Long\>）勾选冲抵本申请人名下借款：非空时 applicantId 必填（599112）、勾选人须=借款人（599113）、按勾选顺序 use=min（报销剩余额度，借款 balanceAmt）。出参 `offsetLoanAmt`（冲销额）+ `payableAmt = amount − offsetLoanAmt`（出纳按应付差额付款）。详见《费用报销》changelog。 报销单 create/update 入参 `offsetLoanIds`（List\<Long\>）勾选冲抵本申请人名下借款：非空时 applicantId 必填（599112）、勾选人须=借款人（599113）、按勾选顺序 use=min（报销剩余额度，借款 balanceAmt）。出参 `offsetLoanAmt`（冲销额）+ `payableAmt = amount − offsetLoanAmt`（出纳按应付差额付款）。本页用 `GET /offsettable?staffId=` 供报销勾选借款。详见《费用报销》changelog。
## 十一、影响评估 / 回滚 ## 十一、影响评估 / 回滚
- 新增域接口，无破坏性。前端按本篇对接「付款管理/员工借款」页。 - 新增域接口，无破坏性。前端按本篇对接「付款管理/员工借款」页（申请+审批+核销进度只读）。
- 回滚：菜单下线（sys_menu）+ 接口不下线即可；表 fin_staff_loan / fin_staff_loan_repay 保留无影响。 - 回滚：菜单下线（sys_menu）+ 接口不下线即可；表 fin_staff_loan / fin_staff_loan_repay 保留无影响。
## 十二、关联接口（前端对接数据源，均现成） ## 十二、关联接口（前端对接数据源，均现成）
@@ -203,13 +196,10 @@ POST /admin/finance/staff-loans/{id}/repays
**② 报销单（冲抵勾稽）** — `GET/POST /admin/finance/expenses`（见《费用报销》changelog，offsetLoanIds/offsetLoanAmt/payableAmt） **② 报销单（冲抵勾稽）** — `GET/POST /admin/finance/expenses`（见《费用报销》changelog，offsetLoanIds/offsetLoanAmt/payableAmt）
**③ 资金账户下拉（还款入账账户）** — `GET /admin/finance/fund-accounts/options`
- 出参启用资金账户，选中取 fundAccountId 传还款 `fundAccountId`
## 十三、关联 / 联系人 ## 十三、关联 / 联系人
- Epic：https://git.1814.love:8443/wx/HL/issues/7520 - Epic：https://git.1814.love:8443/wx/HL/issues/7520
- PR：https://git.1814.love:8443/wx/HL/pulls/7543 ｜ /7549 ｜ /7557 ｜ /7566 - PR：https://git.1814.love:8443/wx/HL/pulls/7543 ｜ /7549 ｜ /7557 ｜ /7566
- 菜单挂载：https://git.1814.love:8443/wx/HL/pulls/7642（Issue #7641） - 菜单挂载：https://git.1814.love:8443/wx/HL/pulls/7642（Issue #7641）
- 配套：《员工借款支付（出纳放款）》；员工选择器 `13_7625_员工选择器接口-新增接口-管理后台.md` - 配套：《员工借款支付（出纳放款·核销）》；员工选择器 `13_7625_员工选择器接口-新增接口-管理后台.md`
- 负责人：yst（腰苏图） - 负责人：yst（腰苏图）