144 行
6.1 KiB
Markdown
144 行
6.1 KiB
Markdown
---
|
||
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）
|