wx/hl-api-changelog

派生 0

文件

T

Mimingguang b7015c1ff4

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog-v2): #7842 出纳拆壳合芯前端 hl-admin 已交付,回写 verified+frontend_ref(96894dd7)

2026-09-17 11:19:18 +08:00

35 KiB

原始文件 Blame 文件历史

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	finance-cashier-split-shell	出纳支付接口「拆壳合芯」——8 页签独立强类型端点（删 3 旧端点 404 + 增 18 新端点）	admin	yst(GIT)	修改接口	merged	pending	verified	mmg	96894dd74610fc2ab85c4ed35f5b83fd34851acc		2026-09-17	出纳支付管理 8 页签从「1 套合一接口靠 payType/bizType 路由」拆为「8 页签各自独立路径 + 强类型出参」。①删 3 旧端点（GET /cashier/queue、POST /cashier/pay、POST /cashier/confirm-in，调用一律 404）；②增 18 新端点（queue×8 + pay×8 + confirm-in×2，路径前缀 /cashier/{nonbiz,payment,prepay,expense,staff-loan,reimburse,advance,company-loan}）；③台账 GET /cashier/payments/page 不变；④入参删 payType/bizType（路径即类型）；⑤队列出参消灭 unitName/category 槽位复用，各页签用业务真名字段（supplierName/staffName/reporterName 等）；⑥ADVANCE 司导预支 2 端点为预留空壳一律 598607，前端勿接。已合并 dev-v3（PR #7855）。前端 hl-admin 已交付(2026-09-17):cashier.js 按页签路径重写(ADVANCE 抛错勿接),confirm-in 拆 nonbiz/reimburse 两函数,payload 删 bizType;CashierQueuePage 队列列改各页签真名兜底链,validator 扩 PAYMENT;定向 vitest 41/41+checkpoint 全量过。	2026-09-17	dev-v3

