291 行
15 KiB
Markdown
291 行
15 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7217"
|
||
title: "支付管理·出纳（待付款队列 / 登记付款 / 已付款台账 / 收款确认 + 业务外状态机补全）"
|
||
consumer: "admin"
|
||
author: "yst"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "7278c5f9"
|
||
target_release: ""
|
||
verified_at: "2026-09-10"
|
||
status_note: "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 全绿。"
|
||
updated_at: "2026-09-07"
|
||
base: "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<Void>），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 典型成功（队列选单 → 登记付款）
|
||
```http
|
||
GET /admin/finance/cashier/queue?payType=NONBIZ&page=1&pageSize=20
|
||
```
|
||
```json
|
||
{"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}}
|
||
```
|
||
```http
|
||
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"
|
||
}
|
||
```
|
||
```json
|
||
{"code":200,"success":true,"data":{"flowId":"2094400011122233445","flowNo":"LS202609070001","balanceAfter":112894.00,"bizId":"2094311122233344455"}}
|
||
```
|
||
|
||
### 8.2 边界情况（回溯补录 / 收款确认）
|
||
付款日期可回溯补录历史付款：
|
||
```json
|
||
{"bizType":"NONBIZ","bizId":2094311122233344460,"payAccountId":2097009988776655443,"amount":0.01,"payDate":"2026-08-15"}
|
||
```
|
||
收款确认入账（业务外收入 APPROVED 单）：
|
||
```json
|
||
{"bizId":2094311000000000001,"payAccountId":2097009988776655443,"payMethod":"BANK_TRANSFER","payDate":"2026-09-07"}
|
||
```
|
||
入账金额由后端取单据 actualAmount，Body 无金额字段。空队列：records=[]、total=0，HTTP 200。
|
||
|
||
### 8.3 业务失败（重复付款 / 余额不足 / 类型非法）
|
||
对同一单据再次登记付款：
|
||
```json
|
||
{"code":598602,"message":"业务单状态非已批准，不可付款","success":false,"data":null}
|
||
```
|
||
账户余额不足且不允许透支：
|
||
```json
|
||
{"code":598604,"message":"账户余额不足且不允许透支","success":false,"data":null}
|
||
```
|
||
payType 传未接通值：
|
||
```json
|
||
{"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）
|