docs(changelog): 资金账户详情 flows 本账户流水对接说明 (Issue #7695)
changelog-filename-gate / validate (push) Failing after 1s
changelog-filename-gate / validate (push) Failing after 1s
这个提交包含在：
yaosutu
@@ -0,0 +1,131 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "7695"
|
||||
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: ""
|
||||
status_note: "对接指引：GET /admin/finance/fund-accounts/{id} 详情返回里已含 flows（本账户资金流水分页），后端实证正常返回数据。前端「本账户资金流水」区块显示为空，多为取数字段名或账户 id 未对上——本文给出正确对接方式与易错点。"
|
||||
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）
|
||||
在新工单中引用
屏蔽一个用户