# 【修改接口·管理后台】订单工作台统计口径与金额字符串收口（#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 跳过。
