diff --git a/changelogs-v2/2026-09/15_fund-stats_点日期下钻日期走query不拼路径查明细用fund-flows-page-修改接口-管理后台.md b/changelogs-v2/2026-09/15_fund-stats_点日期下钻日期走query不拼路径查明细用fund-flows-page-修改接口-管理后台.md new file mode 100644 index 00000000..7bcf7ba5 --- /dev/null +++ b/changelogs-v2/2026-09/15_fund-stats_点日期下钻日期走query不拼路径查明细用fund-flows-page-修改接口-管理后台.md @@ -0,0 +1,123 @@ +--- +schema: "hl-changelog/v2" +ticket: "frontend-finance-fund-stats-drilldown" +title: "资金统计点日期下钻:日期走 query 不拼路径;看某天明细用 fund-flows/page(前端对接纠错)" +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/2026-09-05」——前端把日期拼成了 URL 路径段,但 /daily 只有 query 传参(startDate/endDate),无 /daily/{date} 路径故 404。若意图是点日期下钻看当天资金流水明细,应调 GET /admin/finance/fund-flows/page?flowAtStart=flowAtEnd=该日(账户 fundAccountId 可空=全部)。" +updated_at: "2026-09-15" +base: "dev-v3" +--- + +# 资金统计点日期下钻:日期走 query 不拼路径;看某天明细用 fund-flows/page(前端对接纠错) + +> **服务**: hl-order-service-v3(hl-finance 模块) +> **类型**: ⚠️ 前端对接纠错说明(后端契约**无任何变更**,无需发版) +> **日期**: 2026-09-15 +> **影响范围**: 资金统计查询页(`/finance/fund/stats`)「点日期」交互的接口调用 + +--- + +## 🔴 一句话给前端 + +**`/admin/finance/fund-stats/daily` 的日期只能放 query 参数(`startDate`/`endDate`),不能拼进 URL 路径。** + +| 操作 | ❌ 错误(404 接口不存在) | ✅ 正确 | +|---|---|---| +| 查某天资金日报 | `GET /daily/2026-09-05` | `GET /daily?startDate=2026-09-05&endDate=2026-09-05` | +| 看某天流水明细 | (没有 `/daily/{date}` 这个接口) | `GET /admin/finance/fund-flows/page?flowAtStart=2026-09-05&flowAtEnd=2026-09-05&pageNo=1&pageSize=20` | + +**后端没有 `/daily/{date}` 这种路径**,日期拼进去会因匹配不到路由返回 404「接口不存在」。 + +--- + +## 一、背景(实测现象) + +资金统计查询页,点击某个日期后报错: + +``` +接口不存在 GET /admin/finance/fund-stats/daily/2026-09-05 +``` + +根因:前端把日期 `2026-09-05` 拼到了 `/daily/` 后面当**路径段**,但后端 `FundStatsController` 只暴露了 `GET /admin/finance/fund-stats/daily`(日期走 query),**没有 `/daily/{date}` 路由**,网关/后端找不到 → 404。 + +## 二、两个正确接口(按"点日期"的真实意图二选一) + +### 2.1 若意图 = 重新查某天(或含某天区间)的资金日报 + +**GET** `/admin/finance/fund-stats/daily` + +| Query 参数 | 必填 | 说明 | +|---|---|---| +| `accountId` | 否 | 账户 ID;空 = 全部账户汇总 | +| `startDate` | ✅ | 起始日 yyyy-MM-dd(含当日) | +| `endDate` | ✅ | 截止日 yyyy-MM-dd(含当日) | + +点单日:`startDate` 与 `endDate` 都传该日。 + +### 2.2 若意图 = 点日期**下钻看当天的资金流水明细**("资金明细") + +后端**已有现成接口**,无需新开发。**GET** `/admin/finance/fund-flows/page`(账户流水明细分页,逐笔含结存快照,flowAt 倒序): + +| Query 参数 | 必填 | 说明 | +|---|---|---| +| `fundAccountId` | 否 | 账户 ID;空 = 全部账户 | +| `accountType` | 否 | 账户类型:BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL | +| `direction` | 否 | 方向:OUT 出账 / IN 入账 | +| `bizType` | 否 | 业务类型:PAYMENT / PREPAY / EXPENSE / REIMBURSE / RECEIPT / STAFF_LOAN / COMPANY_LOAN / NONBIZ / ADVANCE / TRANSFER / ORDER_PAY / INVENTORY / OPENING | +| `flowNo` | 否 | 流水号模糊 | +| `flowAtStart` | 否 | 收付日期起 yyyy-MM-dd(**点哪天就传哪天**) | +| `flowAtEnd` | 否 | 收付日期止 yyyy-MM-dd(同上,单日查询=start=end) | +| `pageNo` / `pageSize` | 是 | 分页(PageParam) | + +> ⚠️ 注意:流水明细的日期参数是 **`flowAtStart`/`flowAtEnd`**,账户字段是 **`fundAccountId`**——与 `/daily` 的 `startDate`/`endDate`/`accountId` **命名不同**,别混用。 + +另有单笔流水回单:`GET /admin/finance/fund-flows/{id}`(含互转对侧流水 pairedFlowId)。 + +## 三、示例 + +### 3.1 反例:日期拼路径 → 404 + +```http +GET /admin/finance/fund-stats/daily/2026-09-05 +→ 接口不存在(404) +``` + +### 3.2 正例 A:查某天日报(日期走 query) + +```http +GET /admin/finance/fund-stats/daily?startDate=2026-09-05&endDate=2026-09-05 +``` + +### 3.3 正例 B:点日期下钻看当天流水明细 + +```http +GET /admin/finance/fund-flows/page?flowAtStart=2026-09-05&flowAtEnd=2026-09-05&pageNo=1&pageSize=20 +``` + +(单账户下钻再加 `&fundAccountId=<账户ID>`) + +## 四、前端对接建议 + +- 「点日期」先明确意图:刷新日报 → 调 `/daily`(query 传 `startDate=endDate=该日`);看明细 → 调 `/fund-flows/page`(query 传 `flowAtStart=flowAtEnd=该日`)。**两者日期都在 query,都不拼路径。** +- 明细列表建议带分页 + `flowAt` 倒序展示;点单笔可跳 `/fund-flows/{id}` 回单。 +- 404 / 400 都要有兜底提示(参考上一份纠错:参数名/路径错会 400/404,别静默留白让人误以为"没数据")。 + +## 五、影响评估 / 回滚 + +- **后端零变更**,本次仅为对接说明,无需发版、无需回滚。 +- 前端改对调用方式(日期走 query / 明细走 fund-flows)即可正常,无需等待后端任何动作。 + +## 六、关联 / 联系人 + +- 关联 changelog:[09_7003_资金日报-新增接口](09_7003_资金日报-新增接口-管理后台.md)、[15_fund-stats_参数名纠错](15_fund-stats_资金统计日报查询参数是startDate-endDate不是dateFrom-dateTo-修改接口-管理后台.md) +- 负责人: 腰苏图(yst) +- 反馈入口: 财务域后端对接群 / 直接 @yst