---
schema: "hl-changelog/v2"
ticket: "7695"
title: "资金账户详情 flows（本账户资金流水）字段对接说明"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "902fe6b0a966cf6ae28d7aea417799295d746fe5"
target_release: ""
verified_at: "2026-09-15"
status_note: "对接指引：GET /admin/finance/fund-accounts/{id} 详情返回里已含 flows（本账户资金流水分页），后端实证正常返回数据。前端「本账户资金流水」区块显示为空，多为取数字段名或账户 id 未对上——本文给出正确对接方式与易错点。 前端已对齐：flowList 按信封 flows.records 取数，流水号/时间/结存列改 flowNo/flowAt/balanceAfter 契约键，hl-admin@902fe6b0。"
updated_at: "2026-09-14"
base: "dev-v3"
---

# 资金账户详情 flows（本账户资金流水）字段对接说明

> **服务**: hl-order-service-v3（hl-finance 模块）
> **关联**: Issue [#7695](https://git.1814.love:8443/wx/HL/issues/7695)
> **日期**: 2026-09-14
> **性质**: 对接指引（非接口契约变更）——后端已含 flows 且实证正常，前端需按本文对齐渲染

---

## ⚠️ 一句话结论

「账户档案 → 查看 → 本账户资金流水」**后端接口本来就有数据**，字段路径是 **`data.flows.records[]`**。前端页面显示为空，**几乎都是取数字段名写错或账户 id 用错**，请按下文对齐。

---

## 一、背景

业务外收入/支出经出纳 confirm-in / 登记付款后，资金流水（fin_fund_flow）已正常生成并挂到对应资金账户。用户反馈「资金账户详情里的本账户资金流水没有显示」。经真实接口 + DB 实证：**后端 `GET /admin/finance/fund-accounts/{id}` 的 `flows` 字段完整返回流水**，问题在前端对接。

## 二、接口详情

- **方法/路径**：`GET /admin/finance/fund-accounts/{id}`
- **说明**：资金账户详情，返回账户基础信息 + `flows`（本账户资金流水分页，默认该账户全部流水，按 flowAt 倒序）

## 三、出参（flows 结构）

顶层 `data` 含账户字段（id/accountName/balance/accountType/accountTypeName/channel/channelName/status 等）+ **`flows`**：

```
data.flows        —— PageResult 分页对象
data.flows.total  —— 本账户流水总条数
data.flows.records —— ⭐ 流水数组（注意：是 records 不是 list！）
```

`flows.records[]` 每条字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 流水ID（Long 序列化为 string） |
| `flowNo` | string | 流水号（LS+日期+序号） |
| `direction` | string | 方向：`IN` 收 / `OUT` 支 |
| `amount` | number | 金额 |
| `balanceAfter` | number | 该笔后结存 |
| `bizType` | string | 业务类型：`NONBIZ` 业务外收支 / `STAFF_LOAN` 员工借款 / `EXPENSE` 费用报销 / `TRANSFER` 账户互转 / `INVENTORY` 盘盈盘亏 / `OPENING` 期初 等 |
| `flowAt` | string | 发生时间 `yyyy-MM-dd HH:mm:ss` |
| `remark` | string | 备注（互转备注/盘盈盘亏/期初原因等） |

## 四、实证数据（2026-09-14 测试服实测）

`GET /admin/finance/fund-accounts/2095340438738046977`（呼籁国际-一般户）返回：

```
code: 200
data.flows.total = 6
data.flows.records = [
  { flowNo: "LS202609140002", direction: "IN",  amount: 99.0,  bizType: "NONBIZ",    flowAt: "2026-09-14 17:18:42" },
  { flowNo: "LS202609140001", direction: "IN",  amount: 300.0, bizType: "NONBIZ",    flowAt: "2026-09-14 15:38:06" },
  { flowNo: "LS202609130007", direction: "IN",  amount: 990.0, bizType: "NONBIZ",    flowAt: "2026-09-13 23:53:58" },
  { flowNo: "LS202609130006", direction: "OUT", amount: 100.0, bizType: "TRANSFER",  flowAt: "2026-09-13 16:02:11" },
  ...
]
```

**结论：接口已正常返回本账户流水，含业务外收支（NONBIZ）流水。**

## 五、前端对接要点（易错点）

1. **字段名是 `records` 不是 `list`**：本接口分页结构遵循统一 `PageResult`，流水数组在 `data.flows.records`。若前端按 `data.flows.list` 取数会得到 `undefined` → 渲染空。**这是最可能的空值根因。**
2. **账户 id 要用对**：流水挂在「确认收款/登记付款时选的入账/出账账户」上。例：业务外收入选的是「呼籁国际-一般户」（id `...6977`），流水就挂这个户；打开「基本户」（id `...3041`）详情自然看不到。**确认详情页传入的 `{id}` 是流水实际归属的账户。**
3. **无需另调接口**：`flows` 已随详情一并返回，不必再单独调 `/admin/finance/fund-flows/page`（该接口是独立流水查询页用）。
4. **展示建议**：方向 IN 显示 +金额（绿）、OUT 显示 −金额（红）；bizType 转中文（NONBIZ→业务外收支 等）；空数组时显示「本账户暂无流水」占位。

## 六、示例

### 请求

```http
GET /admin/finance/fund-accounts/2095340438738046977
Authorization: Bearer <token>
```

### 正确取数（伪代码）

```js
// ✅ 正确
const flows = res.data.flows.records   // 注意 records
const total = res.data.flows.total

// ❌ 错误（会拿到 undefined 渲染空）
const flows = res.data.flows.list
```

## 七、业务边界

- `flows` 只含**当前账户**的流水（按 fund_account_id 过滤），无方向/业务类型额外排除。
- 流水是资金动作的结果（出纳 confirm-in / 登记付款 / 互转 / 盘盈盘亏 / 期初等），建单/审批中不产生流水。
- Long 出参（id 等）已序列化为 string，前端勿当 number 比较。

## 八、影响评估 / 回滚

- 纯对接指引，无后端契约变更，无回滚风险。
- 前端按 `flows.records` 对齐后即可显示；无需后端配合。

## 九、注意事项

- 若按本文对齐后仍空，请提供该请求的**完整 URL（含账户 id）+ Response body** 反馈给后端复查。
- 原型 `finance-prototype.html` 的账户流水是纯前端 mock（localStorage），与本真实接口数据不通，勿混。

## 十、关联 / 联系人

- Issue: [#7695](https://git.1814.love:8443/wx/HL/issues/7695)
- 负责人: 腰苏图（yst）