From a669350b0f29c2a2752b330295837ef4736e785b Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 17 Sep 2026 10:43:13 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=87=BA=E7=BA=B3=E6=94=AF?= =?UTF-8?q?=E4=BB=98=E6=8E=A5=E5=8F=A3=E6=8B=86=E5=A3=B3=E5=90=88=E8=8A=AF?= =?UTF-8?q?=E2=80=94=E2=80=94=E5=88=A03=E6=97=A7=E7=AB=AF=E7=82=B9404+?= =?UTF-8?q?=E5=A2=9E18=E9=A1=B5=E7=AD=BE=E7=AB=AF=E7=82=B9=EF=BC=88#7842?= =?UTF-8?q?=20PR=20#7855=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删 GET /cashier/queue、POST /cashier/pay、POST /cashier/confirm-in（一律 404） - 增 queue×8 + pay×8 + confirm-in×2，路径前缀 /cashier/{nonbiz,payment,prepay,expense,staff-loan,reimburse,advance,company-loan} - 队列出参消灭 unitName/category 槽位复用，8 页签各用业务真名强类型字段 - ADVANCE 司导预支 2 端点预留空壳一律 598607，前端勿接 - 台账 GET /cashier/payments/page 不变 --- ..._出纳支付接口拆壳合芯-修改接口-管理后台.md | 681 ++++++++++++++++++ 1 file changed, 681 insertions(+) create mode 100644 changelogs-v2/2026-09/17_7842_出纳支付接口拆壳合芯-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/17_7842_出纳支付接口拆壳合芯-修改接口-管理后台.md b/changelogs-v2/2026-09/17_7842_出纳支付接口拆壳合芯-修改接口-管理后台.md new file mode 100644 index 00000000..fda0d353 --- /dev/null +++ b/changelogs-v2/2026-09/17_7842_出纳支付接口拆壳合芯-修改接口-管理后台.md @@ -0,0 +1,681 @@ +--- +schema: "hl-changelog/v2" +ticket: "finance-cashier-split-shell" +title: "出纳支付接口「拆壳合芯」——8 页签独立强类型端点（删 3 旧端点 404 + 增 18 新端点）" +consumer: "admin" +author: "yst(GIT)" +change_type: "修改接口" +backend_status: "merged" +gateway_status: "pending" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-17" +status_note: "出纳支付管理 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）。" +updated_at: "2026-09-17" +base: "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> +（无请求体） +``` + +响应： +```json +{ + "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 +``` +```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" +} +``` + +响应： +```json +{ + "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> +（无请求体） +``` + +响应： +```json +{ + "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）： +```json +{ + "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 +``` +```json +{ + "bizId": 1958210000000000001, + "payAccountId": 1956000000000000001, + "payMethod": "BANK", + "amount": 5000.00, + "payDate": "2026-09-17" +} +``` + +响应： +```json +{ + "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 不变**：各页签「已付款」列表继续调它，入参出参零变化 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#7842](https://git.1814.love:8443/wx/HL/issues/7842) +- **PR**: [#7855](https://git.1814.love:8443/wx/HL/pulls/7855) +- **Merge commit**: [fa086a66](https://git.1814.love:8443/wx/HL/commit/fa086a66a15d9f11f48298c50d9cb7925e90f800) + +### 13.2 联系人 + +- **后端负责人**: @yst（腰苏图）