hl-api-changelog/changelogs-v2/2026-07/63_5062_订单工作台统计口径与金额字符串-修改接口-管理后台.md

【修改接口·管理后台】订单工作台统计口径与金额字符串收口（#5062）

Issue: wx/HL#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	当日成功退款

三、响应片段

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