150 行
6.3 KiB
Markdown
150 行
6.3 KiB
Markdown
---
|
||
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）
|