wx/hl-api-changelog

派生 0

文件

T

Mimingguang bd0d4f5077

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

详情

chore(changelog): 资金统计日报参数纠错前端已修复回写 verified(mmg,ref 7985051b)

2026-09-15 14:26:33 +08:00

6.0 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	frontend-finance-fund-stats-params	资金统计日报查询参数是 startDate/endDate，不是 dateFrom/dateTo（前端对接纠错）	admin	yst(GIT)	修改接口	deployed	verified	verified	mmg	7985051b6eb5506a6498467097c896015aed8c76		2026-09-15	后端契约零变更，仅前端对接纠错：资金统计日报 GET /admin/finance/fund-stats/daily 的查询参数是 startDate/endDate（yyyy-MM-dd，均必填），前端误传 dateFrom/dateTo 导致参数绑定不上，后端 @NotNull 拦截返回 code 400「统计起始日不能为空;统计截止日不能为空」。前端需改参数名并对 400 做兜底提示，勿留静态占位行掩盖。前端已修复(7985051b):stats 页查询参数改 startDate/endDate;catch 补 message 兜底提示(__handled 不重复弹);期初结转首行改仅查询成功后渲染,未查询/失败不再留静态占位行;fund-stat.js 文档同步;新增 spec 4 例,checkpoint 13 项全绿。	2026-09-15	dev-v3

资金统计日报查询参数是 startDate/endDate，不是 dateFrom/dateTo（前端对接纠错）

服务: hl-order-service-v3（hl-finance 模块）类型: ⚠️ 前端对接纠错说明（后端契约无任何变更，无需发版）日期: 2026-09-15 影响范围: 资金统计查询页（/finance/fund/stats）调资金日报接口的查询参数名 + 错误兜底

🔴 一句话给前端

资金统计日报接口的日期区间参数名是 startDate / endDate，不是 dateFrom / dateTo。

后端契约（正确）	❌ 前端当前误传（会 400）
`startDate`（起始日，必填）	`dateFrom`
`endDate`（截止日，必填）	`dateTo`

参数名对不上 → 后端拿不到 startDate/endDate → @NotNull 拦截 → 返回 code:400「统计截止日不能为空; 统计起始日不能为空」。

同时：前端拿到 400 后必须兜底显示错误提示，不要让页面只显示一行静态「期初结转 0.00」占位——那会让人误以为"接口没数据"，实际是请求被拒了。

一、背景（实测复现）

资金统计查询页面（前端路由 /finance/fund/stats）现象：页面只显示一行「期初结转 0.00」，看不到任何收支数据，看似"后端没数据"。

浏览器实测（测试服 192.168.100.219:9527）：

进入页面不自动发请求（那行「期初结转」是前端静态占位，非接口数据）；
手动填日期点「搜索」，前端发出：

GET /admin/finance/fund-stats/daily?dateFrom=2026-09-01&dateTo=2026-09-15

后端响应（外层 HTTP 200 是 Result 包装，业务码才是真状态）：

{ "code": 400, "message": "统计截止日不能为空; 统计起始日不能为空", "data": null, "success": false }

结论：后端接口正常、流水数据也在，纯粹是前端参数名写错 + 400 未兜底渲染。

二、接口契约（正确入参）

GET /admin/finance/fund-stats/daily

入参（Query）：

字段	必填	说明
`accountId`	否	资金账户 ID；空 = 全部账户汇总（互转双边计入）
`startDate`	✅ 是	统计起始日（yyyy-MM-dd，含当日）
`endDate`	✅ 是	统计截止日（yyyy-MM-dd，含当日）

出参（FundDailyStatsRespVO，仅列关键字段）：

字段	类型	说明
`openingBalance`	BigDecimal	期初结转（=当前结存−起始日以来流水净影响）
`priorIncome` / `priorExpense`	BigDecimal	起始日前累计收入/支出
`totalIncome` / `totalExpense`	BigDecimal	区间总收入/总支出
`closingBalance`	BigDecimal	期末结存 = openingBalance + totalIncome − totalExpense
`days`	Array	逐日明细（仅有流水的日期，无流水日期不返回，前端可自行补零）

完整字段/错误码/口径见 #7003 资金日报。收支聚合排除 biz_type=OPENING 期初留痕流水。

三、示例

3.1 反例：参数名误用 dateFrom/dateTo → 400

GET /admin/finance/fund-stats/daily?dateFrom=2026-09-01&dateTo=2026-09-15

{ "code": 400, "message": "统计截止日不能为空; 统计起始日不能为空", "success": false }

3.2 正例：用 startDate/endDate → 成功

GET /admin/finance/fund-stats/daily?startDate=2026-09-01&endDate=2026-09-15

{
  "code": 200,
  "success": true,
  "data": {
    "openingBalance": 12000.00,
    "priorIncome": 0, "priorExpense": 0,
    "totalIncome": 8000.00, "totalExpense": 5000.00,
    "closingBalance": 15000.00,
    "days": [
      { "date": "2026-09-03", "income": 5000.00, "expense": 0, "dayNet": 5000.00, "runningBalance": 17000.00 }
    ]
  }
}

四、前端对接建议

改参数名：请求查询串用 startDate/endDate（yyyy-MM-dd），别用 dateFrom/dateTo。
错误兜底：响应 code !== 200 时显示 message 提示（如参数缺失/区间非法 595302/跨度超限 595303），不要静默渲染静态占位行。
判空逻辑：days 为空数组 ≠ 接口异常——是区间内无业务流水，正常显示"本期无收支"即可，与 400 区分开。
accountId 留空即全账户汇总；单账户统计才传具体 ID。

五、影响评估 / 回滚

后端零变更，本次仅为对接说明，无需发版、无需回滚。
前端改对参数名 + 补 400 兜底后即可正常显示数据，无需等待后端任何动作。

六、关联 / 联系人

关联 changelog：09_7003_资金日报-新增接口（Issue #7003）
负责人: 腰苏图（yst）
反馈入口: 财务域后端对接群 / 直接 @yst

6.0 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape