docs(dashboard): 补充统计口径与金额字符串契约 (#5062)

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 跳过。