diff --git a/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md b/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md index d44ce7c..5a1a16d 100644 --- a/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md +++ b/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md @@ -6,12 +6,12 @@ consumer: "admin" change_type: "修改接口" backend_status: "deployed" gateway_status: "verified" -frontend_status: "implemented" +frontend_status: "claimed" frontend_owner: "hl-admin" frontend_ref: "mmg/hl-ui@86a272bb1e170c9d3cf9f2b3fa60174a8c8904cd" target_release: "" -verified_at: "2026-07-28T10:58:40+08:00" -status_note: "前端实现 bfcfafc6 已回写,但测试页面 FleetAssignModal 出现响应式递归更新并阻断候选加载;修复并完成页面复验前不得流转为 released/verified" +verified_at: "" +status_note: "2026-07-28 新增车辆行司机汇总口径:现有实现只显示常驻司机或无常驻司机,未汇总当前矩阵订单实际司机,故回退 claimed 等待前端补齐并完成页面复验" updated_at: "2026-07-28" base: "dev-v3" --- @@ -102,15 +102,54 @@ Maximum recursive updates exceeded in component ### 2. 矩阵司机展示 -- 车辆行头: - - `primaryDriverId != null`:展示 `primaryDriverName(常驻)`;可按需展示脱敏手机号。 - - `primaryDriverId == null`:展示“无常驻司机”,不要继续统一显示“待派司机”。 -- 已排订单条块:展示本条 `driverName`。 - - `residentMatch=true`:标记“常驻”。 - - `residentMatch=false`:标记“临时”。 - - `residentMatch=null`:显示“待派司机”。 +#### 2.1 车辆行司机汇总数据源 -不要从 `drivers` 页面列表或姓名/车牌文本反推常驻关系;使用本接口稳定 ID 与 `residentMatch`。 +后端契约已经足够,前端不得新增接口或按车牌反查司机: + +- 常驻司机取当前车辆行 `vehicles[].primaryDriverId`、`primaryDriverName`;常驻关系以 ID 为准。 +- 订单实际司机只取同一车辆行当前响应中的 `vehicles[].assignments[].driverId`、`driverName`;这些是当前矩阵月份和筛选条件已加载的真实派车段。 +- `assignments[]` 后端已按月内 `startDay` 升序返回。前端按响应数组顺序扫描,以司机首次出现的位置作为其他司机的稳定展示顺序,不按姓名另行排序,也不混入上一月份、上一筛选条件、未派窗口、候选列表或 `drivers` 页面数据。 +- `residentMatch` 继续用于订单条块的常驻/临时三态标记;车辆行汇总去重使用稳定 `driverId`,不得只按姓名猜测同一人。 + +#### 2.2 汇总与展示规则 + +1. 若 `primaryDriverId` 非空,先把常驻司机放在结果第一项,显示 `primaryDriverName(常驻)`。ID 存在但姓名异常为空时使用 `姓名未标注(常驻)`,不得输出空白项。 +2. 随后按 `assignments[]` 当前顺序遍历实际司机:`driverId` 或去空后的 `driverName` 为空则跳过;相同 `driverId` 只保留第一次出现。 +3. 订单实际司机与 `primaryDriverId` 相同时,不再追加普通姓名,只保留第一项带“(常驻)”标记的展示。 +4. 其他实际司机按首次出现顺序追加,使用中文逗号 `,` 连接。不得把同一司机跨多个订单或拆分派车段重复展示。 +5. 无常驻司机但存在订单实际司机时,直接展示实际司机汇总,**不得只显示“无常驻司机”**。 +6. 只有常驻司机和订单实际司机都不存在时,才显示“无常驻司机”。若行宽不足允许视觉省略,但必须通过 `title`、tooltip 或等价交互查看完整汇总,不得静默丢失司机。 + +展示样例: + +| 常驻司机 | 当前行订单司机(按首次出现顺序) | 车辆行展示 | +|---|---|---| +| 张三 | 张三、李四、王五、李四、赵六 | `张三(常驻),李四,王五,赵六` | +| 无 | 李四、王五、李四 | `李四,王五` | +| 张三 | 张三、张三 | `张三(常驻)` | +| 无 | 空 | `无常驻司机` | + +#### 2.3 订单条块保持既有语义 + +已排订单条块继续展示本条 `driverName`: + +- `residentMatch=true`:标记“常驻”。 +- `residentMatch=false`:标记“临时”。 +- `residentMatch=null`:显示“待派司机”。 + +不要从 `drivers` 页面列表或姓名/车牌文本反推常驻关系;所有 Long ID 继续按字符串比较,禁止转为 JS `Number`。 + +#### 2.4 前端验收清单 + +- [ ] 截图中车辆无常驻司机但订单已有实际司机时,车辆行显示订单实际司机姓名,不再只显示“无常驻司机”。 +- [ ] 常驻司机与多名订单司机并存时,展示严格为 `张三(常驻),李四,王五,赵六`,常驻第一且只出现一次。 +- [ ] 同一实际司机出现在多个订单或多个有效派车段时只展示一次;空 ID、空姓名和未派条块不产生空白分隔项。 +- [ ] 其他司机顺序跟随当前 `assignments[]` 首次出现顺序;切换月份、车队、车型或状态筛选后按新响应重新计算,不残留旧司机。 +- [ ] 订单条块的 `driverName/residentMatch` 常驻、临时、待派展示不回归。 +- [ ] 补充纯汇总函数或 `VehicleGantt` 组件测试,至少覆盖上表四组样例、Long ID 字符串去重和筛选响应替换。 +- [ ] 真实页面复验行宽溢出场景可查看完整司机列表,Console 无异常,且不增加司机列表或候选接口请求。 + +在本节完成并通过真实矩阵页面复验前,`frontend_status` 保持 `claimed`,不得流转为 `implemented/released/verified`。 ### 3. 同步完成 #5292 页面改造