---
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`。