wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md
wx 3fe95b157f
所有检测均成功
changelog-filename-gate / validate (push) Successful in 1s
详情
docs: 明确矩阵车辆行司机汇总 (#5299) (#59)
2026-07-28 11:35:04 +08:00

13 KiB
原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer change_type backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 5299 车务矩阵车辆司机预选与常驻标记 admin 修改接口 deployed verified claimed hl-admin mmg/hl-ui@86a272bb1e 2026-07-28 新增车辆行司机汇总口径：现有实现只显示常驻司机或无常驻司机，未汇总当前矩阵订单实际司机，故回退 claimed 等待前端补齐并完成页面复验 2026-07-28 dev-v3

Fleet：矩阵车辆司机预选与常驻标记

服务：hl-fleet-service Issue：#5299 影响页面：管理后台车务管理 → 矩阵派单 兼容性：仅新增响应字段，旧客户端可继续忽略

问题与目标

当前矩阵车辆行虽然已有常驻司机姓名，但缺少常驻司机稳定 ID；订单甘特条也没有直接返回该派车组的实际车辆、司机及常驻关系。页面因此无法稳定完成以下行为：

  • 从具体车辆上下文发起派单时自动带出车辆和可派常驻司机；
  • 行头展示车辆常驻司机；
  • 已排订单条块展示实际执行司机，并区分常驻/临时司机。

本次后端补齐稳定读契约。前端不得按姓名判断常驻关系，也不得复制相邻订单的临时司机作为新派单默认值。

2026-07-28 前端运行态阻断：FleetAssignModal 递归更新

现场结论

前端实现提交 bfcfafc69335f289071fe3e6dce74bacb636c55d 已进入 v2.1，但当前测试页面打开逐日派车弹窗并加载车辆、司机候选后稳定出现：

Maximum recursive updates exceeded in component <FleetAssignModal>

浏览器 Console 同时记录多次 unhandledrejection；Network 中多条 POST /admin/fleet/assignments/candidates 均返回 HTTP 200，但车辆、司机区域持续停留在 loading，无法进入下一步。因此本次不是候选接口、日期冲突或后端状态机错误，而是前端实现后的响应式自反馈回归。frontend_status: "implemented" 仅表示代码已存在，不代表已发布或页面闭环。

高可信自反馈链

当前 AssignModal.vue 的深度 watcher 同时观察 candidateEvidence、candidateSelectionReady、autoSelectedResidentDriverSource 等候选派生状态，并在回调 syncActiveSlotSelection() 中无条件重建 dailyPlan、回写当前槽位。dailyPlan 又参与计算其他槽位排除 ID、候选可选态和新的 candidateEvidence；即使业务值没有变化，新数组/对象身份仍会再次触发同一 watcher，形成“观察候选派生值 → 回写逐日方案 → 候选派生值重新计算 → 再次回写”的闭环。

前端修复必须同时满足：

  1. syncActiveSlotSelection() 先比较当前日格与待写 payload；语义完全相同时直接返回，不创建新 dailyPlan/槽位对象。
  2. watcher 使用稳定原始值或稳定 fingerprint，不深度监听会被自身回写间接失效的派生对象；候选响应、用户选择和槽位同步应有单向边界。
  3. updateDailyVehiclePlanCell() 或等价更新器在无真实字段变化时返回原引用，禁止仅因对象重建触发后续 effect。
  4. 保留 #5283 的稳定 initializationIdentity 与 requestSeq 旧响应隔离；不得退回监听 props.order 对象身份或通过删除并发保护掩盖循环。
  5. 正常打开弹窗只允许一次初始候选请求；需要自动常驻司机二次校验时最多再请求一次。状态稳定后不得继续请求，loading 必须收敛。

前端回归验收

  • 打开订单逐日派车弹窗并取得候选成功响应后，Console 不再出现 Maximum recursive updates 或相关 unhandledrejection。
  • 候选请求数量有明确上界；自动常驻司机场景最多“初始查询 + 携两侧 ID 二次校验”，不存在持续请求。
  • 车辆、司机列表结束 loading，接口返回的分页总数与页面一致，可正常进入下一步。
  • 已选车辆、司机、逐日费用和跨常驻确认写回一次后保持稳定，多轮 nextTick 不再重建相同 dailyPlan。
  • 相同业务身份的 SSE/列表对象替换仍保留候选与草稿；真实订单、需求、槽位或模式变化时才重新初始化。
  • 新增真实挂载 FleetAssignModal 的回归测试，模拟候选成功和自动常驻二次校验，断言无未处理 Promise、请求次数有界且草稿稳定；仅做静态源码断言不足以验收。

变更接口

GET /admin/fleet/matrix/grid

data.vehicles[] 新增：

字段 类型 空值规则 说明
primaryDriverId String(Long) 无常驻司机为 null 车辆主档的权威常驻司机 ID

既有 primaryDriverName、primaryDriverPhone 继续返回；手机号保持脱敏。三个字段共同用于行头展示，常驻判断以 ID 为准。

data.vehicles[].assignments[] 新增：

字段 类型 空值规则 说明
vehicleId String(Long) 未派为空 该甘特条对应派车组的实际车辆 ID
vehiclePlate String 未派为空 实际车牌
driverId String(Long) 未派为空 该派车组实际司机 ID
driverName String 未派为空 该派车组实际司机姓名
residentMatch Boolean 无实际司机为 null true=实际司机是该车常驻司机；false=实际司机存在但不是该车常驻司机或车辆无常驻

矩阵继续排除取消切片；同一派车组存在取消日缺口时按有效连续服务段拆成多个甘特条，不得把外包络日期当作司机持续占用。

前端必须调整

1. 从矩阵车辆上下文发起派单

  1. 将所在行 vehicles[].id 直接作为当前选择车辆，并在候选请求中传 selectedVehicleId。
  2. 候选接口 POST /admin/fleet/assignments/candidates 会返回既有字段 selectedVehicleResidentDriver。
  3. 仅当该快照存在且 available=true 时，才把其司机 ID 作为默认司机。
  4. 无常驻司机、常驻司机冲突或不可派时，车辆仍保持预选，司机保持“待选择”，并展示候选返回的不可用原因。
  5. 不得取前后相邻订单的实际司机作为新订单默认司机。

2. 矩阵司机展示

2.1 车辆行司机汇总数据源

后端契约已经足够，前端不得新增接口或按车牌反查司机：

  • 常驻司机取当前车辆行 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 页面改造

用户截图仍出现“收取车费日期”，说明当前测试页面仍在使用旧构建或旧逻辑。新页面必须继续执行 #5292：

  • 删除“收取车费日期”及旧免费日期提交逻辑；
  • 使用 dailyVehiclePlan 渲染“服务日期 × 稳定车辆槽位”；
  • 保存时只提交 dailyPlan，不得同时提交旧 items、chargeableServiceDates、vehicleFeeWaiverReason 或 confirmAllServiceDatesFree。

响应示例

{
  "id": "9007199254740993",
  "plate": "蒙A-88888",
  "primaryDriverId": "9007199254740994",
  "primaryDriverName": "王师傅",
  "primaryDriverPhone": "138****1234",
  "assignments": [
    {
      "id": "9007199254740995",
      "assignmentGroupId": "9007199254740996",
      "vehicleId": "9007199254740993",
      "vehiclePlate": "蒙A-88888",
      "driverId": "9007199254740994",
      "driverName": "王师傅",
      "residentMatch": true
    }
  ]
}

所有 Long ID 仍按 JSON 字符串处理，禁止转为 JS Number。

不影响范围

  • 不修改派单状态机、车辆/司机占用、保险、对账或常驻关系写入。
  • 不自动选择不可派司机，不绕过候选接口与最终派单锁内校验。
  • 不修改 hl-ui 仓库；前端消费状态独立流转。

验证证据

  • 后端 PR wx/HL#5300 已 squash 合并至 dev-v3，合并提交 fca8cedc6。
  • hl-fleet-service 已滚动部署测试环境，8087/8187 双实例健康。
  • 定向矩阵测试：43 tests，0 failures，0 errors，0 skipped。
  • Fleet reactor verify：2456 tests，0 failures，0 errors，1 skipped；模块 Spotless、Jar、JaCoCo 成功。
  • 真实测试网关 GET /admin/fleet/matrix/grid?year=2026&month=8&season=active：HTTP/code 200；返回 19 辆车、38 个派车段，新增车辆/司机字段完整，Long ID 均为字符串，residentMatch 三态合法，常驻司机手机号全部脱敏，无业务写入。
  • 网关证据：D:/work2/HL-v3/.tmp/5299-gateway.json，SHA-256 d94ee78fbe52cc193a28e5bf182e1353d2eca9d87824b1c2eb526c62a4fe645d。
  • OpenAPI/oasdiff：项目尚未配置可复现 Swagger2→OAS3 与 oasdiff，状态为 not_configured；使用源码字段对比、Controller 序列化测试及真实网关响应作为人工回退证据，未冒充工具通过。

当前状态：后端已部署、网关已验证；前端代码状态为 implemented，但运行态复验失败，修复并通过上述页面验收前不得流转为 released 或 verified。

关联：#5299、#5292、#5283。