From a1c85b40610441c6690e2fa6e462fab64394490c Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Tue, 15 Sep 2026 14:08:42 +0800
Subject: [PATCH] =?UTF-8?q?docs(finance):=20=E8=B5=84=E9=87=91=E7=BB=9F?=
 =?UTF-8?q?=E8=AE=A1=E6=97=A5=E6=8A=A5=E5=89=8D=E7=AB=AF=E7=BA=A0=E9=94=99?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E6=9F=A5=E8=AF=A2=E5=8F=82=E6=95=B0=E6=98=AF?=
 =?UTF-8?q?=20startDate/endDate=20=E4=B8=8D=E6=98=AF=20dateFrom/dateTo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

后端契约零变更，仅前端对接说明：GET /admin/finance/fund-stats/daily 参数名
startDate/endDate，前端误传 dateFrom/dateTo 致 @NotNull 拦截返 400；附实测复现 +
正反例 + 400 兜底建议（勿留静态期初占位行掩盖）。
---
 ...tDate-endDate不是dateFrom-dateTo-修改接口-管理后台.md | 139 ++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 changelogs-v2/2026-09/15_fund-stats_资金统计日报查询参数是startDate-endDate不是dateFrom-dateTo-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-09/15_fund-stats_资金统计日报查询参数是startDate-endDate不是dateFrom-dateTo-修改接口-管理后台.md b/changelogs-v2/2026-09/15_fund-stats_资金统计日报查询参数是startDate-endDate不是dateFrom-dateTo-修改接口-管理后台.md
new file mode 100644
index 00000000..06abc920
--- /dev/null
+++ b/changelogs-v2/2026-09/15_fund-stats_资金统计日报查询参数是startDate-endDate不是dateFrom-dateTo-修改接口-管理后台.md
@@ -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