docs: hand off fleet dashboard display contract (#5205)

changelogs-v2/2026-07/24_5205_车务首页汇总与看板人员类型展示-修改接口-管理后台.md

@@ -0,0 +1,105 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5205"
+title: "车务首页汇总与看板人员类型展示"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+base: "dev-v3"
+generated: "2026-07-24T10:45:00+08:00"
+---
+
+# 【修改接口·前端待处理·管理后台】车务首页汇总与看板人员类型展示
+
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 目标分支：`v2.1`
+- 联调/验收环境：<http://192.168.100.160:9527>
+- 小程序：无需处理
+
+> **服务**: hl-fleet-service、hl-user-service
+>
+> **工单**: [wx/HL#5205](https://git.1814.love:8443/wx/HL/issues/5205)
+>
+> **影响范围**: 车务首页待安排车辆卡片、即将用车订单状态标签、派单看板人数摘要
+
+## 1. 首页待安排车辆汇总
+
+`GET /admin/profile/dashboard?period=today` 的响应结构不变，`data.pendingArrangeVehicle`
+调整为 `data.upcomingTrips` 中订单级唯一的有效未完成配车订单总数。
+
+计入口径：
+
+- `unassigned`、`unassigned_urgent`：待派车；
+- `holding`、`holding_urgent`：待确认。
+
+不计入口径：
+
+- `assigned`：已完成车辆配置；
+- `canceled`、`completed`：已取消或已完结，不属于有效待处理订单。
+
+页面不得只统计 `unassigned`，也不得自行按派车槽位累加。当前测试环境验收样例为
+3 个待派车加 1 个待确认，`pendingArrangeVehicle` 与列表徽标都应显示 4。
+
+## 2. 首页状态标签颜色
+
+颜色按稳定状态码映射，不按中文 `statusLabel` 判断：
+
+| `upcomingTrips[].status` | 标签 | 建议语义色 |
+| --- | --- | --- |
+| `unassigned` / `unassigned_urgent` | 待派车 | warning / 橙色 |
+| `holding` / `holding_urgent` | 待确认 | processing / 蓝色 |
+
+紧急程度继续使用 `urgentBadge` 单独表达，不要通过把全部状态渲染成橙色来表示紧急。
+
+## 3. 派单看板人员类型
+
+`GET /admin/fleet/board/orders` 的 `data.records[]` 已返回真实订单人数构成：
+
+```json
+{
+  "headcount": 5,
+  "adultCount": 2,
+  "childCount": 1,
+  "youngChildCount": 1,
+  "babyCount": 1
+}
+```
+
+看板卡片不要只展示 `5人`，应展示人员类型构成，例如：
+
+```text
+成人2 · 儿童1 · 幼童1 · 婴儿1
+```
+
+展示规则：
+
+- 四类字段均为订单真实数据，不得按客户名、标签、总人数或订单 ID 推测；
+- 数值为 0 的类型可省略；
+- 四类字段全部为 `null` 时才兼容回退 `headcount + "人"`；
+- 四类人数合计与 `headcount` 不一致时保留后端原值，并上报数据异常，不在前端静默改数。
+
+## 前端处理清单
+
+- [ ] 首页待安排车辆卡片直接展示后端 `pendingArrangeVehicle`，不再自行只统计待派车状态。
+- [ ] 首页列表徽标与 `upcomingTrips.length` 保持一致。
+- [ ] 待派车使用橙色，待确认使用蓝色；颜色映射使用状态码。
+- [ ] 派单看板用四类人数构成替换单一总人数文案，零值类型省略。
+- [ ] 覆盖 3 个待派车 + 1 个待确认、紧急派生态、四类人数混合和全零/空值兼容场景。
+
+## 后端验证
+
+- `FleetDashboardSummaryServiceTest` 覆盖待派车与待确认共同汇总、订单级去重及完成态排除。
+- 分支 `fix/5205-fleet-dashboard-summary` 已通过测试环境滚动部署任务 `f64ec5ef`，
+  `hl-fleet-service` 的 8087/8187 双实例健康。
+- 2026-07-24 经测试网关验证：
+  `pendingArrangeVehicle=4`、`upcomingTrips.length=4`、唯一订单数为 4、重复数为 0，
+  状态分布为 `unassigned:3`、`holding:1`。
+- `GET /admin/fleet/board/orders` 返回 9 条记录，9 条均具有非空的
+  `adultCount/childCount/youngChildCount/babyCount`。
+- fleet、user 与 gateway 日志未发现本次 dashboard 请求相关异常。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。