docs(finance): 员工借款两菜单 changelog——申请+核销 / 出纳放款支付

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
2026-09-13 17:01:28 +08:00
@@ -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（腰苏图）