diff --git a/changelogs-v2/2026-07/24_5200_用车需求驳回历史与重新提交-修改接口-管理后台.md b/changelogs-v2/2026-07/24_5200_用车需求驳回历史与重新提交-修改接口-管理后台.md new file mode 100644 index 0000000..18d0fd7 --- /dev/null +++ b/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` +- 联调/验收环境: +- 小程序:无需处理 + +> **服务**: 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`。