5.4 KiB
5.4 KiB
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 | 7521/7520 | 员工借款支付（支付管理/员工借款支付）：借款审批通过后的出纳放款链路对接说明——队列/登记放款/已放款台账按 STAFF_LOAN 路由 | admin | yst | 修改接口 | deployed | not_required | verified | mmg | eb6812c2ce0d001d6f8f4b6b7716741edb64ecff | 2026-09-13 | 📘 对接说明（出纳域接口本次无变更）：员工借款 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 登记两菜单。 | 2026-09-13 | 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（见员工借款篇） |
六、注意事项
- 员工借款支付复用统一出纳队列/付款/台账接口，不要为员工借款单独写支付接口；靠
payType/bizType=STAFF_LOAN区分业务类型。 - 放款金额以借款单
amount（全额）为准——员工借款无"冲抵差额"概念（报销才有 payableAmt），放款即全额。 - 放款凭证（出纳回单）通过
cashier/pay的 voucherUrl 上传；与借款"申请凭证"voucherUrl 是两个不同字段。 - 出账账户下拉用资金账户接口（
GET /admin/finance/fund-accounts/options，取启用账户）。 - 错误码：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（腰苏图）