wx/hl-api-changelog

派生 0

文件

T

Mimingguang 2bfed6bf0f

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): #7695 回写前端已对齐(verified,hl-admin@902fe6b0)

2026-09-15 00:04:58 +08:00

6.1 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

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

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

服务: hl-order-service-v3（hl-finance 模块）关联: Issue #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）流水。

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

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

六、示例

请求

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

正确取数（伪代码）

// ✅ 正确
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
负责人: 腰苏图（yst）

6.1 KiB 原始文件 Blame 文件历史 Unescape Escape