hl-api-changelog/changelogs-v2/2026-09/07_7217_支付管理出纳-新增接口-管理后台.md

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	7217	支付管理·出纳（待付款队列 / 登记付款 / 已付款台账 / 收款确认 + 业务外状态机补全）	admin	yst	新增接口	deployed	verified	verified	mmg	7278c5f9		2026-09-10	verified 2026-09-10 mmg: cashier.js 四端点(queue/pay/payments-page/confirm-in)+buildCashierPayPayload 按 bizType 分叉(NONBIZ→payAccountId+amount+fee,EXPENSE→fundAccountId+actualAmount);CashierQueuePage 共享页(props.payType) n-tabs[待付款,已付款台账],登记付款弹窗金额默认带入 actualAmount 可改(不一致后端仅 WARN);confirm-in 触发点归 #7165 业务外收入列表。pay/expense 与 pay/nonbiz-out 两薄壳。checkpoint 全绿。	2026-09-07	dev-v3

支付管理（出纳统一收付执行）

1. 接口背景

财务域「支付管理」：出纳统一收付执行出口。上游业务单（本期=业务外支出）审批通过后进入出纳待付款队列，出纳在队列里选单登记付款——后端同事务完成「记资金流水 OUT + 回写业务单 PAID + 重算账户结存 + 透支闸校验」；业务外收入走「收款确认入账」端点直接记 IN 流水。同时业务外收支域补两个状态机推进端点（submit/approve），把单据从草稿推到已批准。

• 出纳域路径前缀：/admin/finance/cashier（4 个新端点）
• 业务外域补端点：/admin/finance/nonbiz-flows/{id}/submit、/{id}/approve（2 个新端点）
• 服务：hl-finance（财务服务）

2. 变更清单

类型	接口	说明
新增	GET /admin/finance/cashier/queue	出纳待付款队列（本期仅 NONBIZ 业务外支出进队列）
新增	POST /admin/finance/cashier/pay	登记付款（统一动作：记 OUT 流水 + 回写 PAID + 重算结存 + 透支闸）
新增	GET /admin/finance/cashier/payments/page	出纳已付款流水台账分页（数据源 fin_fund_flow OUT）
新增	POST /admin/finance/cashier/confirm-in	收款确认入账（业务外收入批准即入账：记 IN 流水 + 回写 PAID）
新增	PUT /admin/finance/nonbiz-flows/{id}/submit	提交收支单（PENDING → SUBMITTED，提交后锁定）
新增	PUT /admin/finance/nonbiz-flows/{id}/approve	批准收支单（SUBMITTED → APPROVED；本期手工置，企微审批待接通）

3. 接口详情

3.1 待付款队列 GET /queue

• 使用场景：管理后台「支付管理」待付款页签，出纳看待付单据列表。
• 认证：管理后台管理员 Token（Authorization: Bearer admin-token），未登录返 401。
• 幂等性：查询接口，天然幂等。限流：网关默认。

3.2 登记付款 POST /pay

• 使用场景：出纳实际打款后在系统登记。后端同事务：记资金流水 OUT → 回写业务单 status=PAID → 重算账户结存 → 透支闸（余额不足且账户不允许透支时整单回滚报 598604）。
• 认证：同上。幂等性：业务幂等——同一业务单重复付款被 CAS 条件更新拦截，返回 598602，不会重复记账。限流：网关默认。

3.3 已付款台账 GET /payments/page

• 使用场景：出纳「已付款」页签，查历史付款流水（数据源为资金流水表 fin_fund_flow 的 OUT 出纳业务类记录）。
• 认证：同上。幂等：查询接口。限流：网关默认。

3.4 收款确认入账 POST /confirm-in

• 使用场景：业务外收入单批准（APPROVED）后，出纳确认钱已到账，记 IN 流水并回写单据 PAID。入账金额 = 单据实收 actualAmount，不可手改。
• 认证：同上。幂等性：业务幂等——单据回写 PAID 后重复调用报 598606。限流：网关默认。

3.5 提交收支单 PUT /nonbiz-flows/{id}/submit

• 使用场景：业务外收支草稿录入人提交审批，单据 PENDING → SUBMITTED 并锁定（不可编辑/删除）。
• 认证：同上。幂等性：重复提交报 598505。限流：网关默认。无 Body。

3.6 批准收支单 PUT /nonbiz-flows/{id}/approve

• 使用场景：财务负责人批准审批中的单据，SUBMITTED → APPROVED；支出单此后进出纳待付款队列，收入单待收款确认。本期为手工审批，企微审批流待接通。
• 认证：同上。幂等性：重复批准报 598505。限流：网关默认。无 Body。

4. 接口入参

4.1 队列 Query（CashierQueueReqVO）

