---
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`。