diff --git a/changelogs-v2/2026-09/15_7695_出纳收付方式与账户两级校验-修改接口-管理后台.md b/changelogs-v2/2026-09/15_7695_出纳收付方式与账户两级校验-修改接口-管理后台.md new file mode 100644 index 00000000..937d410a --- /dev/null +++ b/changelogs-v2/2026-09/15_7695_出纳收付方式与账户两级校验-修改接口-管理后台.md @@ -0,0 +1,141 @@ +--- +schema: "hl-changelog/v2" +ticket: "7695" +title: "出纳收付方式↔出入账账户两级校验落地(新增 598609)" +consumer: "admin" +author: "yst(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-15" +status_note: "出纳 confirm-in / pay 各路径新增「收付方式↔出入账账户」匹配校验(新错误码 598609):现金方式须选现金账户、银行转账须选银行账户、三方支付须选对应渠道商户号账户;OUT 四分支(费用/应付款/预付款/员工借款放款)补齐方式↔渠道校验(598608),payMethod/payChannel 由可忽略变为校验。前端确认到账/登记付款/还款弹窗应按方式过滤账户下拉。" +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) diff --git a/changelogs-v2/2026-09/15_7710_资金账户详情删flows流水走独立分页-修改接口-管理后台.md b/changelogs-v2/2026-09/15_7710_资金账户详情删flows流水走独立分页-修改接口-管理后台.md new file mode 100644 index 00000000..84100fc6 --- /dev/null +++ b/changelogs-v2/2026-09/15_7710_资金账户详情删flows流水走独立分页-修改接口-管理后台.md @@ -0,0 +1,149 @@ +--- +schema: "hl-changelog/v2" +ticket: "7710" +title: "资金账户详情删 flows 字段,本账户流水改走独立分页接口" +consumer: "admin" +author: "yst(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-15" +status_note: "破坏性:GET /admin/finance/fund-accounts/{id} 出参删 flows 字段、入参删 flowPage/flowPageSize;本账户资金流水改调独立分页接口 GET /admin/finance/fund-flows/page?fundAccountId={id}(返回 records[])。同时更正并取代 2026-09-14 的 14_7695_flows对接说明(根因实为「对象vs数组」结构不匹配,最终方案是拆接口)。前端详情页需拆两接口调用并对齐 flowAt/balanceAfter 字段名。" +updated_at: "2026-09-15" +base: "dev-v3" +--- + +# 资金账户详情删 flows 字段,本账户流水改走独立分页接口(修改接口 · 破坏性) + +> **服务**: hl-order-service-v3(hl-finance 模块) +> **PR**: [#7711](https://git.1814.love:8443/wx/HL/pulls/7711) +> **Issue**: [#7710](https://git.1814.love:8443/wx/HL/issues/7710) +> **日期**: 2026-09-15(已部署测试服 + 行为级验证 PASS) +> **影响范围**: 资金账户详情接口出参/入参;本账户流水查询路径变更 + +--- + +## ⚠️ 关键变化(破坏性) + +🔴 **详情接口删除 flows**: +- `GET /admin/finance/fund-accounts/{id}` 出参**不再含 `flows`** 字段 +- 同接口入参**不再接受 `flowPage` / `flowPageSize`** + +🟢 **本账户流水改走独立分页接口**(已现成存在): + +```http +GET /admin/finance/fund-flows/page?fundAccountId={id}&pageNo=1&pageSize=10 +``` + +⚠️ **本文取代并更正 2026-09-14 的 `14_7695_资金账户详情flows本账户流水对接说明`**:那份把根因写成「records vs list 字段名」,实际更深一层——后端 flows 是 PageResult 分页**对象**、前端按**数组**判空(`Array.isArray` 恒 false),结构根本不匹配。最终方案不是前端改字段名,而是**详情删 flows、流水走独立分页接口**。 + +--- + +## 一、背景 + +资金账户详情「本账户资金流水」区块在管理后台恒空。根因:详情接口 flows 是 `PageResult` 对象,前端 `AccountDetailDrawer.vue` 按数组假设导致永远渲染空。经拍板,详情页拆两个接口——账户信息 + 流水分页分开,职责更清晰、流水可分页。独立流水分页接口早已具备,故详情接口直接删 flows。 + +## 二、变更清单 + +| 项 | 变更 | +|---|---| +| `GET /admin/finance/fund-accounts/{id}` 出参 | **删除 `flows` 字段** | +| `GET /admin/finance/fund-accounts/{id}` 入参 | **删除 `flowPage` / `flowPageSize`** | +| 本账户流水查询 | 改用 `GET /admin/finance/fund-flows/page?fundAccountId={id}` | + +## 三、接口详情 + +### 3.1 资金账户详情(改后) + +- **方法/路径**:`GET /admin/finance/fund-accounts/{id}` +- **入参**:仅路径 `{id}`,不再有 flowPage/flowPageSize +- **出参**:账户基础信息(id/accountName/accountNo/bankName/accountType/accountTypeName/nature/natureName/channel/channelName/balance/openingBalance/feeRate/status/remark/scopeCompanies 等),**无 flows** + +### 3.2 本账户流水分页(替代接口,现成) + +- **方法/路径**:`GET /admin/finance/fund-flows/page` +- **入参**(query): + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `fundAccountId` | long | ✅ | 账户ID(详情页传当前账户 id) | +| `pageNo` / `pageSize` | int | 否 | 分页 | +| `direction` | string | 否 | OUT 出账 / IN 入账 | +| `bizType` | string | 否 | NONBIZ/STAFF_LOAN/EXPENSE/TRANSFER/INVENTORY/OPENING 等 | +| `flowNo` | string | 否 | 流水号模糊 | +| `flowAtStart` / `flowAtEnd` | string | 否 | 收付日期范围 yyyy-MM-dd | + +- **出参**:`PageResult.records[]`,行字段: + +| 字段 | 类型 | 说明 | +|---|---|---| +| `id` | string | 流水ID | +| `flowNo` | string | 流水号 | +| `direction` | string | IN 收 / OUT 支 | +| `amount` | number | 金额 | +| `balanceAfter` | number | 该笔后结存(**注意:不是 balance**) | +| `bizType` | string | 业务类型 | +| `flowAt` | string | 发生时间(**注意:不是 time/createdAt**) | +| `remark` | string | 备注 | + +## 四、前端对接(详情页拆两接口) + +```js +// 1. 账户信息 +const detail = await getFundAccountDetail(id) // GET /fund-accounts/{id} + +// 2. 本账户流水(分页) +const flows = await getFundFlows({ // GET /fund-flows/page + fundAccountId: id, pageNo: 1, pageSize: 10 +}) +const list = flows.records // ✅ 数组在 records +// 行字段:flowAt(时间)、balanceAfter(结存)、direction、amount、bizType、flowNo、remark +``` + +**易错点**: +- 流水数组在 `flows.records`(不是 list)。 +- 时间字段是 `flowAt`,结存是 `balanceAfter`——按 time/createdAt/balance 取会显示 '—'。 +- direction:IN 显示 +金额(绿)、OUT 显示 −金额(红)。 + +## 五、示例 + +### 5.1 详情(改后无 flows) + +```http +GET /admin/finance/fund-accounts/2095340438738046977 +``` +→ `{ code:200, data:{ id, accountName, balance, ..., (无 flows) } }` + +### 5.2 本账户流水分页 + +```http +GET /admin/finance/fund-flows/page?fundAccountId=2095340438738046977&pageNo=1&pageSize=5 +``` +```json +{ "code": 200, "data": { "total": 6, "records": [ + { "flowNo": "LS202609140002", "direction": "IN", "amount": 99.0, "bizType": "NONBIZ", + "flowAt": "2026-09-14 17:18:42", "balanceAfter": 6389.0 } +] } } +``` + +## 六、影响评估 / 回滚 + +- **影响**:详情接口 flows 下线,前端若仍读 `detail.flows` 将拿到 undefined(应改调独立接口)。 +- **骑缝态**:前后端须同步上线;老前端详情流水区块会空(本就已空,无回退损失)。 +- 回滚:revert PR #7711 恢复 flows 字段。 + +## 七、注意事项 + +- 已部署测试服并实证:详情无 flows、独立分页接口返回本账户流水(含 NONBIZ/STAFF_LOAN/TRANSFER 等)。 +- Long 出参已序列化为 string。 + +## 八、关联 / 联系人 + +- Issue: [#7710](https://git.1814.love:8443/wx/HL/issues/7710) +- PR: [#7711](https://git.1814.love:8443/wx/HL/pulls/7711) +- 取代/更正: `changelogs-v2/2026-09/14_7695_资金账户详情flows本账户流水对接说明-修改接口-管理后台.md` +- 负责人: 腰苏图(yst)