7.1 KiB
7.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 | 7695 | 出纳收付方式↔出入账账户两级校验落地（新增 598609） | admin | yst(GIT) | 修改接口 | deployed | verified | verified | mmg | 5f0d3abb5192acbc5999f265236f0f3441203383 | 2026-09-15 | 出纳 confirm-in / pay 各路径新增「收付方式↔出入账账户」匹配校验（新错误码 598609）：现金方式须选现金账户、银行转账须选银行账户、三方支付须选对应渠道商户号账户；OUT 四分支（费用/应付款/预付款/员工借款放款）补齐方式↔渠道校验（598608），payMethod/payChannel 由可忽略变为校验。前端确认到账/登记付款/还款弹窗应按方式过滤账户下拉。 前端已对齐：登记付款/还款核销/确认到账弹窗账户下拉按方式过滤（三方再按渠道精配），方式切换清错配已选，hl-admin@5f0d3abb。 | 2026-09-15 | dev-v3 |
出纳收付方式↔出入账账户两级校验落地（修改接口）
服务: hl-order-service-v3（hl-finance 模块） PR: #7698 Issue: #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
POST /admin/finance/cashier/confirm-in
{ "bizId": 2099531798860951553, "payAccountId": 2095340438738046977,
"payMethod": "CASH", "payDate": "2026-09-15" }
（2095340438738046977 是银行账户）
{ "code": 598609, "message": "收付账户与收付方式不匹配（现金方式须选现金账户、银行转账须选银行账户、三方支付须选对应渠道商户号账户）", "success": false }
5.2 反例：银行方式选现金账户 → 598609
POST /admin/finance/cashier/confirm-in
{ "bizId": 2099531798860951553, "payAccountId": 2095431817594028033,
"payMethod": "BANK", "payDate": "2026-09-15" }
（2095431817594028033 是现金账户）→ 返回同上 598609。
5.3 正例：现金方式选现金账户 → 成功
POST /admin/finance/cashier/confirm-in
{ "bizId": 2099531798860951553, "payAccountId": 2095431817594028033,
"payMethod": "CASH", "payDate": "2026-09-15" }
→ { "code": 200, "message": "成功", "success": true }
六、前端对接建议
确认到账 / 登记付款 / 还款弹窗的「出入账账户」下拉，按所选收付方式过滤：
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。