【修改接口·管理后台】出纳支付接口「拆壳合芯」——8 页签独立端点 (#7842)

PR: #7855 | 服务: hl-order-service-v3（hl-finance 模块） | 更新时间: 2026-09-17

1. 接口背景

出纳支付管理 8 个页签（业务外支出 / 应付款 / 预付款 / 费用报销 / 员工借款 / 报账款 / 司导预支 / 公司借款）原来共用一套合一接口：队列靠 query 参数 payType 路由，登记付款 / 收款确认靠 body 字段 bizType 路由。合一队列出参用 unitId / unitName / category / categoryName 四个「槽位」复用装 8 类单据的业务字段——同一个 unitName 在业务外支出里是「外部单位」、在应付款里是「供应商」、在员工借款里是「借款人」，前端无法生成精确强类型，字段语义靠猜。

本次「拆壳合芯」：8 页签各自独立路径 + 独立强类型出参（业务真名字段），入参删 payType / bizType（路径即类型）。旧 3 个合一端点直接删除，调用一律 404，前端 8 页签必须同步改调新路径。

2. 变更清单

2.1 删除（3 个旧合一端点，调用一律 404）

#	方法	路径	变更类型	说明
1	GET	`/admin/finance/cashier/queue`	⚠️ 删除	旧合一待付款队列（`payType` 路由）——旧路径已删，调用一律 404
2	POST	`/admin/finance/cashier/pay`	⚠️ 删除	旧合一登记付款（`bizType` 路由）——旧路径已删，调用一律 404
3	POST	`/admin/finance/cashier/confirm-in`	⚠️ 删除	旧合一收款确认（`bizType` 路由）——旧路径已删，调用一律 404

2.2 新增（18 个页签端点）

#	方法	路径	页签	说明
1	GET	`/admin/finance/cashier/nonbiz/queue`	业务外支出	待付款队列
2	POST	`/admin/finance/cashier/nonbiz/pay`	业务外支出	登记付款
3	POST	`/admin/finance/cashier/nonbiz/confirm-in`	业务外支出	业务外收入收款确认入账
4	GET	`/admin/finance/cashier/payment/queue`	应付款	待付款队列
5	POST	`/admin/finance/cashier/payment/pay`	应付款	登记付款
6	GET	`/admin/finance/cashier/prepay/queue`	预付款	待付款队列
7	POST	`/admin/finance/cashier/prepay/pay`	预付款	登记付款
8	GET	`/admin/finance/cashier/expense/queue`	费用报销	待付款队列
9	POST	`/admin/finance/cashier/expense/pay`	费用报销	登记付款
10	GET	`/admin/finance/cashier/staff-loan/queue`	员工借款	待放款队列
11	POST	`/admin/finance/cashier/staff-loan/pay`	员工借款	登记放款
12	GET	`/admin/finance/cashier/reimburse/queue`	报账款	待付款队列（仅 direction=PAYABLE）
13	POST	`/admin/finance/cashier/reimburse/pay`	报账款	登记付款（仅 direction=PAYABLE）
14	POST	`/admin/finance/cashier/reimburse/confirm-in`	报账款	报账回款收款确认（仅 direction=RECEIVABLE，支持部分收款）
15	GET	`/admin/finance/cashier/advance/queue`	司导预支	⚠️ 预留未接通，一律返 598607，前端勿接
16	POST	`/admin/finance/cashier/advance/pay`	司导预支	⚠️ 预留未接通，一律返 598607，前端勿接
17	GET	`/admin/finance/cashier/company-loan/queue`	公司借款	待付款队列（仅 direction=OUT 借出单）
18	POST	`/admin/finance/cashier/company-loan/pay`	公司借款	借出放款（仅 direction=OUT）

2.3 保留不变（1 个台账端点）

方法	路径	说明
GET	`/admin/finance/cashier/payments/page`	已付款流水台账，各页签共用，入参出参均不变，前端无需改

3. 接口详情（按页签分节）

全 18 端点共性：认证需管理后台 JWT；幂等性 是——付款 / 收款动作为 APPROVED → PAID（或 RECEIVED）CAS 条件更新，并发重复提交后到的请求返 598602；限流无。

3.1 业务外支出（NONBIZ）——3 端点

使用场景：业务外支出单（fin_nonbiz_flow direction=OUT）审批通过（APPROVED）后，出纳在本页签拉队列、登记付款；业务外收入单（direction=IN）APPROVED 后在本页签做收款确认入账。

方法	路径	说明
GET	`/admin/finance/cashier/nonbiz/queue`	待付款队列（direction=OUT 且 APPROVED 分页）
POST	`/admin/finance/cashier/nonbiz/pay`	登记付款（记资金流水 OUT + 回写 PAID；金额锁死 = 审批实付 actual_amount）
POST	`/admin/finance/cashier/nonbiz/confirm-in`	业务外收入收款确认入账（direction=IN 且 APPROVED 批准即入账：记 IN 流水 + 回写 PAID，金额 = 单据实收 actual_amount，入参无 amount）

队列出参 NonbizQueueRowRespVO 字段：

字段	类型	说明
id	String	单据ID（Long 序列化为字符串，下同）
bizNo	String	业务单号（上游无单号列时为空，以前端展示单据ID兜底）
unitId	String	外部单位ID
unitName	String	外部单位名快照
category	String	收支类别码
categoryName	String	收支类别中文名
amount	Number	付款金额
fee	Number	手续费（挂本单）
actualAmount	Number	实付 = amount − fee
operatorName	String	申请人姓名快照
createTime	String	申请时间（yyyy-MM-dd HH:mm:ss）
occurDate	String	发生日期（yyyy-MM-dd）
status	String	单据状态（队列内恒 APPROVED）
remark	String	备注

3.2 应付款（PAYMENT）——2 端点

使用场景：应付款单（fin_payment）APPROVED 后出纳付款。

方法	路径	说明
GET	`/admin/finance/cashier/payment/queue`	待付款队列（status=APPROVED 分页）
POST	`/admin/finance/cashier/payment/pay`	登记付款（记 OUT 流水 + 回写 PAID；金额锁死 = 审批实付 actual_pay_amount）

队列出参 PaymentQueueRowRespVO 字段：

字段	类型	说明
id	String	单据ID
bizNo	String	业务单号
supplierId	String	供应商ID
supplierName	String	供应商全称快照
paymentTypeName	String	付款类型名称快照
amount	Number	付款金额（= 审批实付）
fee	Number	手续费（应付款线无手续费概念，恒 0）
actualAmount	Number	实付（= amount）
operatorName	String	申请人姓名快照
createTime	String	申请时间
occurDate	String	发生日期
status	String	单据状态（队列内恒 APPROVED）
remark	String	备注

3.3 预付款（PREPAY）——2 端点

使用场景：预付款单（fin_prepay）APPROVED 后出纳打款。

方法	路径	说明
GET	`/admin/finance/cashier/prepay/queue`	待付款队列（status=APPROVED 分页）
POST	`/admin/finance/cashier/prepay/pay`	登记付款（记 OUT 流水 + 回写 PAID；金额锁死 = 审批预付金额 amount）

队列出参 PrepayQueueRowRespVO 字段：

字段	类型	说明
id	String	单据ID
bizNo	String	业务单号
supplierId	String	供应商ID
supplierName	String	供应商全称快照
payDate	String	预付日期（yyyy-MM-dd）
amount	Number	付款金额（= 审批预付金额）
fee	Number	手续费（恒 0）
actualAmount	Number	实付（= amount）
operatorName	String	申请人姓名快照
createTime	String	申请时间
status	String	单据状态（队列内恒 APPROVED）
remark	String	备注

注意：预付款队列行无 occurDate 字段（有 payDate 预付日期）。

3.4 费用报销（EXPENSE）——2 端点

使用场景：费用报销单（fin_expense）APPROVED 后出纳付款。

方法	路径	说明
GET	`/admin/finance/cashier/expense/queue`	待付款队列（status=APPROVED 分页）
POST	`/admin/finance/cashier/expense/pay`	登记付款（记 OUT 流水 + 回写 PAID；金额锁死 = 审批应付 payable_amt，已含冲销借款差额）

队列出参 ExpenseQueueRowRespVO 字段：

字段	类型	说明
id	String	单据ID
bizNo	String	业务单号
departmentId	String	部门ID
departmentName	String	部门名快照
expenseCategoryName	String	费用类别名称（末级名称快照）
amount	Number	付款金额（= 审批应付，已含冲销借款差额）
fee	Number	手续费（恒 0）
actualAmount	Number	实付（= amount）
operatorName	String	申请人姓名快照
createTime	String	申请时间
occurDate	String	发生日期
status	String	单据状态（队列内恒 APPROVED）
remark	String	备注

3.5 员工借款（STAFF_LOAN）——2 端点

使用场景：员工借款单（fin_staff_loan）APPROVED 后出纳放款。

方法	路径	说明
GET	`/admin/finance/cashier/staff-loan/queue`	待放款队列（status=APPROVED 分页）
POST	`/admin/finance/cashier/staff-loan/pay`	登记放款（记 OUT 流水 + 回写 PAID；金额锁死 = 审批借款金额 amount）

队列出参 StaffLoanQueueRowRespVO 字段：

字段	类型	说明
id	String	单据ID
bizNo	String	业务单号
staffId	String	借款人ID
staffName	String	借款人姓名快照
purpose	String	借款用途
loanDate	String	借款日期（yyyy-MM-dd）
amount	Number	付款金额（= 审批借款金额）
fee	Number	手续费（恒 0）
actualAmount	Number	实付（= amount）
operatorName	String	申请人姓名快照
createTime	String	申请时间
status	String	单据状态（队列内恒 APPROVED）

注意：员工借款队列行无 remark / occurDate 字段。

3.6 报账款（REIMBURSE）——3 端点

使用场景：报账结算后，direction=PAYABLE（公司应付报账人）的单据进待付款队列由出纳打款；direction=RECEIVABLE（报账人应回款）的单据走收款确认入账，支持部分收款（累计收不齐挂 PARTIAL_RECEIVED、收齐翻 RECEIVED）。

方法	路径	说明
GET	`/admin/finance/cashier/reimburse/queue`	待付款队列（status=APPROVED 且 direction=PAYABLE 分页）
POST	`/admin/finance/cashier/reimburse/pay`	登记付款（仅 direction=PAYABLE：记 OUT 流水 + 回写 PAID；金额锁死 = 结算金额 settle_amount）
POST	`/admin/finance/cashier/reimburse/confirm-in`	报账回款收款确认入账（仅 direction=RECEIVABLE：记 IN 流水 + 累计 received_amount；入参必填 amount 本次收款额，累计不超过 settle_amount）

队列出参 ReimburseQueueRowRespVO 字段：

字段	类型	说明
id	String	单据ID
bizNo	String	业务单号
reporterName	String	报账人姓名快照
settleAmount	Number	结算金额（推送时冻结，与付款金额锁死基准同值）
direction	String	报账方向：PAYABLE 公司应付报账人 / RECEIVABLE 报账人应回款 / BALANCED 两清（队列内恒 PAYABLE）
amount	Number	付款金额（= settleAmount）
fee	Number	手续费（恒 0）
actualAmount	Number	实付（= amount）
operatorName	String	申请人姓名快照
createTime	String	申请时间
occurDate	String	发生日期
status	String	单据状态（队列内恒 APPROVED）
remark	String	备注

3.7 司导预支（ADVANCE）——2 端点，⚠️ 预留未接通

使用场景：上游司导预支单据尚未建设，本页签 2 端点为契约占位空壳，调用一律返错误码 598607。前端勿接入（不要做页签入口，或做置灰）。

方法	路径	说明
GET	`/admin/finance/cashier/advance/queue`	预留未接通，一律 598607
POST	`/admin/finance/cashier/advance/pay`	预留未接通，一律 598607

占位出参 AdvanceQueueRowRespVO 字段（id / bizNo / amount / fee / actualAmount / operatorName / createTime / occurDate / status / remark）仅为契约占位，实际不会返回数据（端点直接抛 598607）。

3.8 公司借款（COMPANY_LOAN）——2 端点

使用场景：公司借款单（fin_company_loan）仅 direction=OUT 借出单 APPROVED 后进出纳付款队列放款；借入 IN 单不在本页签（走公司借款域自己的 confirm-inbound 专用端点，不在本次范围）。

方法	路径	说明
GET	`/admin/finance/cashier/company-loan/queue`	待付款队列（direction=OUT 且 status=APPROVED 分页）
POST	`/admin/finance/cashier/company-loan/pay`	借出放款（APPROVED → PAID + 记 OUT 流水 + 落 CASHIER_PAY 操作流水；金额锁死 = 借款金额 amount）

队列出参 CompanyLoanQueueRowRespVO 字段：

字段	类型	说明
id	String	借款单ID
loanNo	String	借款单号（GS- 前缀）——注意本页签用 loanNo，不是 bizNo
direction	String	方向（队列内恒 OUT 借出）
unitId	String	往来单位ID
unitName	String	往来单位名称快照
handlerStaffId	String	经办人ID
handlerStaffName	String	经办人姓名快照
amount	Number	借款金额（付款金额锁死基准同值）
feeRate	Number	手续费率‰（登记参考值）
loanDate	String	借款日期（yyyy-MM-dd）
dueDate	String	约定归还日期（yyyy-MM-dd）
purpose	String	借款用途
status	String	单据状态（队列内恒 APPROVED）
createTime	String	申请时间

注意：公司借款队列行无 fee / actualAmount / operatorName / occurDate / remark 字段（有 feeRate / dueDate / handlerStaffId / handlerStaffName 特有字段）。

3.9 已付款流水台账（保留不变）——1 端点

方法	路径	说明
GET	`/admin/finance/cashier/payments/page`	出纳已付款流水台账分页（fin_fund_flow OUT 单源查询，各页签前端共用）

入参 CashierPaymentPageReqVO（Query，含分页参数 page / pageSize）：

字段	类型	必填	说明
bizType	String	❌	付款类型（见 §6.1 枚举）；空 = NONBIZ
fundAccountId	Long	❌	出账公司账户ID；空 = 不限
flowNo	String	❌	流水号模糊；空 = 不限
flowAtStart	String	❌	收付日期起（yyyy-MM-dd）
flowAtEnd	String	❌	收付日期止（yyyy-MM-dd）

出参 CashierPaymentRowRespVO 字段：

字段	类型	说明
id	String	流水ID
flowNo	String	流水号
fundAccountId	String	出账公司账户ID
accountName	String	出账账户名称
amount	Number	金额
fee	Number	手续费（挂出账流水）
balanceAfter	Number	本笔记完后账户结存快照
bizType	String	业务类型码
bizTypeName	String	业务类型中文名
bizId	String	关联业务单据ID
bizNo	String	业务单号（上游无单号列时为空）
counterparty	String	对方单位名快照
voucherUrl	String	付款凭证影像 URL
flowAt	String	收付落账时间（yyyy-MM-dd HH:mm:ss）
operatorName	String	经办人姓名快照
remark	String	备注

4. 接口入参（18 新端点共用 3 类请求 VO）

4.1 队列查询（8 个 queue 端点共用 `CashierQueueFormReqVO`，Query 参数）

字段	类型	必填	说明	校验规则
page	Integer	❌	页码，默认 1	最小 1；兼容别名 pageNo
pageSize	Integer	❌	每页条数，默认 20	1-100

已删除 payType 字段——路径即付款类型，无需再传。

4.2 登记付款（8 个 pay 端点共用 `CashierPayFormReqVO`，JSON body）

字段	类型	必填	说明	校验规则
bizId	Long	✅	业务单据ID	非空
payAccountId	Long	✅	出账公司账户ID（fin_fund_account）	非空
payMethod	String	❌	付款方式（字典 fin_pay_way 码值：CASH / BANK / THIRD_PARTY）	与 payChannel 联动校验（见 §9）
payChannel	String	❌	付款渠道（WXPAY 微信支付 / ALIPAY 支付宝；仅 payMethod=THIRD_PARTY 时传，其余方式不传）	最长 20
amount	Number	✅	付款金额（>0，须等于单据审批应付金额，不一致 598610 硬拦；各页签锁死基准见 §3 各节）	非空
fee	Number	❌	手续费（≥0，挂出账流水）	不得为负
voucherNo	String	❌	付款凭证号	—
voucherUrl	String	❌	付款凭证影像 URL	—
payDate	String	✅	付款日期（yyyy-MM-dd，可回溯补录）	非空

已删除 bizType 与 operatorName 字段——路径即业务类型；经办人统一取当前登录人快照。

4.3 业务外收入收款确认（仅 NONBIZ 页签 `NonbizConfirmInReqVO`，JSON body）

字段	类型	必填	说明	校验规则
bizId	Long	✅	业务单据ID（fin_nonbiz_flow direction=IN 且 status=APPROVED）	非空
payAccountId	Long	✅	入账公司账户ID（fin_fund_account）	非空
payMethod	String	❌	收款方式（字典 fin_pay_way：CASH / BANK / THIRD_PARTY）	与 payChannel 联动校验
payChannel	String	❌	收款渠道（WXPAY / ALIPAY；仅 THIRD_PARTY 时传）	最长 20
voucherNo	String	❌	收款凭证号	—
voucherUrl	String	❌	收款凭证影像 URL	—
payDate	String	✅	收款日期（yyyy-MM-dd，可回溯补录）	非空

无 amount 字段——入账金额 = 单据实收 actual_amount。

4.4 报账回款收款确认（仅 REIMBURSE 页签 `ReimburseConfirmInReqVO`，JSON body）

字段	类型	必填	说明	校验规则
bizId	Long	✅	业务单据ID（fin_reimburse direction=RECEIVABLE 且 status=APPROVED / PARTIAL_RECEIVED）	非空
payAccountId	Long	✅	入账公司账户ID	非空
payMethod	String	❌	收款方式（CASH / BANK / THIRD_PARTY）	与 payChannel 联动校验
payChannel	String	❌	收款渠道（WXPAY / ALIPAY；仅 THIRD_PARTY 时传）	最长 20
voucherNo	String	❌	收款凭证号	—
voucherUrl	String	❌	收款凭证影像 URL	—
payDate	String	✅	收款日期（yyyy-MM-dd，可回溯补录）	非空
amount	Number	✅	本次收款金额（>0，支持部分收款；累计不超过应收总额 settle_amount，超额 598611）	非空

5. 出参（pay / confirm-in 共用响应）

5.1 收付执行响应（8 个 pay + 2 个 confirm-in 端点共用 `CashierPayRespVO`）

字段	类型	说明
flowId	String	资金流水ID
flowNo	String	资金流水号（LS + yyyyMMdd + 4 位序号）
balanceAfter	Number	本笔记完后账户结存快照
bizId	String	业务单据ID（已回写 PAID）

队列出参各页签不同，字段表已内联在 §3.1–§3.8 各页签小节，不再重复。

6. 枚举 / 数据字典

6.1 付款类型（`FinCashierPayTypeEnum`）

所属字段：台账入参 bizType / 台账出参 bizType | 类型：String

值	中文	单号前缀	是否接通	说明
`NONBIZ`	业务外支出	WS-	✅ 已接通	来源 fin_nonbiz_flow direction=OUT 且 APPROVED
`PAYMENT`	应付款	FK-	✅ 已接通	来源 fin_payment APPROVED
`PREPAY`	预付款	YF-	✅ 已接通	来源 fin_prepay APPROVED
`EXPENSE`	费用	FY-	✅ 已接通	来源 fin_expense APPROVED
`REIMBURSE`	报账款	BZ-	✅ 已接通	来源 fin_reimburse APPROVED 且 direction=PAYABLE
`STAFF_LOAN`	员工借款	JK-	✅ 已接通	来源 fin_staff_loan APPROVED
`COMPANY_LOAN`	公司借款	GS-	✅ 已接通	来源 fin_company_loan direction=OUT 且 APPROVED（仅借出单）
`ADVANCE`	司导预支	YZ-	❌ 预留未接通	上游 order_advance 未建，端点一律 598607

6.2 报账方向 direction（`ReimburseQueueRowRespVO.direction` / `CompanyLoanQueueRowRespVO.direction`）

值	中文	说明
`PAYABLE`	公司应付报账人	报账款：走 pay 打款
`RECEIVABLE`	报账人应回款	报账款：走 confirm-in 回款（支持部分收款）
`BALANCED`	两清	报账款：不进出纳队列
`OUT`	借出	公司借款：走 pay 放款（队列内恒此值）
`IN`	借入	公司借款：不进出纳队列（走公司借款域 confirm-inbound 专用端点）

6.3 收付方式 payMethod（字典 `fin_pay_way`）

值	中文	渠道约束
`CASH`	现金	不得传 payChannel
`BANK`	银行转账	不得传 payChannel
`THIRD_PARTY`	三方支付	必传 payChannel（WXPAY / ALIPAY）

6.4 收付渠道 payChannel

值	中文
`WXPAY`	微信支付
`ALIPAY`	支付宝

6.5 单据状态 status（队列行出参）

队列内恒 APPROVED（已批准待付款）。收款确认后报账款可能出现 PARTIAL_RECEIVED（部分收讫）/ RECEIVED（已收讫），付款完成后各单据翻 PAID。

7. 错误码

code	含义	触发场景
598601	业务单不存在	bizId 无效或已软删
598602	业务单状态非已批准，不可付款	单据非 APPROVED；或并发下状态已被另一请求推进（CAS 兜底）
598603	出账账户不存在或已停用	payAccountId 无效 / 账户已停用
598604	账户余额不足且不允许透支	付款金额超账户余额且账户不开透支
598605	付款金额无效（金额须大于0，手续费不得为负）	amount ≤ 0 或 fee < 0
598606	收款确认单状态非法（须为已批准的可入账单：业务外收入/报账回款）	confirm-in 的单据 direction / status 不满足入账条件
598607	付款类型非法（本期仅支持 NONBIZ / EXPENSE / PAYMENT / PREPAY / STAFF_LOAN / REIMBURSE / COMPANY_LOAN）	ADVANCE 司导预支空壳端点被调用
598608	收付方式与收付渠道不匹配	THIRD_PARTY 未传渠道；或 CASH / BANK 传了渠道
598609	收付账户与收付方式不匹配	现金方式未选现金账户 / 银行转账未选银行账户 / 三方支付未选对应渠道商户号账户
598610	付款金额与单据应付金额不一致（出纳付款须严格按审批应付金额，不得修改）	amount ≠ 该单据审批应付金额（锁死基准见 §3 各页签）
598611	收款金额超过剩余待收	报账回款部分收款：本次收款 > settle_amount − received_amount

8. 示例（3 组：典型 / 边界 / 异常）

8.1 典型成功——应付款页签「拉队列 → 登记付款」全流程

第 1 步：拉待付款队列

请求：

GET /admin/finance/cashier/payment/queue?page=1&pageSize=20
Authorization: Bearer <管理后台 JWT>
（无请求体）

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "id": "1958210000000000001",
        "bizNo": "FK-20260917-0003",
        "supplierId": "1957000000000000101",
        "supplierName": "呼伦贝尔某某车队有限公司",
        "paymentTypeName": "车费尾款",
        "amount": 5800.00,
        "fee": 0,
        "actualAmount": 5800.00,
        "operatorName": "张三",
        "createTime": "2026-09-16 15:20:11",
        "occurDate": "2026-09-20",
        "status": "APPROVED",
        "remark": "9月团期车费尾款"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "traceId": "a1b2c3d4-e5f6-7890",
  "success": true
}

