From b80d3e3ca22eaeb71b6c0ba3c14cc00f65e5868b Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Mon, 14 Sep 2026 23:38:11 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=B5=84=E9=87=91=E8=B4=A6?=
 =?UTF-8?q?=E6=88=B7=E8=AF=A6=E6=83=85=20flows=20=E6=9C=AC=E8=B4=A6?=
 =?UTF-8?q?=E6=88=B7=E6=B5=81=E6=B0=B4=E5=AF=B9=E6=8E=A5=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=20(Issue=20#7695)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...�情flows本账户流水对接说明-修改接口-管理后台.md | 131 ++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 changelogs-v2/2026-09/14_7695_资金账户详情flows本账户流水对接说明-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-09/14_7695_资金账户详情flows本账户流水对接说明-修改接口-管理后台.md b/changelogs-v2/2026-09/14_7695_资金账户详情flows本账户流水对接说明-修改接口-管理后台.md
new file mode 100644
index 00000000..c1cfade2
--- /dev/null
+++ b/changelogs-v2/2026-09/14_7695_资金账户详情flows本账户流水对接说明-修改接口-管理后台.md
@@ -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）