From 4917e44e6a7d181ff59cc9ce8ac032b72c538eb6 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Tue, 15 Sep 2026 02:40:43 +0800
Subject: [PATCH] =?UTF-8?q?feat(finance):=20=E5=87=BA=E7=BA=B3=E4=BB=98?=
=?UTF-8?q?=E6=AC=BE=E9=87=91=E9=A2=9D=E9=94=81=E6=AD=BB=20changelog?=
=?UTF-8?q?=EF=BC=88598610=EF=BC=8C#7713=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
5 条 OUT 付款线金额须等于审批应付金额，不一致抛 598610；
前端付款弹窗金额应改只读。
---
...7713_出纳付款金额锁死-修改接口-管理后台.md | 143 ++++++++++++++++++
1 file changed, 143 insertions(+)
create mode 100644 changelogs-v2/2026-09/15_7713_出纳付款金额锁死-修改接口-管理后台.md
diff --git a/changelogs-v2/2026-09/15_7713_出纳付款金额锁死-修改接口-管理后台.md b/changelogs-v2/2026-09/15_7713_出纳付款金额锁死-修改接口-管理后台.md
new file mode 100644
index 00000000..974dcf38
--- /dev/null
+++ b/changelogs-v2/2026-09/15_7713_出纳付款金额锁死-修改接口-管理后台.md
@@ -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
+// ❌ 原来：可编辑
+
+
+// ✅ 建议：只读展示审批应付金额
+{{ payableAmount }} // 随 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）