第 2 步：登记付款

请求：

POST /admin/finance/cashier/payment/pay
Authorization: Bearer <管理后台 JWT>
Content-Type: application/json

{
  "bizId": 1958210000000000001,
  "payAccountId": 1956000000000000001,
  "payMethod": "BANK",
  "amount": 5800.00,
  "fee": 0,
  "voucherNo": "TRANS20260917001",
  "voucherUrl": "https://oss.example.com/voucher/20260917/001.pdf",
  "payDate": "2026-09-17"
}

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "flowId": "1958300000000000007",
    "flowNo": "LS202609170007",
    "balanceAfter": 94200.00,
    "bizId": "1958210000000000001"
  },
  "traceId": "b2c3d4e5-f6a7-8901",
  "success": true
}

8.2 边界情况——ADVANCE 司导预支空壳（预留未接通）

场景说明：司导预支页签 2 端点为契约占位，上游单据未建，调用一律返 598607。前端勿接入此页签。

请求：

GET /admin/finance/cashier/advance/queue?page=1&pageSize=20
Authorization: Bearer <管理后台 JWT>
（无请求体）

响应：

{
  "code": 598607,
  "message": "付款类型非法（本期仅支持 NONBIZ 业务外支出 / EXPENSE 费用报销 / PAYMENT 应付款 / PREPAY 预付款 / STAFF_LOAN 员工借款 / REIMBURSE 报账款 / COMPANY_LOAN 公司借款）",
  "traceId": "c3d4e5f6-a7b8-9012",
  "success": false
}

