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

schema, ticket, title, consumer, backend, gateway, frontend, base, generated

schema	ticket	title	consumer	backend	gateway	frontend	base	generated
hl-changelog/v1	5205	车务首页汇总与看板人员类型展示	admin	verified	verified	pending	dev-v3	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

影响范围: 车务首页待安排车辆卡片、即将用车订单状态标签、派单看板人数摘要

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[] 已返回真实订单人数构成：

{
  "headcount": 5,
  "adultCount": 2,
  "childCount": 1,
  "youngChildCount": 1,
  "babyCount": 1
}

看板卡片不要只展示 5人，应展示人员类型构成，例如：

成人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。