---
schema: "hl-changelog/v2"
ticket: "7713"
title: "出纳付款金额锁死：金额须等于审批应付金额（新增 598610）"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "dea4a6e7e2bd5541527796db5fdc116a1be7a33a"
target_release: ""
verified_at: "2026-09-15"
status_note: "破坏性收紧：出纳 POST /admin/finance/cashier/pay 5 条 OUT 分支（业务外支出/费用报销/应付款/预付款/员工借款放款）付款金额从「可任意改（仅 WARN）」改为「必须等于审批应付金额」，不一致抛新错误码 598610。前端付款弹窗金额输入框应改为只读展示审批应付金额，否则用户改了会被 598610 拦。 前端已对齐：登记付款弹窗金额改只读展示（原型口径），hl-admin@dea4a6e7。"
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）