yaosutu
edab50a6a8
changelog-filename-gate / validate (push) Failing after 2s
- 费用报销：page 加 statuses 多状态筛选、detail 加 payRecords 付款记录、表单补 applicantId/payeeAccount/voucherUrl、透出经办人 operatorId/operatorName、598705 文案放宽；含部门组织树/员工选择器/所属公司 travel_agency/费用分类 关联接口指引 - 费用支付：出纳域对接说明（queue/pay/payments 按 EXPENSE 路由），接口无变更
78 行
4.0 KiB
Markdown
78 行
4.0 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "expense-pay"
|
||
title: "费用支付（出纳）：报销审批通过后的付款链路对接说明——队列/登记付款/已付台账按 EXPENSE 路由"
|
||
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=EXPENSE 路由。本文给前端费用支付页的对接口径。"
|
||
updated_at: "2026-09-13"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 费用支付（出纳）—— 报销付款链路对接说明
|
||
|
||
> **服务**: hl-order-service-v3（hl-finance 财务模块·出纳域）
|
||
> **端**: 管理后台
|
||
> **类型**: 📘 对接说明（出纳域接口本次**无变更**，仅说明费用支付页怎么接）
|
||
> **日期**: 2026-09-13
|
||
> **关联**: 费用报销 changelog（`13_expense_费用报销多状态与申请人经办人`）
|
||
|
||
## 一、接口背景
|
||
|
||
费用报销单 `APPROVED`（审批通过）后进入**出纳待付款队列**，由出纳登记打款、回写报销单 PAID。费用支付**不单独建接口**，复用财务统一出纳接口 `/admin/finance/cashier/*`，按 `payType / bizType = EXPENSE` 路由出报销这一类的待付/已付数据。
|
||
|
||
## 二、付款链路（报销视角）
|
||
|
||
```
|
||
报销单 approve(APPROVED) → 出纳队列出现该待付单 → 出纳登记付款(pay, bizType=EXPENSE)
|
||
→ 记资金流水 OUT + 回写报销单 PAID + 重算结存 → 已付款台账可查 / 报销详情 payRecords 回显
|
||
```
|
||
|
||
> 报销单若有"冲抵借款"（offsetLoanAmt>0），出纳按 `payableAmt`（应付差额）付款，非全额 amount。
|
||
|
||
## 三、涉及接口（均为出纳域现有接口，按 EXPENSE 过滤）
|
||
|
||
### ① 出纳待付款队列 — `GET /admin/finance/cashier/queue`
|
||
- 入参：`payType=EXPENSE`（费用报销）+ page/pageSize（其余筛选项按 VO）
|
||
- 出参行：报销单号 / 申请人 / 金额（应付 payableAmt）/ 状态 / 等
|
||
- **费用支付页"待付款"列表 = 本接口 payType=EXPENSE**
|
||
|
||
### ② 登记付款 — `POST /admin/finance/cashier/pay`
|
||
- 入参：`bizType=EXPENSE` + `bizId`(报销单ID) + 出账账户 fundAccountId + 金额 + 手续费 + 付款日期 + 凭证 voucherUrl 等
|
||
- 动作：记资金流水 OUT + 回写报销单 PAID + 重算账户结存 + 透支闸校验
|
||
- 幂等/并发：同一报销单重复付款会被状态守卫拦截（已 PAID 不可重复付）
|
||
|
||
### ③ 已付款流水台账 — `GET /admin/finance/cashier/payments/page`
|
||
- 入参：`bizType=EXPENSE` + page/pageSize
|
||
- **费用支付页"已付款"列表 = 本接口 bizType=EXPENSE**
|
||
|
||
## 四、字段对接要点
|
||
|
||
| 前端展示 | 来源 |
|
||
|---|---|
|
||
| 待付款列表 | `cashier/queue?payType=EXPENSE` |
|
||
| 已付款列表 | `cashier/payments/page?bizType=EXPENSE` |
|
||
| 登记付款动作 | `cashier/pay`（bizType=EXPENSE） |
|
||
| 单张报销的付款记录（含付款凭证） | 报销详情 `GET /admin/finance/expenses/{id}` 的 `payRecords`（见报销 changelog） |
|
||
|
||
## 五、注意事项
|
||
|
||
1. 费用支付复用统一出纳队列/付款/台账接口，**不要**为报销单独写支付接口；靠 `payType/bizType=EXPENSE` 区分业务类型。
|
||
2. 付款金额以报销单 `payableAmt`（应付差额）为准（有冲抵借款时 ≠ 报销总额 amount）。
|
||
3. 付款凭证（出纳回单）通过 `cashier/pay` 的 voucherUrl 上传，回显在报销详情 `payRecords[].voucherUrl`，与报销"申请凭证" voucherUrl 是两个不同字段。
|
||
4. 出账账户下拉用资金账户接口（`GET /admin/finance/fund-accounts` 启用项，取 ACTIVE 且非冻结账户）。
|
||
|
||
## 六、关联 / 联系人
|
||
|
||
- 报销单据 changelog：`13_expense_费用报销多状态与申请人经办人-修改接口-管理后台.md`
|
||
- 出纳域（统一收付）：hl-finance `CashierController`（queue/pay/payments/confirm-in）
|
||
- 负责人：yst（腰苏图）
|