diff --git a/changelogs-v2/2026-07/63_5062_订单工作台统计口径与金额字符串-修改接口-管理后台.md b/changelogs-v2/2026-07/63_5062_订单工作台统计口径与金额字符串-修改接口-管理后台.md new file mode 100644 index 0000000..4307577 --- /dev/null +++ b/changelogs-v2/2026-07/63_5062_订单工作台统计口径与金额字符串-修改接口-管理后台.md @@ -0,0 +1,83 @@ +# 【修改接口·管理后台】订单工作台统计口径与金额字符串收口(#5062) + +> Issue: [wx/HL#5062](https://git.1814.love:8443/wx/HL/issues/5062) +> +> 服务: `hl-user-service`、`hl-order-service-v3` +> +> 日期: 2026-07-18 +> +> 影响入口: `GET /admin/profile/dashboard?period={today|week|month}` + +## 一、前端结论 + +1. 路径、请求参数和角色分流不变,不需要新增接口调用。 +2. GMV/收入改按真实收款时间归属:线上只统计成功支付,线下只统计未撤销收款;不再按订单创建时间归属订单累计实付。 +3. 退款改按真实成功退款时间归属;财务近 30 天趋势返回真实每日收入和退款。 +4. 所有金额字段固定按 JSON String 处理;比例 `gmvDiffRate` 仍为 JSON Number。 +5. 雪花 ID(例如排行 `adminId`、即将出行 `orderId`)固定按 JSON String 处理,禁止转换为 JavaScript `Number`。 +6. 排行订单数为期间发生有效收款的订单去重数,同一订单多笔收款只计一单、金额全部累加。 +7. 权威统计源不可用时接口失败关闭,不会用部分成功数据或全零数据伪装成功。 + +## 二、受影响字段 + +### 2.1 ADMIN / CUSTOMIZER 工作台 + +| 字段 | JSON 类型 | 说明 | +|---|---|---| +| `overview.gmv` | String | 当前 period 内真实收款金额 | +| `overview.gmvDiffRate` | Number | 与上一等长期间相比的变化比例 | +| `trend[].gmv` | String | 对应日期的真实收款金额 | +| `ranking[].adminId` | String | 定制师雪花 ID | +| `ranking[].gmv` | String | 对应定制师期间真实收款金额 | +| `ranking[].orderCount` | Number | 发生有效收款的去重订单数 | +| `ranking[].avatar` | String/null | 定制师头像;用户信息降级时允许为空 | +| `upcomingTrips[].orderId` | String | 订单雪花 ID | + +### 2.2 FINANCE 工作台 + +| 字段 | JSON 类型 | 说明 | +|---|---|---| +| `periodIncome` | String | 当前 period 内真实收入 | +| `periodRefund` | String | 当前 period 内成功退款 | +| `monthIncome` | String | 自然月真实收入 | +| `monthRefund` | String | 自然月成功退款 | +| `financeTrend[].date` | String | 日期,`yyyy-MM-dd` | +| `financeTrend[].income` | String | 当日真实收入 | +| `financeTrend[].refund` | String | 当日成功退款 | + +## 三、响应片段 + +```json +{ + "code": 200, + "success": true, + "data": { + "role": "FINANCE", + "periodIncome": "128000.00", + "periodRefund": "5600.00", + "monthIncome": "328000.00", + "monthRefund": "8600.00", + "financeTrend": [ + { + "date": "2026-07-18", + "income": "12000.00", + "refund": "600.00" + } + ] + } +} +``` + +## 四、前端检查清单 + +- [ ] 金额展示使用字符串格式化,不执行 `Number(amount)`。 +- [ ] `gmvDiffRate` 继续按 Number 计算百分比。 +- [ ] 所有 Long ID 保持字符串透传到路由和请求参数。 +- [ ] 不再用订单创建日解释趋势 GMV;趋势日期是支付/收款发生日。 +- [ ] 财务趋势同时渲染 `income` 与 `refund`,空日后端返回 `"0.00"`。 +- [ ] 接口业务失败时展示重试,不把缺失统计源当作全零成功。 + +## 五、后端验证 + +- Dashboard、User 聚合、支付/退款 Feign、序列化与失败关闭相关测试已通过。 +- Issue #5062 最终五模块全量测试:14,518 个测试,0 失败、0 错误;Fleet Reactor verify:1,824 个测试,0 失败、0 错误、0 跳过。