---
schema: "hl-changelog/v1"
ticket: "5215"
title: "车务首页未完成状态独立汇总"
consumer: "admin"
backend: "verified"
gateway: "verified"
frontend: "implemented"
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@a48846a3e35c06df3aef422e538d5cd198002c2c"
updated_at: "2026-07-24T07:15:17.828Z"
base: "dev-v3"
generated: "2026-07-24T14:25:00+08:00"
---

# 【修改接口·前端待处理·管理后台】车务首页未完成状态独立汇总

## 目标前端

- 端类型：管理后台（Web）
- 目标仓库：`mmg/hl-ui`
- 目标分支：`v2.1`
- 联调/验收环境：<http://192.168.100.160:9527>
- 小程序：无需处理

> **服务**: hl-fleet-service、hl-user-service
>
> **工单**: [wx/HL#5215](https://git.1814.love:8443/wx/HL/issues/5215)
>
> **影响范围**: 车务首页待处理汇总卡片

## 接口变更

`GET /admin/profile/dashboard?period=today` 在保留 `data.pendingArrangeVehicle`
总数的基础上，新增固定顺序的 `data.pendingStatusCards`：

```json
{
  "code": 200,
  "data": {
    "pendingArrangeVehicle": 5,
    "pendingStatusCards": [
      {
        "status": "unassigned",
        "statusLabel": "待派车",
        "count": 4
      },
      {
        "status": "holding",
        "statusLabel": "待确认",
        "count": 1
      }
    ]
  }
}
```

字段口径：

| 字段 | 含义 |
| --- | --- |
| `pendingArrangeVehicle` | 近 7 天订单级唯一的全部未完成配车订单数 |
| `pendingStatusCards[].status` | 稳定状态键，固定为 `unassigned`、`holding` |
| `pendingStatusCards[].statusLabel` | 后端中文标签，分别为“待派车”“待确认” |
| `pendingStatusCards[].count` | 对应基础状态的订单级唯一数量 |

`unassigned_urgent` 归入 `unassigned`，`holding_urgent` 归入 `holding`。
`assigned`（配置完成）、`canceled`、`completed` 不进入状态卡。接口始终按
`unassigned`、`holding` 顺序返回两项；即使数量为 0 也不省略。

守恒关系：

```text
sum(pendingStatusCards[].count)
  == pendingArrangeVehicle
  == upcomingTrips.length
```

## 前端展示

首页汇总区应展示三张独立卡片：

| 卡片 | 数据源 | 建议语义色 |
| --- | --- | --- |
| 待安排车辆 | `pendingArrangeVehicle` | danger / 红色 |
| 待派车 | `pendingStatusCards[status=unassigned].count` | warning / 橙色 |
| 待确认 | `pendingStatusCards[status=holding].count` | processing / 蓝色 |

实现要求：

- 使用 `pendingStatusCards` 循环渲染状态卡，并以 `status` 作为稳定 key 和颜色映射依据；
- 保留现有“待安排车辆”总卡，不要用状态卡替换总数；
- 不要从 `upcomingTrips` 或派车槽位在前端重新汇总；
- 数量为 0 时仍展示对应状态卡，避免布局和状态口径随数据变化；
- 标签优先展示后端 `statusLabel`，颜色不得按中文文案判断。

## 前端处理清单

- [ ] 首页汇总区展示“待安排车辆、待派车、待确认”三张卡片。
- [ ] 待安排车辆使用红色、待派车使用橙色、待确认使用蓝色。
- [ ] 状态卡以 `status` 为 key，直接使用后端 `count`，不在前端重新统计。
- [ ] 覆盖 `5/4/1`、两个状态均为 0、单个状态为 0 的展示场景。
- [ ] 保持现有即将用车订单表格与操作逻辑不变。

## 后端验证

- `FleetDashboardSummaryServiceTest` 覆盖 `unassigned=4`、`holding=1`、
  紧急派生态归并、订单去重、配置完成排除及零值场景。
- `LogisticsDashboardServiceTest` 与 Feign fallback 测试覆盖完整透传、
  滚动部署兼容和固定两项零值降级。
- `mvn -pl hl-user-service,hl-fleet-service -am verify` 已通过。
- 分支 `fix/5215-fleet-dashboard-status-cards` 已按 fleet、user 顺序部署，
  四个服务实例均健康。
- 2026-07-24 经测试网关验证：
  `pendingArrangeVehicle=5`、`unassigned=4`、`holding=1`、
  `upcomingTrips.length=5`。
- fleet、user 与 gateway 部署完成窗口内 ERROR 级别日志均为 0，
  未发现 dashboard 目标异常。

> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。