6.1 KiB
6.1 KiB
schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
| schema | ticket | title | consumer | author | change_type | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 7713 | 出纳付款金额锁死：金额须等于审批应付金额（新增 598610） | admin | yst(GIT) | 修改接口 | deployed | verified | verified | mmg | dea4a6e7e2bd5541527796db5fdc116a1be7a33a | 2026-09-15 | 破坏性收紧：出纳 POST /admin/finance/cashier/pay 5 条 OUT 分支（业务外支出/费用报销/应付款/预付款/员工借款放款）付款金额从「可任意改（仅 WARN）」改为「必须等于审批应付金额」，不一致抛新错误码 598610。前端付款弹窗金额输入框应改为只读展示审批应付金额，否则用户改了会被 598610 拦。 前端已对齐：登记付款弹窗金额改只读展示（原型口径），hl-admin@dea4a6e7。 | 2026-09-15 | dev-v3 |
出纳付款金额锁死：金额须等于审批应付金额（修改接口 · 破坏性收紧）
服务: hl-order-service-v3（hl-finance 模块） PR: #7714 Issue: #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：
POST /admin/finance/cashier/pay
{ "bizType":"STAFF_LOAN","bizId":2099067894846345217,
"payAccountId":2095431817594028033,"payMethod":"CASH","amount":999,"payDate":"2026-09-15" }
{ "code": 598610, "message": "付款金额与单据应付金额不一致（出纳付款须严格按审批应付金额，不得修改）", "success": false }
5.2 反例：多付 → 598610
同上单据实付 1200，同样返回 598610。
5.3 正例：金额一致 → 放款成功
POST /admin/finance/cashier/pay
{ "bizType":"STAFF_LOAN","bizId":2099067894846345217,
"payAccountId":2095431817594028033,"payMethod":"CASH","amount":1000,"payDate":"2026-09-15" }
→ { "code": 200, "message": "成功" }，借款单状态 → PAID。
六、前端对接建议（重要）
付款弹窗的金额输入框应改为只读，展示该单据的审批应付金额（由后端在待付款队列/详情给出），不要再让用户编辑：
// ❌ 原来：可编辑
<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。