docs(changelog): 出纳方式↔账户两级校验(598609) + 资金账户详情删flows走独立分页 (Issue #7695/#7710)

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）

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）