diff --git a/changelogs-v2/2026-08/12_5914_看板详情新增换版原因reassignReasons-修改接口-管理后台.md b/changelogs-v2/2026-08/12_5914_看板详情新增换版原因reassignReasons-修改接口-管理后台.md new file mode 100644 index 0000000..2188982 --- /dev/null +++ b/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 已同步。