---
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）