142 行
7.1 KiB
Markdown
142 行
7.1 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7695"
|
||
title: "出纳收付方式↔出入账账户两级校验落地（新增 598609）"
|
||
consumer: "admin"
|
||
author: "yst(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "5f0d3abb5192acbc5999f265236f0f3441203383"
|
||
target_release: ""
|
||
verified_at: "2026-09-15"
|
||
status_note: "出纳 confirm-in / pay 各路径新增「收付方式↔出入账账户」匹配校验（新错误码 598609）：现金方式须选现金账户、银行转账须选银行账户、三方支付须选对应渠道商户号账户；OUT 四分支（费用/应付款/预付款/员工借款放款）补齐方式↔渠道校验（598608），payMethod/payChannel 由可忽略变为校验。前端确认到账/登记付款/还款弹窗应按方式过滤账户下拉。 前端已对齐：登记付款/还款核销/确认到账弹窗账户下拉按方式过滤（三方再按渠道精配），方式切换清错配已选，hl-admin@5f0d3abb。"
|
||
updated_at: "2026-09-15"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 出纳收付方式↔出入账账户两级校验落地（修改接口）
|
||
|
||
> **服务**: hl-order-service-v3（hl-finance 模块）
|
||
> **PR**: [#7698](https://git.1814.love:8443/wx/HL/pulls/7698)
|
||
> **Issue**: [#7695](https://git.1814.love:8443/wx/HL/issues/7695)
|
||
> **日期**: 2026-09-15（已部署测试服 + 行为级验证 PASS）
|
||
> **影响范围**: 出纳 confirm-in / pay 各路径 + 员工借款还款的**入参语义收紧** + 新增 1 错误码；不涉及路由/字段名变化
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
🔴 **新增校验**：「收付方式」和「出入账账户」现在必须类型匹配，否则报 **598609**：
|
||
|
||
| 收付方式 payMethod | 必须选择的账户类型 |
|
||
|---|---|
|
||
| `CASH` 现金 | 现金账户（accountType=CASH） |
|
||
| `BANK` 银行转账 | 银行账户（accountType=BANK） |
|
||
| `THIRD_PARTY` 三方支付 | 三方账户（accountType=THIRD_PARTY）且渠道匹配（payChannel=WXPAY→微信商户号 / ALIPAY→支付宝商户号） |
|
||
|
||
🔴 **OUT 四分支补齐校验**：费用报销/应付款/预付款/员工借款放款（cashier pay 的 EXPENSE/PAYMENT/PREPAY/STAFF_LOAN 分支）此前**静默丢弃** payMethod/payChannel，现在纳入校验——非法方式↔渠道组合报 598608，方式↔账户错配报 598609。
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
方案甲（#7681）把收付方式收口为「账户类型+渠道」两维后，方式与账户码值已同源对齐，但后端执行路径未校验两者匹配——传「现金方式 + 银行账户 ID」会被放行（只要账户 ACTIVE），导致「现金进银行账户」「微信款进支付宝户」可穿透。本次补上方式↔账户两级硬校验。
|
||
|
||
## 二、变更清单
|
||
|
||
| 接口/路径 | 变更 |
|
||
|---|---|
|
||
| `POST /admin/finance/cashier/confirm-in`（业务外收入确认到账，IN） | 新增方式↔账户匹配校验（598609） |
|
||
| `POST /admin/finance/cashier/pay`（登记付款，OUT）bizType=NONBIZ | 新增方式↔账户校验（598609） |
|
||
| 同上 bizType=EXPENSE / PAYMENT / PREPAY / STAFF_LOAN（OUT 四分支） | **补齐**方式↔渠道校验（598608）+ 方式↔账户校验（598609），payMethod/payChannel 不再被忽略 |
|
||
| `POST /admin/finance/staff-loans/{id}/repays`（员工借款还款，IN） | 新增 repayWay（CASH/BANK）↔账户类型校验（598609） |
|
||
| 错误码 | 新增 **598609** |
|
||
|
||
## 三、入参（语义收紧）
|
||
|
||
### confirm-in / pay 共有
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `payMethod` | string | 否 | 收付方式：CASH/BANK/THIRD_PARTY。**传入即校验**：须与 payAccountId 对应账户类型匹配 |
|
||
| `payChannel` | string | 条件 | 收付渠道：WXPAY/ALIPAY，仅 payMethod=THIRD_PARTY 时必填（否则 598608），且须匹配账户 channel（否则 598609） |
|
||
| `payAccountId` | long | ✅ | 出入账账户 ID（fin_fund_account，须 ACTIVE），**其 accountType/channel 须与 payMethod/payChannel 匹配** |
|
||
|
||
> payMethod 留空仍从宽（不校验账户匹配，口径同方案甲）；一旦传入就必须与账户匹配。
|
||
|
||
## 四、错误码
|
||
|
||
| 码 | 含义 | 触发 |
|
||
|---|---|---|
|
||
| **598609**（新增） | 收付账户与收付方式不匹配 | payMethod=CASH 选了银行/三方户；payMethod=BANK 选了现金/三方户；payMethod=THIRD_PARTY 选了非三方户或渠道不符（WXPAY 选支付宝户）；repayWay=CASH 入银行户 等 |
|
||
| 598608（既有，现 OUT 四分支也生效） | 收付方式与收付渠道不匹配 | THIRD_PARTY 未传/传错 payChannel；非 THIRD_PARTY 却传了 payChannel |
|
||
|
||
## 五、示例
|
||
|
||
### 5.1 反例：现金方式选银行账户 → 598609
|
||
|
||
```http
|
||
POST /admin/finance/cashier/confirm-in
|
||
{ "bizId": 2099531798860951553, "payAccountId": 2095340438738046977,
|
||
"payMethod": "CASH", "payDate": "2026-09-15" }
|
||
```
|
||
（2095340438738046977 是银行账户）
|
||
|
||
```json
|
||
{ "code": 598609, "message": "收付账户与收付方式不匹配（现金方式须选现金账户、银行转账须选银行账户、三方支付须选对应渠道商户号账户）", "success": false }
|
||
```
|
||
|
||
### 5.2 反例：银行方式选现金账户 → 598609
|
||
|
||
```http
|
||
POST /admin/finance/cashier/confirm-in
|
||
{ "bizId": 2099531798860951553, "payAccountId": 2095431817594028033,
|
||
"payMethod": "BANK", "payDate": "2026-09-15" }
|
||
```
|
||
（2095431817594028033 是现金账户）→ 返回同上 598609。
|
||
|
||
### 5.3 正例：现金方式选现金账户 → 成功
|
||
|
||
```http
|
||
POST /admin/finance/cashier/confirm-in
|
||
{ "bizId": 2099531798860951553, "payAccountId": 2095431817594028033,
|
||
"payMethod": "CASH", "payDate": "2026-09-15" }
|
||
```
|
||
→ `{ "code": 200, "message": "成功", "success": true }`
|
||
|
||
## 六、前端对接建议
|
||
|
||
确认到账 / 登记付款 / 还款弹窗的「出入账账户」下拉，按所选收付方式过滤：
|
||
|
||
```http
|
||
GET /admin/finance/fund-accounts/page?accountType={CASH|BANK|THIRD_PARTY}&status=ACTIVE&pageNo=1&pageSize=100
|
||
```
|
||
|
||
三方支付时进一步按渠道过滤（accountType=THIRD_PARTY + 账户 channel 与 payChannel 一致）。从根上避免用户选出矛盾组合被 598609 拦。
|
||
|
||
## 七、业务边界
|
||
|
||
- 校验只拦「方式↔账户」错配，不动既有金额/状态/账户 ACTIVE 校验。
|
||
- 员工借款还款走自有 repayWay 枚举（CASH/BANK），同规则：CASH→现金户、BANK→银行户。
|
||
- 不适用域：资金互转（已有 mode.matches 校验）、盘盈盘亏/期初调整/红冲（无收付方式概念）。
|
||
|
||
## 八、影响评估 / 回滚
|
||
|
||
- **影响**：此前能蒙混的错配组合现在报 598609；OUT 四分支传非法方式渠道组合现在报 598608。前端若一直传正确组合则无感。
|
||
- **骑缝态**：前后端须同步上线，老前端传错配组合会被拦（属预期收紧）。
|
||
- 回滚：revert PR #7698 即可，纯校验逻辑无数据迁移。
|
||
|
||
## 九、注意事项
|
||
|
||
- 已部署测试服并行为级验证（598609 正反例 + 正例入账成功）。
|
||
- Long 字段（bizId/payAccountId）JSON 传 number。
|
||
|
||
## 十、关联 / 联系人
|
||
|
||
- Issue: [#7695](https://git.1814.love:8443/wx/HL/issues/7695)
|
||
- PR: [#7698](https://git.1814.love:8443/wx/HL/pulls/7698)
|
||
- 负责人: 腰苏图（yst）
|