docs(order): hand off vehicle rejection history (#5200)

changelogs-v2/2026-07/24_5200_用车需求驳回历史与重新提交-修改接口-管理后台.md

@@ -0,0 +1,150 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5200"
+title: "用车需求驳回历史与重新提交"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+base: "dev-v3"
+generated: "2026-07-24T11:05:00+08:00"
+---
+
+# 【修改接口·前端待处理·管理后台】用车需求驳回历史与重新提交
+
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 目标分支：`v2.1`
+- 联调/验收环境：<http://192.168.100.160:9527>
+- 小程序：无需处理
+
+> **服务**: hl-order-service-v3、hl-fleet-service
+>
+> **工单**: [wx/HL#5200](https://git.1814.love:8443/wx/HL/issues/5200)
+>
+> **影响范围**: 订单详情行程安排中的用车需求、驳回后的重新提交
+
+## 业务口径
+
+- 用车需求被车务驳回后，旧版本终态失活并作为只读历史保留，不是“已回配”。
+- 驳回后没有当前 active 用车需求，订单详情允许定制师重新提交。
+- 重新提交创建新的 active 版本并重新进入车务流程，不复活或覆盖旧版本。
+- 新旧版本可以同屏展示：当前版本保留原有操作，历史版本只读。
+
+## 一、订单详情行程安排
+
+接口：
+
+```http
+GET /v3/admin/order/{orderId}/itinerary
+```
+
+响应 `data` 新增：
+
+```json
+{
+  "vehicleGroup": null,
+  "vehicleHistory": [
+    {
+      "requirementId": "2080186927616606210",
+      "version": 1,
+      "status": "REJECTED_TO_CONSULTANT",
+      "isActive": false,
+      "submittedAt": "2026-07-23 15:03:06",
+      "returnedAt": "2026-07-24 09:20:00",
+      "returnRemark": "当地无合适车辆",
+      "vehicleTypeSummary": "suv×1",
+      "specialTags": ["儿童安全座椅", "大行李空间"],
+      "pickupRequired": true,
+      "dropoffRequired": true,
+      "remark": "原需求备注"
+    }
+  ],
+  "canContactFleet": false,
+  "contactFleetDisabledReason": "请先提交有效用车需求后再联系车务"
+}
+```
+
+### `vehicleHistory` 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `requirementId` | `String` | 历史需求 ID |
+| `version` | `Integer` | 版本号，列表按版本倒序 |
+| `status` | `String` | 驳回场景为 `REJECTED_TO_CONSULTANT` 或 `REJECTED_TO_ADMIN` |
+| `isActive` | `Boolean` | 历史项固定为 `false` |
+| `submittedAt` | `LocalDateTime` | 原需求提交时间 |
+| `returnedAt` | `LocalDateTime/null` | 驳回时间 |
+| `returnRemark` | `String/null` | 驳回原因 |
+| 其余摘要字段 | 与 `vehicleGroup.requirement` 相同 | 车型、座位、接送、特殊诉求和备注等原需求快照 |
+
+边界行为：
+
+- 从未提交用车需求：`vehicleGroup=null`、`vehicleHistory=[]`。
+- 已驳回且尚未重提：`vehicleGroup=null`、`vehicleHistory` 包含驳回历史。
+- 已重新提交：`vehicleGroup.requirement` 是新 active 版本，`vehicleHistory` 仍包含旧版本。
+- 历史列表还可能包含被正常重版替换的失活版本，前端按 `status` 决定是否展示“已驳回”。
+
+## 二、重新提交
+
+继续使用现有接口：
+
+```http
+PUT /v3/admin/order/{orderId}/vehicle-requirement
+```
+
+驳回后提交的返回语义：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "version": 2,
+    "isActive": true,
+    "status": "PENDING",
+    "branchTaken": "INIT_SUBMIT"
+  }
+}
+```
+
+版本规则：
+
+- 新版本号 = 历史最高版本号 + 1；
+- 新版本为当前 active 需求；
+- 旧驳回版本继续留在 `vehicleHistory`；
+- 仅新版本进入车务看板和派单流程。
+
+## 三、前端处理清单
+
+- [ ] 订单详情用车卡片固定支持“历史需求”只读区域，不论当前 active 需求是否存在。
+- [ ] 历史项展示版本、原需求内容、驳回状态、`returnedAt` 和 `returnRemark`。
+- [ ] 历史项不得显示修改、联系车务、派车或“已回配”等当前需求操作/文案。
+- [ ] `vehicleGroup=null` 且 `vehicleHistory` 非空时，继续显示“提交用车需求”入口。
+- [ ] 有新 `vehicleGroup.requirement` 时，同时展示当前需求和旧历史，历史项不覆盖当前状态。
+- [ ] 不要把 `vehicleHistory` 项映射成当前 `vehicleGroup.requirement`。
+- [ ] 覆盖驳回未重提、驳回后重提、存在多个历史版本三个场景。
+
+## 四、兼容说明
+
+现有前端在 `vehicleGroup=null` 时已能进入“提交用车需求”空态，因此后端部署后不会再把驳回需求误显示成“已回配”。新增历史区域需要前端按上方清单接入；未接入时只是暂不展示历史内容，不影响重新提交。
+
+## 五、后端验证
+
+- 驳回 CAS 原子更新 `status`、`is_active=false`、驳回原因/时间并清空接单人。
+- Fleet Outbox 按“订单需求驳回成功 → 取消未派占位”的顺序执行；重放已失活驳回历史时幂等成功。
+- 无 active 需求时按历史最高版本递增，兼容旧 active rejected 数据。
+- 订单/Fleet 相关定向测试累计 658 项通过。
+- `mvn -pl hl-order-service-v3 -am verify`、`mvn -pl hl-fleet-service -am verify` 和 fleet `spotless:check` 全部通过。
+- 后端 PR [wx/HL#5206](https://git.1814.love:8443/wx/HL/pulls/5206) 已合并到
+  `dev-v3@c13a035d0`；测试环境滚动部署任务 `a2a5a9fa` 成功，8086/8186 两实例健康。
+- 网关以 `wx` 验证订单 `26-9919`：驳回迁移后 `vehicleGroup=null`，
+  `vehicleHistory` 返回 v1、`REJECTED_TO_CONSULTANT`、`isActive=false` 及原驳回原因；
+  重新提交返回 v2、`PENDING`，再次查询同时保留 v1 历史和 v2 当前需求。
+- 测试库核对：v1 已失活且保留，v2 为唯一 active；Fleet 为 v2 生成 6 条
+  `unassigned` 日切片，旧 v1 的 6 条派单保持 `canceled`。
+- 异常团号 `26-4165` 的 3 条旧派单均已取消并软删除，0 条可见、0 条在途；
+  对应失败 Outbox 已进入 `QUARANTINED`，网关看板按团号搜索返回 0 条。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。