diff --git a/changelogs-v2/2026-07/27_5283_派车候选响应被订单刷新清空-修改接口-管理后台.md b/changelogs-v2/2026-07/27_5283_派车候选响应被订单刷新清空-修改接口-管理后台.md new file mode 100644 index 0000000..c495b85 --- /dev/null +++ b/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 +``` + +接口继续返回车辆、司机两套独立分页候选。前端应消费 `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` 创建工单; +- 不修改后端候选过滤、日期冲突、车辆/司机占用、派单状态机、计费、保险、通知或数据库; +- 不把前端实现、发布和页面验收冒充为本次后端代码交付。