feat(finance): 出纳付款金额锁死 changelog（598610，#7713）

5 条 OUT 付款线金额须等于审批应付金额，不一致抛 598610；前端付款弹窗金额应改只读。
2026-09-15 02:40:43 +08:00
@@ -0,0 +1,143 @@
 ---
 schema: "hl-changelog/v2"
 ticket: "7713"
 title: "出纳付款金额锁死：金额须等于审批应付金额（新增 598610）"
 consumer: "admin"
 author: "yst(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
 frontend_status: "required"
 frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: "2026-09-15"
 status_note: "破坏性收紧：出纳 POST /admin/finance/cashier/pay 5 条 OUT 分支（业务外支出/费用报销/应付款/预付款/员工借款放款）付款金额从「可任意改（仅 WARN）」改为「必须等于审批应付金额」，不一致抛新错误码 598610。前端付款弹窗金额输入框应改为只读展示审批应付金额，否则用户改了会被 598610 拦。"
 updated_at: "2026-09-15"
 base: "dev-v3"
 ---
 # 出纳付款金额锁死：金额须等于审批应付金额（修改接口 · 破坏性收紧）
 > **服务**: hl-order-service-v3（hl-finance 模块）
 > **PR**: [#7714](https://git.1814.love:8443/wx/HL/pulls/7714)
 > **Issue**: [#7713](https://git.1814.love:8443/wx/HL/issues/7713)
 > **日期**: 2026-09-15（已部署测试服 + 行为级验证 PASS）
 > **影响范围**: 出纳登记付款接口入参语义收紧 + 新增 1 错误码；无路由/字段名变化
 ---
 ## ⚠️ 关键变化（破坏性收紧）
 🔴 **付款金额锁死**：`POST /admin/finance/cashier/pay` 的 `amount` 现在**必须等于该单据的审批应付金额**，不再允许出纳修改。
 - 此前：金额可任意填，不等仅记 WARN 日志，照样放款（资金风险：申请 1000 实付 800/1200）。
 - 现在：金额 ≠ 审批应付金额 → 直接抛 **598610**，**不放款**。
 🟢 **覆盖 5 条 OUT 付款线**（bizType）：
 | bizType | 单据 | 应付金额基准 |
 |---|---|---|
 | `NONBIZ` | 业务外支出 | 审批实付 `actual_amount` |
 | `EXPENSE` | 费用报销 | 审批应付 `payable_amt`（= 报销额 − 冲销借款额） |
 | `PAYMENT` | 应付款 | 审批实付 `actual_pay_amount` |
 | `PREPAY` | 预付款 | 审批预付 `amount` |
 | `STAFF_LOAN` | 员工借款放款 | 审批借款 `amount` |
 ---
 ## 一、背景
 员工借款支付、业务外支出等付款场景，金额本应由审批锁定、出纳只按审批额付款。原型上金额是只读展示，但真实前端做成了可编辑输入框，后端又只 WARN 不拦——导致「申请额 ≠ 实付额」可穿透，涉钱出错。本次把 5 条付款线金额全部锁死。
 ## 二、变更清单
 | 项 | 变更 |
 |---|---|
 | `POST /admin/finance/cashier/pay` 入参 `amount` | 语义收紧：须等于审批应付金额，不一致 598610 |
 | 错误码 | 新增 **598610** `CASHIER_PAY_AMOUNT_MISMATCH` |
 | 校验时点 | 在扣账/记流水**之前** fail-fast（员工借款线在锁内） |
 | 无基准场景 | 如 EXPENSE `payable_amt=null`，一律 fail-fast 不放款（涉钱从严） |
 ## 三、入参（语义收紧）
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `bizType` | string | ✅ | NONBIZ/EXPENSE/PAYMENT/PREPAY/STAFF_LOAN |
 | `bizId` | long | ✅ | 业务单据ID |
 | `payAccountId` | long | ✅ | 出账账户（fin_fund_account，ACTIVE；类型须匹配 payMethod，否则 598609） |
 | `amount` | number | ✅ | **付款金额：必须等于审批应付金额**（见上表基准），不一致 598610 |
 | `payMethod` / `payChannel` | string | 见既有 | 收付方式/渠道（#7681/#7698 口径不变） |
 | `payDate` | string | ✅ | 付款日期 yyyy-MM-dd |
 ## 四、错误码
 | 码 | 含义 | 触发 |
 |---|---|---|
 | **598610**（新增） | 付款金额与单据应付金额不一致 | amount ≠ 审批应付金额（多付/少付都拦）；或无基准金额可校验 |
 ## 五、示例
 ### 5.1 反例：少付 → 598610
 借款单审批金额 1000，实付 999：
 ```http
 POST /admin/finance/cashier/pay
 { "bizType":"STAFF_LOAN","bizId":2099067894846345217,
  "payAccountId":2095431817594028033,"payMethod":"CASH","amount":999,"payDate":"2026-09-15" }
 ```
 ```json
 { "code": 598610, "message": "付款金额与单据应付金额不一致（出纳付款须严格按审批应付金额，不得修改）", "success": false }
 ```
 ### 5.2 反例：多付 → 598610
 同上单据实付 1200，同样返回 598610。
 ### 5.3 正例：金额一致 → 放款成功
 ```http
 POST /admin/finance/cashier/pay
 { "bizType":"STAFF_LOAN","bizId":2099067894846345217,
  "payAccountId":2095431817594028033,"payMethod":"CASH","amount":1000,"payDate":"2026-09-15" }
 ```
 → `{ "code": 200, "message": "成功" }`，借款单状态 → PAID。
 ## 六、前端对接建议（重要）
 付款弹窗的**金额输入框应改为只读**，展示该单据的审批应付金额（由后端在待付款队列/详情给出），不要再让用户编辑：
 ```js
 // ❌ 原来：可编辑
 <n-input-number v-model:value="payForm.amount" />
 // ✅ 建议：只读展示审批应付金额
 <span>{{ payableAmount }}</span>  // 随 pay 请求原样回传
 ```
 否则用户改了金额提交会被 598610 拦，体验是「总报错」。
 ## 七、业务边界
 - 只锁「金额 = 审批应付」，不动既有账户 ACTIVE / 方式↔账户匹配（598608/598609）/ 状态机校验。
 - 费用报销全额冲销（payable_amt=0）的单不应再走付款。
 - 不适用：资金互转 / 盘盈盘亏 / 期初 / 红冲（无审批应付概念）。
 ## 八、影响评估 / 回滚
 - **影响**：此前能蒙混通过的金额不一致付款，现在报 598610。前端若一直传审批应付金额则无感。
 - **骑缝态**：前后端须同步上线，老前端允许改金额会被拦（属预期收紧）。
 - 回滚：revert PR #7714 即可，纯校验逻辑无数据迁移。
 ## 九、注意事项
 - 已部署测试服并行为级验证：少付 999 / 多付 1200 均被 598610 拦，正确金额 1000 放款成功。
 - Long 字段（bizId/payAccountId）JSON 传 number。
 ## 十、关联 / 联系人
 - Issue: [#7713](https://git.1814.love:8443/wx/HL/issues/7713)
 - PR: [#7714](https://git.1814.love:8443/wx/HL/pulls/7714)
 - 负责人: 腰苏图（yst）