8.3 业务失败——调旧合一接口路径（已删除，404）

场景说明：旧路径 GET /admin/finance/cashier/queue、POST /admin/finance/cashier/pay、POST /admin/finance/cashier/confirm-in 已删除，任何调用一律 404。

请求：

GET /admin/finance/cashier/queue?payType=NONBIZ&page=1&pageSize=20
Authorization: Bearer <管理后台 JWT>
（无请求体）

响应（HTTP 404）：

{
  "timestamp": "2026-09-17T10:30:00.000+00:00",
  "status": 404,
  "error": "Not Found",
  "path": "/admin/finance/cashier/queue"
}

另一个高频失败：付款金额与审批应付不一致（598610）

请求：

POST /admin/finance/cashier/payment/pay
Authorization: Bearer <管理后台 JWT>
Content-Type: application/json

{
  "bizId": 1958210000000000001,
  "payAccountId": 1956000000000000001,
  "payMethod": "BANK",
  "amount": 5000.00,
  "payDate": "2026-09-17"
}

响应：

{
  "code": 598610,
  "message": "付款金额与单据应付金额不一致（出纳付款须严格按审批应付金额，不得修改）",
  "traceId": "d4e5f6a7-b8c9-0123",
  "success": false
}

9. 业务边界

✅ 适用：单据状态 = APPROVED（已批准待付款）时进队列、可登记付款；报账回款单 status ∈ {APPROVED, PARTIAL_RECEIVED} 时可继续收款确认
❌ 不适用：非 APPROVED 单据（草稿 / 审批中 / 已付款 / 已作废）→ 598602；已删 / 不存在单据 → 598601
⚠️ 金额锁死：pay 入参 amount 必须等于该单据审批应付金额（各页签锁死基准：NONBIZ=actual_amount / PAYMENT=actual_pay_amount / PREPAY=amount / EXPENSE=payable_amt / STAFF_LOAN=amount / REIMBURSE=settle_amount / COMPANY_LOAN=amount），不一致 598610 硬拦，出纳不得改金额
⚠️ 并发：重复提交同一单据付款，后到请求 598602（CAS 条件更新兜底）
⚠️ 透支闸：账户余额不足且账户不允许透支 → 598604
⚠️ 方式↔渠道↔账户三级匹配：THIRD_PARTY 必传 WXPAY / ALIPAY（598608）；现金方式须选现金账户、银行转账须选银行账户、三方须选对应渠道商户号账户（598609）
⚠️ REIMBURSE 方向分流：pay 仅受理 direction=PAYABLE；confirm-in 仅受理 direction=RECEIVABLE
⚠️ COMPANY_LOAN 仅借出：队列与放款仅 direction=OUT 借出单；借入 IN 单不在本页签
⚠️ confirm-in 仅 2 页签有：NONBIZ（业务外收入）与 REIMBURSE（报账回款）；其余 6 页签无收款确认端点
⚠️ ADVANCE 空壳：queue / pay 一律 598607，前端勿接

