docs: 明确矩阵车辆行司机汇总 (#5299) (#59)

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"
+verified_at: ""
-status_note: "前端实现 bfcfafc6 已回写，但测试页面 FleetAssignModal 出现响应式递归更新并阻断候选加载；修复并完成页面复验前不得流转为 released/verified"
+status_note: "2026-07-28 新增车辆行司机汇总口径：现有实现只显示常驻司机或无常驻司机，未汇总当前矩阵订单实际司机，故回退 claimed 等待前端补齐并完成页面复验"
 updated_at: "2026-07-28"
 base: "dev-v3"
 ---
@@ -102,15 +102,54 @@ Maximum recursive updates exceeded in component <FleetAssignModal>
 
 ### 2. 矩阵司机展示
 
-- 车辆行头：
+#### 2.1 车辆行司机汇总数据源
-  - `primaryDriverId != null`：展示 `primaryDriverName（常驻）`；可按需展示脱敏手机号。
-  - `primaryDriverId == null`：展示“无常驻司机”，不要继续统一显示“待派司机”。
-- 已排订单条块：展示本条 `driverName`。
-  - `residentMatch=true`：标记“常驻”。
-  - `residentMatch=false`：标记“临时”。
-  - `residentMatch=null`：显示“待派司机”。
 
-不要从 `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 页面改造