diff --git a/changelogs-v2/2026-07/24_5205_车务首页汇总与看板人员类型展示-修改接口-管理后台.md b/changelogs-v2/2026-07/24_5205_车务首页汇总与看板人员类型展示-修改接口-管理后台.md new file mode 100644 index 0000000..e8d82c3 --- /dev/null +++ b/changelogs-v2/2026-07/24_5205_车务首页汇总与看板人员类型展示-修改接口-管理后台.md @@ -0,0 +1,105 @@ +--- +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` +- 联调/验收环境: +- 小程序:无需处理 + +> **服务**: 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`。