字段	类型	必填	约束	说明
payType	String	否	NONBIZ	付款类型；空=NONBIZ。本期仅接通 NONBIZ（业务外支出），其余为预留枚举未建上游，传未接通值报 598607
page	Number	否	默认 1	页码
pageSize	Number	否	默认 20	每页条数

4.2 登记付款 Body（CashierPayReqVO）

字段	类型	必填	约束	说明
bizType	String	是	NONBIZ	业务类型；本期仅 NONBIZ（业务外支出）
bizId	Number	是	—	业务单据 ID（须 status=APPROVED，否则 598602）
payAccountId	Number	是	—	出账公司账户 ID（fin_fund_account，不存在/停用报 598603）
payMethod	String	否	—	付款方式（字典 fin_pay_way 码值：CASH/BANK_TRANSFER/WECHAT/ALIPAY）
amount	Number	是	大于0	付款金额（598605）
fee	Number	否	不小于0	手续费（挂出账流水）
voucherNo	String	否	—	付款凭证号
voucherUrl	String	否	—	付款凭证影像 URL
payDate	String	是	yyyy-MM-dd	付款日期（可回溯补录）
operatorName	String	否	—	后端忽略，统一取当前登录人快照；字段保留仅为入参兼容

4.3 台账 Query（CashierPaymentPageReqVO）

字段	类型	必填	约束	说明
bizType	String	否	NONBIZ	业务类型筛选；空=NONBIZ
fundAccountId	Number	否	—	出账公司账户 ID；空=不限
flowNo	String	否	模糊	流水号筛选
flowAtStart	String	否	yyyy-MM-dd	收付日期起
flowAtEnd	String	否	yyyy-MM-dd	收付日期止
page	Number	否	默认 1	页码
pageSize	Number	否	默认 20	每页条数

4.4 收款确认 Body（CashierConfirmInReqVO）

字段	类型	必填	约束	说明
bizId	Number	是	—	业务单据 ID（须 direction=IN 且 status=APPROVED，否则 598606）
payAccountId	Number	是	—	入账公司账户 ID（fin_fund_account）
payMethod	String	否	—	收款方式（字典 fin_pay_way 码值）
voucherNo	String	否	—	收款凭证号
voucherUrl	String	否	—	收款凭证影像 URL
payDate	String	是	yyyy-MM-dd	收款日期（可回溯补录）

4.5 状态机端点路径参数

接口	字段	类型	说明
PUT /nonbiz-flows/{id}/submit、/{id}/approve	id	Number	收支单 ID；无 Body

5. 出参字段

5.1 队列行（CashierQueueRowRespVO）

字段	类型	说明
id	String	单据 ID（雪花字符串）
bizNo	String	业务单号（上游单据无单号列时为空，前端展示以 id 兜底）
payType	String	付款类型码（NONBIZ）
payTypeName	String	付款类型中文名（业务外支出）
unitId	String	外部单位 ID（雪花字符串）
unitName	String	外部单位名快照
category	String	收支类别码
categoryName	String	收支类别中文名（取自 fin_nonbiz_category）
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	备注

5.2 台账行（CashierPaymentRowRespVO）

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

5.3 付款 / 收款确认响应（CashierPayRespVO）

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

5.4 状态机端点响应

data 为 null（Result），code=200 即流转成功。

6. 枚举 / 数据字典

payType / bizType（出纳业务类型，代码枚举）

值	中文	说明
NONBIZ	业务外支出	本期唯一接通（队列/登记/台账均支持）
EXPENSE / PAYMENT 等	—	预留枚举，上游未建，传入报 598607

业务外单据状态机（本次补全后）

PENDING →(submit)→ SUBMITTED →(approve)→ APPROVED →(出纳 pay / confirm-in)→ PAID；SUBMITTED 可驳回为 REJECTED（驳回端点后续提供）。状态值见「06_7165_业务外收支流水」changelog 第 6 节。

payMethod（收付方式，数据字典 fin_pay_way）

码值	中文
CASH	现金
BANK_TRANSFER	银行转账
WECHAT	微信
ALIPAY	支付宝

7. 错误码（段位 598600-598699 + 业务外段补 598505）

错误码	含义	触发场景
598601	业务单不存在	bizId 无效或已软删
598602	业务单状态非已批准，不可付款	业务单非 APPROVED 即登记付款；同一单据重复付款（CAS 兜底）也报此码
598603	出账账户不存在或已停用	payAccountId 无效（recordFlow 内 FOR UPDATE 重读兜底）
598604	账户余额不足且不允许透支	出账触发透支闸（资金流水域 595103 在出纳边界的翻译）
598605	付款金额无效（金额须大于0，手续费不得为负）	amount≤0 或 fee<0
598606	收款确认单状态非法（须为已批准的业务外收入单）	confirm-in 的单据非 direction=IN+APPROVED；重复确认也报此码
598607	付款类型非法	payType/bizType 传未接通值（本期仅 NONBIZ）
598505	状态流转非法（提交须草稿态，批准须审批中）	submit/approve 时状态不符（业务外收支段，见 7165 changelog）

