docs(changelog): #5914 看板详情新增换版原因reassignReasons 实测证据回填

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

changelogs-v2/2026-08/12_5914_看板详情新增换版原因reassignReasons-修改接口-管理后台.md

@@ -0,0 +1,80 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5914"
+title: "看板详情新增换版原因 reassignReasons：改人数/改出发日期/改行程天数的精确 diff"
+consumer: "admin"
+change_type: "修改接口"
+author: "wx(GIT)"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+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 已同步。