---
schema: "hl-changelog/v2"
ticket: "5914"
title: "看板详情新增换版原因 reassignReasons：改人数/改出发日期/改行程天数的精确 diff"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "a254f29f"
target_release: ""
verified_at: "2026-08-12"
status_note: "后端已实现并部署测试服，API 实测通过。订单因改人数/改出发日期/改行程天数触发车需求换版（DONE_ADJUST）后，看板详情端点 GET /admin/fleet/board/orders/{orderId} 新增 reassignReasons 字段（仅换版版本返回，否则为 null），给出精确 diff 供前端在排车页「当前需求」区提示车务为何需重新配车。示例：改人数 → [{type:HEADCOUNT_CHANGE, oldValue:10, newValue:11, label:出行人 10→11}]；改出发日期 → DEPART_DATE_CHANGE 出发日期 8/18→8/21；改行程天数 → TRIP_DAYS_CHANGE 行程 4天→5天；多选并存返回多条。前端在「当前需求」区渲染 label 即可（label 后端直出可直接展示，oldValue/newValue/type 供自定义）。"
updated_at: "2026-08-12"
base: "dev-v3"
---

# 看板详情新增换版原因 reassignReasons（#5914）

> **服务**: hl-order-service-v3（记录）+ hl-fleet-service（透出）
> **日期**: 2026-08-12
> **背景**: 车务派单看板「当前需求」区，订单因改人数/改期/改行程换版后需重新走配车确认，但车务看不到**为什么要重新配车**。本条在换版时记录精确原因并在看板返回，全部为**新增响应字段，向后兼容，无破坏性变更**。

---

## 一、变更接口

| 方法 | 路径 | 变更 |
|------|------|------|
| `GET` | `/admin/fleet/board/orders/{orderId}` | 新增 `reassignReasons` 字段（仅换版版本返回） |

---

## 二、契约字段 reassignReasons

仅在当前生效用车需求为**换版**（DONE_ADJUST）产生的版本时返回；首提/待审编辑/幂等重提等非换版场景为 `null`。

数组，元素结构：

| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | string | `HEADCOUNT_CHANGE`(改人数) / `DEPART_DATE_CHANGE`(改出发日期) / `TRIP_DAYS_CHANGE`(改行程天数) |
| `oldValue` | string | 旧值（人数 / 出发月日 / 天数） |
| `newValue` | string | 新值 |
| `label` | string | 后端直出中文，可直接展示 |

示例（同时改人数+出发日期）：

```json
"reassignReasons": [
  { "type": "HEADCOUNT_CHANGE", "oldValue": "10", "newValue": "11", "label": "出行人 10→11" },
  { "type": "DEPART_DATE_CHANGE", "oldValue": "8/18", "newValue": "8/21", "label": "出发日期 8/18→8/21" }
]
```

## 三、前端展示建议（mmg）

排车页「当前需求」区，在需求卡片下方按 `reassignReasons[]` 逐条渲染 `label`（如：「出行人 10→11」「出发日期 8/18→8/21」「行程 4天→5天」），提示车务本次为何需重新配车。字段为 `null` 时不渲染。

## 四、实现说明（后端，对前端透明）

- 换版统一收口 `RequirementService.doUpsertVehicleRequirement` DONE_ADJUST 分支，diff 旧版与新基线（人数/出发日期/行程天数）生成原因 JSON，存 `order_vehicle_requirement.adjust_reason`（新版本行；新 Flyway V20260812_001 加列）。
- 经既有 Feign 契约 `VehicleRequirementForFleetDTO.reassignReasons` 透出（不新增跨服务调用），fleet 看板详情 `BoardOrderDetailVO.reassignReasons` 透传。

## 五、验收

- [x] 改订单人数触发换版后，board detail 返回 `reassignReasons` 含「出行人 旧→新」
- [x] 改出发日期触发换版后，含「出发日期 旧→新」
- [x] 改行程天数触发换版后，含「行程 旧天→新天」
- [x] 同时改多项返回多条
- [x] 非换版（首版/待审编辑/幂等）该字段为 null

## 验证证据(测试服 API 实测，订单 2086270138171994114 / 2086270141158346754)

- **改人数换版（正向）**：订单 `2086270138171994114`（26-3698，原 10 人）提交调整 `updates.people.travelers.add` +1 出行人（10→11）触发 DONE_ADJUST 换版。DB 新版本行 `order_vehicle_requirement.adjust_reason` 落 `[{"type":"HEADCOUNT_CHANGE","oldValue":"10","newValue":"11","label":"出行人 10→11"}]`；`GET /admin/fleet/board/orders/2086270138171994114` 返回 `reassignReasons` 一致（requirementVersion=4，headcount=11）。
- **非换版（反向）**：订单 `2086270141158346754`（26-0821，v7 PROCESSING 非 DONE_ADJUST 换版）返回 `reassignReasons=null`，不误标。
- **改出发日期/行程天数/多项并存**：由 `RequirementServiceTest` 单测覆盖（DEPART_DATE_CHANGE 出发日期 7/20→8/18、TRIP_DAYS_CHANGE 行程 2天→3天、多项并存按序返回 3 条）。
- **门禁**：Flyway `20260812.001 add vehicle requirement adjust reason` success=1、列已加；order-v3 274 / fleet 129 / ArchTest 44+13 / 50 个 MySQL IT 全绿；H2 IT schema 已同步。