8. 示例

8.1 典型成功（队列选单 → 登记付款）

GET /admin/finance/cashier/queue?payType=NONBIZ&page=1&pageSize=20

{"code":200,"success":true,"data":{"records":[{"id":"2094311122233344455","bizNo":null,"payType":"NONBIZ","payTypeName":"业务外支出","unitId":"2094001122334455667","unitName":"市文旅局","category":"DEPOSIT_REFUND","categoryName":"押金退回","amount":2000.00,"fee":0,"actualAmount":2000.00,"operatorName":"腰苏图","createTime":"2026-09-06 11:00:00","occurDate":"2026-09-05","status":"APPROVED","remark":"质保金退回"}],"total":1,"page":1,"pageSize":20}}

POST /admin/finance/cashier/pay
Content-Type: application/json

{
  "bizType": "NONBIZ",
  "bizId": 2094311122233344455,
  "payAccountId": 2097009988776655443,
  "payMethod": "BANK_TRANSFER",
  "amount": 2000.00,
  "fee": 0,
  "voucherNo": "FK-20260907-01",
  "payDate": "2026-09-07"
}

{"code":200,"success":true,"data":{"flowId":"2094400011122233445","flowNo":"LS202609070001","balanceAfter":112894.00,"bizId":"2094311122233344455"}}

8.2 边界情况（回溯补录 / 收款确认）

付款日期可回溯补录历史付款：

{"bizType":"NONBIZ","bizId":2094311122233344460,"payAccountId":2097009988776655443,"amount":0.01,"payDate":"2026-08-15"}

收款确认入账（业务外收入 APPROVED 单）：

{"bizId":2094311000000000001,"payAccountId":2097009988776655443,"payMethod":"BANK_TRANSFER","payDate":"2026-09-07"}

入账金额由后端取单据 actualAmount，Body 无金额字段。空队列：records=[]、total=0，HTTP 200。

8.3 业务失败（重复付款 / 余额不足 / 类型非法）

对同一单据再次登记付款：

{"code":598602,"message":"业务单状态非已批准，不可付款","success":false,"data":null}

账户余额不足且不允许透支：

{"code":598604,"message":"账户余额不足且不允许透支","success":false,"data":null}

payType 传未接通值：

{"code":598607,"message":"付款类型非法（本期仅支持 NONBIZ 业务外支出）","success":false,"data":null}

9. 业务边界

适用：

• 业务外支出（NONBIZ OUT）批准后的出纳付款执行与台账查询。
• 业务外收入（NONBIZ IN）批准后的收款确认入账。
• 业务外收支单从草稿到已批准的状态机推进（submit/approve）。

不适用 / 限制：

• 队列/登记付款本期仅接通 NONBIZ 一条线（方案 A）；工资/提成等类型已裁掉，其余枚举预留未建上游，传未接通值报 598607。
• 批准本期为手工操作（approve 端点直接置 APPROVED），企微审批流留 TODO 未接通。
• 出纳实付金额与单据 actualAmount 不一致时后端打 WARN 审计日志但不硬拦，允许出纳按实际打款登记。
• confirm-in 入账金额恒等于单据 actualAmount，不支持部分入账。

特殊边界：

• operatorName 入参被后端忽略，经办人统一取当前登录人快照，防止冒名登记。
• 登记付款 / 收款确认均为同事务「流水 + 回写」原子操作，失败整单回滚，不会出现只记流水不回写。
• fin_nonbiz_flow 本 PR 补 3 列（pay_account_id/pay_flow_id/paid_at，Flyway V20260906_104），部署自动执行。

10. 注意事项

• 所有雪花 ID 均为字符串，前端按 String 处理。
• 队列行 bizNo 可能为空（上游单据无单号列），前端展示建议以单据 id 兜底。
• 台账数据源是资金流水表（fin_fund_flow OUT），不是业务单表；一笔付款对应一行台账。
• balanceAfter 是「本笔记完后」的账户结存快照，前端可直接展示无需再查账户余额。
• 业务外收支域的 5 个基础端点见「06_7165_业务外收支流水」changelog；本文件只覆盖出纳 4 端点 + nonbiz 2 个流转端点。

11. 关联 / 联系人

• Issue：https://git.1814.love:8443/wx/HL/issues/7217
• PR：https://git.1814.love:8443/wx/HL/pulls/7221
• Commit：https://git.1814.love:8443/wx/HL/commit/850cbf454c
• Epic：https://git.1814.love:8443/wx/HL/issues/7216
• 负责人：腰苏图（yst）