docs(finance): 资金统计日报前端纠错——查询参数是 startDate/endDate 不是 dateFrom/dateTo

后端契约零变更，仅前端对接说明：GET /admin/finance/fund-stats/daily 参数名 startDate/endDate，前端误传 dateFrom/dateTo 致 @NotNull 拦截返 400；附实测复现 + 正反例 + 400 兜底建议（勿留静态期初占位行掩盖）。
2026-09-15 14:09:02 +08:00
@@ -0,0 +1,139 @@
+---
+schema: "hl-changelog/v2"
+ticket: "frontend-finance-fund-stats-params"
+title: "资金统计日报查询参数是 startDate/endDate，不是 dateFrom/dateTo（前端对接纠错）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-15"
+status_note: "后端契约零变更，仅前端对接纠错：资金统计日报 GET /admin/finance/fund-stats/daily 的查询参数是 startDate/endDate（yyyy-MM-dd，均必填），前端误传 dateFrom/dateTo 导致参数绑定不上，后端 @NotNull 拦截返回 code 400「统计起始日不能为空;统计截止日不能为空」。前端需改参数名并对 400 做兜底提示，勿留静态占位行掩盖。"
+updated_at: "2026-09-15"
+base: "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）：
+
+1. 进入页面**不自动发请求**（那行「期初结转」是前端静态占位，非接口数据）；
+2. 手动填日期点「搜索」，前端发出：
+
+```http
+GET /admin/finance/fund-stats/daily?dateFrom=2026-09-01&dateTo=2026-09-15
+```
+
+3. 后端响应（外层 HTTP 200 是 Result 包装，业务码才是真状态）：
+
+```json
+{ "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 资金日报](09_7003_资金日报-新增接口-管理后台.md)。收支聚合排除 `biz_type=OPENING` 期初留痕流水。
+
+## 三、示例
+
+### 3.1 反例：参数名误用 dateFrom/dateTo → 400
+
+```http
+GET /admin/finance/fund-stats/daily?dateFrom=2026-09-01&dateTo=2026-09-15
+```
+
+```json
+{ "code": 400, "message": "统计截止日不能为空; 统计起始日不能为空", "success": false }
+```
+
+### 3.2 正例：用 startDate/endDate → 成功
+
+```http
+GET /admin/finance/fund-stats/daily?startDate=2026-09-01&endDate=2026-09-15
+```
+
+```json
+{
+  "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 }
+    ]
+  }
+}
+```
+
+## 四、前端对接建议
+
+1. **改参数名**：请求查询串用 `startDate`/`endDate`（yyyy-MM-dd），别用 `dateFrom`/`dateTo`。
+2. **错误兜底**：响应 `code !== 200` 时显示 `message` 提示（如参数缺失/区间非法 595302/跨度超限 595303），不要静默渲染静态占位行。
+3. **判空逻辑**：`days` 为空数组 ≠ 接口异常——是区间内无业务流水，正常显示"本期无收支"即可，与 400 区分开。
+4. `accountId` 留空即全账户汇总；单账户统计才传具体 ID。
+
+## 五、影响评估 / 回滚
+
+- **后端零变更**，本次仅为对接说明，无需发版、无需回滚。
+- 前端改对参数名 + 补 400 兜底后即可正常显示数据，无需等待后端任何动作。
+
+## 六、关联 / 联系人
+
+- 关联 changelog：[09_7003_资金日报-新增接口](09_7003_资金日报-新增接口-管理后台.md)（Issue [#7003](https://git.1814.love:8443/wx/HL/issues/7003)）
+- 负责人: 腰苏图（yst）
+- 反馈入口: 财务域后端对接群 / 直接 @yst