diff --git a/changelogs-v2/2026-07/24_5215_车务首页未完成状态独立汇总-修改接口-管理后台.md b/changelogs-v2/2026-07/24_5215_车务首页未完成状态独立汇总-修改接口-管理后台.md new file mode 100644 index 0000000..5a3241f --- /dev/null +++ b/changelogs-v2/2026-07/24_5215_车务首页未完成状态独立汇总-修改接口-管理后台.md @@ -0,0 +1,117 @@ +--- +schema: "hl-changelog/v1" +ticket: "5215" +title: "车务首页未完成状态独立汇总" +consumer: "admin" +backend: "verified" +gateway: "verified" +frontend: "pending" +base: "dev-v3" +generated: "2026-07-24T14:25:00+08:00" +--- + +# 【修改接口·前端待处理·管理后台】车务首页未完成状态独立汇总 + +## 目标前端 + +- 端类型:管理后台(Web) +- 目标仓库:`mmg/hl-ui` +- 目标分支:`v2.1` +- 联调/验收环境: +- 小程序:无需处理 + +> **服务**: 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`。