10. 修改前后对比

10.1 接口级对比

项	改前	改后
队列入口	1 个 `GET /cashier/queue?payType=X`	8 个 `GET /cashier/{页签}/queue`（路径即类型，删 payType）
付款入口	1 个 `POST /cashier/pay`（body 带 bizType）	8 个 `POST /cashier/{页签}/pay`（删 bizType）
收款确认入口	1 个 `POST /cashier/confirm-in`（body 带 bizType）	2 个 `POST /cashier/nonbiz/confirm-in` + `POST /cashier/reimburse/confirm-in`（删 bizType）
队列出参	1 个合一 `CashierQueueRowRespVO`（unitName / category 槽位复用）	8 个强类型 `XxxQueueRowRespVO`（业务真名字段）
台账	`GET /cashier/payments/page`	不变

10.2 队列出参字段级对比（旧槽位 → 新业务真名）

旧合一字段	NONBIZ 业务外支出	PAYMENT 应付款	PREPAY 预付款	EXPENSE 费用报销	STAFF_LOAN 员工借款	REIMBURSE 报账款	COMPANY_LOAN 公司借款
payType / payTypeName	删除（路径即类型）	删除	删除	删除	删除	删除	删除
unitId / unitName	unitId / unitName（外部单位）	supplierId / supplierName（供应商）	supplierId / supplierName（供应商）	departmentId / departmentName（部门）	staffId / staffName（借款人）	reporterName（报账人，无 ID 字段）	unitId / unitName（往来单位）
category / categoryName	category / categoryName（收支类别）	paymentTypeName（付款类型名）	删除（改 payDate 预付日期）	expenseCategoryName（费用类别名）	删除（改 purpose 用途 + loanDate 借款日期）	删除（改 settleAmount 结算金额 + direction 方向）	删除（改 feeRate / loanDate / dueDate / purpose / handlerStaffId / handlerStaffName）
bizNo	bizNo	bizNo	bizNo	bizNo	bizNo	bizNo	loanNo（借款单号，字段名不同）
id / amount / fee / actualAmount / operatorName / createTime / status	保留	保留	保留	保留	保留（无 remark / occurDate）	保留	部分保留（无 fee / actualAmount / operatorName / occurDate / remark）
occurDate / remark	保留	保留	无 occurDate	保留	无	保留	无

