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

docs(finance): 员工借款两菜单 changelog——申请+核销 / 出纳放款支付
changelog-filename-gate / validate (push) Failing after 2s
详情

浏览代码 
Epic #7520 四 PR（#7543/#7549/#7557/#7566）员工借款域已全量接通 + 菜单已挂载（PR #7642 / 迁移 V20260913_001）。

- 13_staffloan_员工借款申请与核销-新增接口：「付款管理/员工借款」/admin/finance/staff-loans 12 端点全表 + 状态机 + 错误码 599101-599113
- 13_staffloan_员工借款支付出纳放款-修改接口：「支付管理/员工借款支付」出纳放款对接（cashier bizType=STAFF_LOAN）
- 两篇均含 菜单↔功能↔接口 对照表；借款人下拉统一 GET /admin/user/employee-options；资金账户 fund-accounts/options
这个提交包含在：
yaosutu
2026-09-13 17:01:28 +08:00
父节点 890c8bd454
当前提交 c91730668b
共修改 2 个文件，包含 304 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-09/13_staffloan_员工借款支付出纳放款-修改接口-管理后台.md
+89
查看文件
@@ -0,0 +1,89 @@
---
schema: "hl-changelog/v2"
ticket: "7521/7520"
title: "员工借款支付（支付管理/员工借款支付）：借款审批通过后的出纳放款链路对接说明——队列/登记放款/已放款台账按 STAFF_LOAN 路由"
consumer: "admin"
author: "yst"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "📘 对接说明（出纳域接口本次无变更）：员工借款 APPROVED 后进出纳待放款队列，复用统一出纳接口 /admin/finance/cashier/*，按 payType/bizType=STAFF_LOAN 路由。本文给前端「支付管理/员工借款支付」页的对接口径。菜单 V20260913_001 已挂载（PR #7642）。"
updated_at: "2026-09-13"
base: "dev-v3"
---
# 员工借款支付（支付管理/员工借款支付）—— 出纳放款链路对接说明
> **服务**: hl-order-service-v3（hl-finance 财务模块·出纳域）
> **端**: 管理后台
> **类型**: 📘 对接说明（出纳域接口本次**无变更**，仅说明员工借款支付页怎么接）
> **日期**: 2026-09-13
> **关联**: Epic #7520 / PR #7549；菜单挂载 PR #7642（均已合并 dev-v3）
## 一、接口背景
员工借款单 `APPROVED`（审批通过）后进入**出纳待放款队列**，由出纳登记线下放款、回写借款单 PAID。员工借款支付**不单独建接口**，复用财务统一出纳接口 `/admin/finance/cashier/*`，按 `payType / bizType = STAFF_LOAN` 路由出员工借款这一类的待放款/已放款数据。
## 二、菜单↔功能↔接口 对应表
| 菜单 | 功能 | 接口 |
|---|---|---|
| 支付管理/员工借款支付 | 待放款队列 | `GET /admin/finance/cashier/queue?payType=STAFF_LOAN` |
| 支付管理/员工借款支付 | 登记放款 | `POST /admin/finance/cashier/pay`（bizType=STAFF_LOAN） |
| 支付管理/员工借款支付 | 已放款台账 | `GET /admin/finance/cashier/payments/page?bizType=STAFF_LOAN` |
> 菜单 path（已挂载）：员工借款支付 = `/finance/pay/staff-loan`。
## 三、放款链路（借款视角）
```
借款单 approve(APPROVED) → 出纳队列出现该待放款单 → 出纳登记放款(pay, bizType=STAFF_LOAN)
→ 记资金流水 OUT + 回写借款单 PAID（落 fund_account_id/paid_at）+ 重算账户结存
→ 已放款台账可查 / 借款详情 paidAt+fundAccountId 回显
```
## 四、涉及接口（均为出纳域现有接口，按 STAFF_LOAN 过滤）
### ① 出纳待放款队列 — `GET /admin/finance/cashier/queue`
- 入参：`payType=STAFF_LOAN`（员工借款）+ page/pageSize
- 队列源：fin_staff_loan 状态 APPROVED 的借款单
- **员工借款支付页"待放款"列表 = 本接口 payType=STAFF_LOAN**
### ② 登记放款 — `POST /admin/finance/cashier/pay`
- 入参：`bizType=STAFF_LOAN` + `bizId`(借款单ID) + 出账账户 fundAccountId + 金额 + 手续费 + 付款日期 + 凭证 voucherUrl 等
- 动作：记资金流水 OUT + 回写借款单 APPROVED→PAID（落 fund_account_id/paid_at）+ 重算账户结存
- 并发/幂等：放款前 selectForUpdate 锁借款行 + 锁内校验存在且 APPROVED，已 PAID 不可重复放款（598602）
### ③ 已放款流水台账 — `GET /admin/finance/cashier/payments/page`
- 入参：`bizType=STAFF_LOAN` + page/pageSize
- **员工借款支付页"已放款"列表 = 本接口 bizType=STAFF_LOAN**
## 五、字段对接要点
| 前端展示 | 来源 |
|---|---|
| 待放款列表 | `cashier/queue?payType=STAFF_LOAN` |
| 已放款列表 | `cashier/payments/page?bizType=STAFF_LOAN` |
| 登记放款动作 | `cashier/pay`（bizType=STAFF_LOAN） |
| 单张借款的放款结果（放款时间/出账账户） | 借款详情 `GET /admin/finance/staff-loans/{id}` 的 `paidAt` / `fundAccountId`（见员工借款篇） |
## 六、注意事项
1. 员工借款支付复用统一出纳队列/付款/台账接口，**不要**为员工借款单独写支付接口；靠 `payType/bizType=STAFF_LOAN` 区分业务类型。
2. 放款金额以借款单 `amount`（全额）为准——员工借款无"冲抵差额"概念（报销才有 payableAmt），放款即全额。
3. 放款凭证（出纳回单）通过 `cashier/pay` 的 voucherUrl 上传；与借款"申请凭证"voucherUrl 是两个不同字段。
4. 出账账户下拉用资金账户接口（`GET /admin/finance/fund-accounts/options`，取启用账户）。
5. 错误码：598607（bizType 非法文案含 STAFF_LOAN）/ 598602（借款单已放款不可重复）等出纳域既有码，按 message 原样提示。
## 七、关联 / 联系人
- 员工借款（申请+核销）changelog：`13_staffloan_员工借款申请与核销-新增接口-管理后台.md`
- Epic：https://git.1814.love:8443/wx/HL/issues/7520 ｜ PR：https://git.1814.love:8443/wx/HL/pulls/7549
- 菜单挂载：https://git.1814.love:8443/wx/HL/pulls/7642（Issue #7641）
- 出纳域（统一收付）：hl-finance `CashierController`（queue/pay/payments/confirm-in）
- 负责人：yst（腰苏图）
changelogs-v2/2026-09/13_staffloan_员工借款申请与核销-新增接口-管理后台.md
+215
查看文件
@@ -0,0 +1,215 @@
---
schema: "hl-changelog/v2"
ticket: "7521/7520"
title: "员工借款（付款管理/员工借款）：借款申请+审批+还款核销+报销冲抵 全域接口对接说明"
consumer: "admin"
author: "yst"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "员工借款域后端已全量接通（Epic #7520 四 PR：#7543 CRUD+审批 / #7549 出纳放款 / #7557 还款核销 / #7566 报销冲抵）。本篇覆盖「付款管理/员工借款」菜单的申请+审批+核销+冲抵（/admin/finance/staff-loans 全域）；出纳放款见配套《员工借款支付》篇。菜单 V20260913_001 已挂载（PR #7642）。"
updated_at: "2026-09-13"
base: "dev-v3"
---
# 员工借款（付款管理/员工借款）—— 申请 + 审批 + 还款核销 + 报销冲抵
> **服务**: hl-order-service-v3（hl-finance 财务模块·员工借款域）
> **端**: 管理后台
> **类型**: 🆕 新增接口（员工借款域首次对接说明）
> **日期**: 2026-09-13
> **关联**: Epic #7520；PR #7543 / #7549 / #7557 / #7566；菜单挂载 PR #7642（均已合并 dev-v3）
## 一、接口背景
员工借款主链：**申请 → 提交 → 审批 → 出纳放款 → 还款核销**。本域在管理后台对应原型菜单「付款管理 / 员工借款」，承载借款申请、审批、还款核销（现金/转账）、报销冲抵选借款四块功能。出纳放款（登记线下付款流水）在「支付管理 / 员工借款支付」，见配套 changelog《员工借款支付（出纳放款）》。
## 二、菜单↔功能↔接口 对应表
| 菜单 | 功能 | 接口 |
|---|---|---|
| 付款管理/员工借款 | 借款单列表/新建/详情/编辑/删除 | `GET /page`、`POST /`、`GET /{id}`、`PUT /{id}`、`DELETE /{id}` |
| 付款管理/员工借款 | 提交审批 / 批准 / 驳回 | `PUT /{id}/submit`、`PUT /{id}/approve`、`PUT /{id}/reject` |
| 付款管理/员工借款 | 还款核销（现金/转账）登记/列表/红冲 | `POST /{id}/repays`、`GET /{id}/repays`、`DELETE /repays/{repayId}` |
| 付款管理/员工借款 | 报销冲抵——查某员工可冲抵借款 | `GET /offsettable?staffId=` |
> 菜单 path（已挂载）：员工借款 = `/finance/payable/staff-loan`。
## 三、接口清单（基础路径 `/admin/finance/staff-loans`）
| 方法 | 路径 | 说明 | 状态前置 |
|---|---|---|---|
| GET | `/page` | 借款单分页 | - |
| GET | `/offsettable?staffId=` | 可冲抵借款（PAID/SETTLING 且余额>0） | - |
| POST | `/` | 创建借款单（PENDING 草稿）→ `{id}` | - |
| GET | `/{id}` | 借款单详情（含 repayRecords） | - |
| PUT | `/{id}` | 编辑 | 仅 PENDING |
| DELETE | `/{id}` | 软删 | 仅 PENDING |
| PUT | `/{id}/submit` | 提交审批 | PENDING→SUBMITTED |
| PUT | `/{id}/approve` | 批准 | SUBMITTED→APPROVED |
| PUT | `/{id}/reject` | 驳回（body `{reason}` 必填≤512） | SUBMITTED→REJECTED（终态） |
| POST | `/{id}/repays` | 登记还款（现金/转账） | PAID/SETTLING |
| GET | `/{id}/repays` | 还款记录列表 | - |
| DELETE | `/repays/{repayId}` | 还款红冲（反向流水+状态回退） | 非 EXPENSE_OFFSET 行 |
## 四、入参
### 4.1 分页 `GET /page`
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| status | String | 否 | 单据状态单值 |
| statuses | List\<String\> | 否 | 单据状态多值（IN 查询）。**非空优先于 status；均空=全部** |
| staffId | Long(String) | 否 | 借款人 adminId（空=不限） |
| keyword | String | 否 | 关键字（借款单号 / 借款人姓名模糊） |
| page / pageSize | Integer | 否 | 分页 |
### 4.2 创建 `POST /` / 编辑 `PUT /{id}`（同构）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| staffId | Long(String) | ✅ | 借款人 adminId（员工选择器选，关联接口①）。后端反查企微名落 staffName 快照，查不到/无真名 → 599104 |
| amount | BigDecimal | ✅ | 借款金额 >0（否则 599103） |
| purpose | String≤200 | ✅ | 借款事由 |
| loanDate | Date | 否 | 借款日期 |
| dueDate | Date | 否 | 应还日期 |
| voucherUrl | String≤500 | 否 | 申请凭证影像 URL |
### 4.3 驳回 `PUT /{id}/reject`
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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（分页）
id、loanNo（JK- 前缀单号）、staffId、staffName、amount、repaidAmt（已还）、balanceAmt（剩余余额）、loanDate、dueDate、status、operatorId、operatorName（经办人=登录人留痕，只读）、createTime
### 5.2 Detail（详情）= Row 全字段 + 以下
purpose、voucherUrl、fundAccountId、paidAt（放款时间）、approvalInstanceId（本期留空）、rejectReason、repayRecords[]
### 5.3 repayRecords[]（还款记录）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 还款记录 ID |
| repayNo | String | 还款单号（HK- 前缀） |
| amount | BigDecimal | 还款金额 |
| repayWay | String | 还款方式码 |
| repayWayName | String | 还款方式中文 |
| fundAccountId | String | 入账账户（EXPENSE_OFFSET 恒 null，不记资金流水） |
| voucherUrl | String | 还款凭证 |
| repaidAt | DateTime | 还款时间 |
### 5.4 可冲抵借款 `GET /offsettable` 出参项
id、loanNo、amount、repaidAmt、balanceAmt（**可冲上限**）、loanDate、purpose
## 六、枚举 / 数据字典
| 字段 | 取值 |
|---|---|
| status / statuses | PENDING 草稿 / SUBMITTED 审批中 / APPROVED 已批准 / REJECTED 已驳回（终态）/ PAID 已放款 / SETTLING 核销中 / SETTLED 已核销 |
| repayWay | CASH 现金 / TRANSFER 转账 / EXPENSE_OFFSET 报销冲销（系统产生，手工还款不收） |
**状态机**：`PENDING → SUBMITTED → APPROVED / REJECTED(终态) →(出纳放款) PAID →(有还款未清) SETTLING →(SUM≥amount) SETTLED`。
## 七、错误码（HTTP 恒 200，判 code，按 message 原样提示）
| code | message | 触发 |
|---|---|---|
| 599101 | 借款单不存在 | id 无效 |
| 599102 | 借款单状态非法，当前状态不允许此操作 | 状态前置不满足 |
| 599103 | 借款金额无效（须大于0） | amount≤0 |
| 599104 | 借款人非法（不存在或未登记真名） | staffId 查不到/无企微真名 |
| 599105 | 借款单号生成冲突，请重试 | 单号并发撞号（重试即可） |
| 599106 | 还款金额超过借款剩余余额 | 还款 amount>balanceAmt |
| 599107 | 借款可冲余额不足，请重新勾选 | 报销冲抵勾选超额 |
| 599108 | 还款单号生成冲突，请重试 | 还款单号撞号 |
| 599109 | 还款记录不存在或已撤销 | repayId 无效 |
| 599110 | 还款方式非法（仅支持现金/转账） | 手工还款传 EXPENSE_OFFSET |
| 599111 | 报销冲销还款不可手工撤销 | 红冲 EXPENSE_OFFSET 行 |
| 599112 | 勾选冲抵借款时申请人必填 | 报销 offsetLoanIds 非空但 applicantId 空 |
| 599113 | 勾选借款与报销申请人不一致 | 报销勾选人≠借款人 |
## 八、示例
### 典型·新建借款单
```json
POST /admin/finance/staff-loans
{ "staffId":"2083457702519873537", "amount":5000.00, "purpose":"出差备用金",
"loanDate":"2026-09-13", "dueDate":"2026-10-13" }
→ 200 { "code":200, "data":{ "id":"..." } }
详情出参含：loanNo="JK-20260913-0001"、staffName="金卫"、status="PENDING"
```
### 典型·登记现金还款
```json
POST /admin/finance/staff-loans/{id}/repays
{ "repayWay":"CASH", "amount":2000.00, "fundAccountId":"2095340438490583041" }
→ 记资金流水 IN + 重算状态（SUM<amount → SETTLING；SUM≥amount → SETTLED）
```
### 异常·借款人非法 / 还款超额
```json
{ "staffId":"999...", ... } → { "code":599104, "message":"借款人非法（不存在或未登记真名）" }
还款 amount 超 balanceAmt → { "code":599106, "message":"还款金额超过借款剩余余额" }
手工还款传 EXPENSE_OFFSET → { "code":599110, "message":"还款方式非法（仅支持现金/转账）" }
```
## 九、业务边界
- staffName / operatorName 为后端反查企微名落的快照/展示值，**前端不要传**，只读。
- `operatorId/operatorName` = 当前登录人（created_by）留痕，只读透出。
- 报销冲销（EXPENSE_OFFSET）还款行由报销域产生、**不记资金流水**（fundAccountId 恒 null），不可手工红冲（599111）。
- 还款红冲走 `DELETE /repays/{repayId}`：反向 OUT 流水 + 软删 + 状态回退，仅现金/转账行可冲。
- 已还金额不存列，`repaidAmt/balanceAmt` 由还款记录现算。
## 十、报销冲抵（跨域勾稽）
报销单 create/update 入参 `offsetLoanIds`（List\<Long\>）勾选冲抵本申请人名下借款：非空时 applicantId 必填（599112）、勾选人须=借款人（599113）、按勾选顺序 use=min（报销剩余额度，借款 balanceAmt）。出参 `offsetLoanAmt`（冲销额）+ `payableAmt = amount − offsetLoanAmt`（出纳按应付差额付款）。详见《费用报销》changelog。
## 十一、影响评估 / 回滚
- 新增域接口，无破坏性。前端按本篇对接「付款管理/员工借款」页。
- 回滚：菜单下线（sys_menu）+ 接口不下线即可；表 fin_staff_loan / fin_staff_loan_repay 保留无影响。
## 十二、关联接口（前端对接数据源，均现成）
**① 借款人下拉（员工选择器）** — `GET /admin/user/employee-options`（🆕 不限角色，PR #7627 / changelog `13_7625`）
- 入参：deptId / keyword / page / pageSize；出参：adminId、username、enterpriseWechatName、deptNames
- 选中取 `adminId` 传 `staffId`
**② 报销单（冲抵勾稽）** — `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
- PR：https://git.1814.love:8443/wx/HL/pulls/7543 ｜ /7549 ｜ /7557 ｜ /7566
- 菜单挂载：https://git.1814.love:8443/wx/HL/pulls/7642（Issue #7641）
- 配套：《员工借款支付（出纳放款）》；员工选择器 `13_7625_员工选择器接口-新增接口-管理后台.md`
- 负责人：yst（腰苏图）