124 行
6.2 KiB
Markdown
124 行
6.2 KiB
Markdown
---
|
||
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: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "5c4852d190362a6eafd58ae2899072b5d35e39aa"
|
||
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 可空=全部）。 前端已闭环(5c4852d1):DayDetailDrawer 弃用拼路径的 getFundStatDayDetail(fund-stat.js 同步删除该函数),改 getFundFlowPage({flowAtStart=flowAtEnd=该日,pageNo,pageSize}) 服务端分页,列按真实出参 flowAt/flowNo/balanceAfter/accountName/counterparty 重键并删 voucherNo 穿透列;顺带修正账户流水页 flow/index.vue 误传键 accountId/dateFrom/dateTo/page→fundAccountId/flowAtStart/flowAtEnd/pageNo(beforeFetch 换名),404/400 均有兜底提示;新增 spec 8 例,checkpoint 13 项全绿。"
|
||
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
|