8493c75ab4
修改原因：hl-ui changelog loop 需要把前端消费进度回写到契约源，避免领取、实现状态与实际交付脱节。 修改内容：将 frontend_status 与已有 legacy frontend 同步为 implemented，记录负责人 hl-ui-codex，并关联 mmg/hl-ui@a48846a3e35c06df3aef422e538d5cd198002c2c；发布和验收字段保持不变。 实际验证：回写器已校验目标文件、状态单调性、提交范围和 Front Matter 内容，提交只包含当前 changelog。 Frontend-Status: tools/mcp-api-sync/.changelog-repo/changelogs-v2/2026-07/24_5215_车务首页未完成状态独立汇总-修改接口-管理后台.md
122 行
4.1 KiB
Markdown
122 行
4.1 KiB
Markdown
---
|
||
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`。
|