各页签完整字段表见 §3.1–§3.8，以各小节为准。

10.3 行为级对比

行为	改前	改后
旧路径调用	正常路由	一律 404（queue / pay / confirm-in 已删）
队列字段语义	unitName / category 按 payType 动态解释	字段名即业务语义，前端可生成精确强类型
付款类型指定	query / body 传 payType / bizType	路径前缀即类型，不传
经办人 operatorName 入参	可传（后端忽略）	字段已删，统一取登录人快照

11. 影响评估 / 回滚

11.1 影响评估

是否破坏向后兼容：是——旧 3 端点（queue / pay / confirm-in）已删除，调用一律 404；队列出参字段结构整体替换（槽位字段 → 业务真名字段）
前端是否必须同步上线：是——8 页签必须改调新路径 + 改读新字段，否则页面 404 / 字段全空；台账页（payments/page）无需改可继续用

11.2 回滚方案

回滚方式：revert PR #7855（merge commit fa086a66）即恢复旧 3 端点；后端为纯增量 + 删旧端点，无数据迁移、零 DDL
回滚后清理：无需清理脏数据 / 缓存

12. 注意事项

前端 workaround 清理点：
- 旧前端按 payType 拼队列请求、按 bizType 拼付款 / 收款确认请求的逻辑全部删除，改为按页签调对应路径
- 旧前端按 unitName / category 槽位 + payType 分支解释字段语义的逻辑删除，直接读 §10.2 对照表右侧的业务真名字段
- 旧前端若对「pay 入参传 operatorName」有残留代码，删除（字段已删）
字段语义警示：
- 公司借款队列行的单号字段是 loanNo 不是 bizNo，且无 fee / actualAmount（有 feeRate 手续费率‰）
- 员工借款队列行无 remark / occurDate；预付款队列行无 occurDate（用 payDate）
- 所有 Long 型 ID（id / bizId / unitId / supplierId / staffId / flowId 等）在 JSON 中为字符串
ADVANCE 司导预支页签勿接：2 端点一律 598607，是预留壳不是 bug
台账 payments/page 不变：各页签「已付款」列表继续调它，入参出参零变化

35 KiB 原始文件 Blame 文件历史 Unescape Escape