docs: 交接派车候选刷新清空问题 (#5283) (#47)

changelogs-v2/2026-07/27_5283_派车候选响应被订单刷新清空-修改接口-管理后台.md

@@ -0,0 +1,106 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5283"
+title: "车务派车候选响应被订单刷新清空"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端候选接口契约与日期冲突口径正常；前端 AssignModal 因同订单对象刷新而重复初始化，清空已成功返回的候选。"
+updated_at: "2026-07-27"
+base: "dev-v3"
+---
+
+# 车务派车候选响应被订单刷新清空
+
+> **服务**: `hl-fleet-service`
+>
+> **后端工单**: [wx/HL#5283](https://git.1814.love:8443/wx/HL/issues/5283)
+>
+> **前端消费端**: `mmg/hl-ui v2.1`
+>
+> **影响页面**: 车务管理 → 派车看板/矩阵 → 派车弹窗 `AssignModal`
+
+## 结论
+
+本次不是后端候选过滤或 API 契约缺陷，不新增或修改接口、字段、类型、必填性、错误码及派单状态机：
+
+- 同一真实请求经测试网关返回 `vehicleTotal=19`，其中 11 辆 `AVAILABLE`，其余车辆因真实日期冲突不可用；
+- 专用测试车辆在目标日期区间均返回 `AVAILABLE`，车辆、车型、车队和维保状态未造成错误排除；
+- 页面显示“共 0 辆”发生在响应成功之后：看板刷新/SSE 以新对象替换同一订单，`AssignModal` 再次执行 `resetOptionPages()` 并递增 `requestSeq`，从而清空候选并丢弃已返回结果；
+- 不得通过放宽后端车辆/车队/车型或冲突过滤来掩盖前端状态重置问题。
+
+该问题也属于 [#5279 车务派单全链路 E2E 前端缺陷交接](./27_5279_车务派单全链路E2E前端缺陷交接-修改接口-管理后台.md)“后台刷新不得重置正在编辑的派车草稿”的同类消费缺陷；#5283 补充了候选 19/11 的独立网关证据和稳定初始化键要求。
+
+## 变更接口
+
+```http
+POST /admin/fleet/assignments/candidates
+Content-Type: application/json
+Authorization: Bearer <admin-token>
+```
+
+接口继续返回车辆、司机两套独立分页候选。前端应消费 `vehicles.records/total` 与 `drivers.records/total`（兼容别名 `list` 仍保留），并以 `available`、`availabilityReasonCode`、`conflicts[]` 和 `availabilityWindows[]` 展示可用性；本次没有后端契约变化。
+
+## 前端修复口径
+
+### 1. 以稳定业务身份决定是否重新初始化
+
+不得仅监听 `props.order` 对象身份。应使用 `initializationIdentity` 或等价稳定键，至少覆盖：
+
+- `orderId`；
+- 当前 `requirementId`；
+- 目标 `assignmentSlotId/fleetItemIndex`；
+- `assign/change` 模式及必要入口上下文。
+
+只有上述业务身份真正变化，或用户主动关闭后重新打开弹窗时，才允许执行 `resetOptionPages()` 和重建派车草稿。同一订单仅因列表刷新或 SSE 生成新对象时不得重置。
+
+### 2. 保留候选与编辑草稿
+
+同一稳定业务身份下刷新订单对象时，必须保留：
+
+- 车辆/司机候选 `records/total/page/pageSize`；
+- 车队、车型、关键字和可用性筛选；
+- 已选车辆、司机、日期和稳定槽位；
+- 收费服务日、逐日价格、调价/免费原因；
+- 跨常驻确认以及 `HOLD/DIRECT` 模式。
+
+若服务端基线确实变化，继续使用现有 baseline-difference 强提示，由用户决定如何处理；不得静默清空或改写草稿。
+
+### 3. 保留并发响应保护，但不得误杀当前请求
+
+继续保留 `requestSeq` 或等价的旧响应隔离机制。只有新业务身份或新查询真正开始时才递增序号；同一订单对象替换不得把已经成功返回的当前候选标记为过期。快速连续刷新时，旧请求不能覆盖新请求，新请求成功结果也不能被无关初始化清空。
+
+## 前端验收清单
+
+- [ ] 专用测试订单 `26-4700`、`2026-08-04..2026-08-07`、SUV、3 人请求返回后，页面候选数量与接口一致，不再错误显示 0。
+- [ ] 相同订单、需求、槽位和模式下，列表/SSE 替换订单对象后，车辆和司机候选仍保留。
+- [ ] 候选分页总数、筛选条件、已选项和费用草稿不被后台刷新清空。
+- [ ] 已切换的 `HOLD/DIRECT` 模式不会因同订单刷新恢复默认值。
+- [ ] 订单、需求、槽位或模式真实变化时仍能正确重新初始化。
+- [ ] 快速连续刷新时，旧响应不能覆盖新响应，当前成功响应也不会被误判过期。
+- [ ] Network 记录仍使用现有候选接口，无新增或修改后端请求契约。
+
+## 验证证据
+
+- 测试网关与 Fleet 双实例同口径响应：`code=200`、车辆总数 19、可用 11、真实冲突 8；
+- 目标测试车辆均为 `AVAILABLE`，目标日期冲突数为 0；
+- 后端 worktree 零代码改动，当前候选过滤、日期闭区间冲突和 API 契约保持不变；
+- 前端 HMR 现场曾出现稳定 `initializationIdentity` 方向的修正，但尚无 `mmg/hl-ui v2.1` 远端提交与发布验收依据，因此本文件保持 `frontend_status: "pending"`。
+
+## 契约审查
+
+- Frontend API：现有接口消费纠错，无 Controller/DTO/VO/字段变化，OpenAPI diff 为 `not_required`；
+- Internal Feign / shared Java：无变化，Consumer Contract 为 `not_required`；
+- 后端真值由已部署测试环境网关响应和现有 Fleet 源码确认；changelog 发布不代表前端已实现或已发布。
+
+## 不影响范围
+
+- 不修改 `hl-ui`，不在 `mmg/hl-ui` 创建工单；
+- 不修改后端候选过滤、日期冲突、车辆/司机占用、派单状态机、计费、保险、通知或数据库；
+- 不把前端实现、发布和页面验收冒充为本次后端代码交付。