diff --git a/changelogs/2026-04/2026-04-21_order-v2_admin-itinerary-summary.md b/changelogs/2026-04/2026-04-21_order-v2_admin-itinerary-summary.md new file mode 100644 index 0000000..2eaf6be --- /dev/null +++ b/changelogs/2026-04/2026-04-21_order-v2_admin-itinerary-summary.md @@ -0,0 +1,149 @@ +# 管理端行程安排聚合接口 + 订单详情房间日期补全 — 2026-04-21 + +> **服务** hl-order-service-v2（端口 8094）· **类型** feat + fix · **关联** PR #1064 +> **使用场景**：管理端订单详情 · 行程安排 Tab · 查看场景一次性加载 +> **前端调用路径**：网关(8080) → hl-order-service-v2(8094) + +--- + +## 一、新增聚合接口 + +### 🆕 `GET /admin/order/{orderId}/itinerary/summary` — 行程安排聚合 + +**功能**：一次返回【行程安排】Tab 所需的 **房间 / 车辆 / 交通** 三段数据，替代前端分别调用 +`/hotel-assignment`、`/vehicle-assignment`、`/arrival` 的三次并发请求。 + +原三个接口**保留不动**，编辑场景仍各自调用；查看场景推荐走此聚合接口。 + +**请求参数**： + +| 参数 | 位置 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | --- | +| `orderId` | Path | `Long` | ✅ | 订单ID | + +**返回值** `Result`： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `orderId` | `Long` | 订单ID | +| `hotelAssignments` | `List` | 房间安排列表（字段同 `GET /hotel-assignment`，含 `assignmentDate` 现算值） | +| `vehicleAssignments` | `List` | 车辆安排列表（字段同 `GET /vehicle-assignment`，司机电话脱敏） | +| `transports` | `ArrivalListRespVO` | 交通信息（字段同 `GET /arrival`，按 `ARRIVAL`/`DEPARTURE` 分组） | + +> 💡 `transports` 是 VO 包对象而非扁平 List，内部按到达/离开方向拆成 `arrivals` / `departures` 两个子列表，结构与 `GET /arrival` 一致，保留方向分组语义。 + +**`transports` 子结构**： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `orderId` | `Long` | 订单ID | +| `arrivals` | `List` | 到达批次（`direction=ARRIVAL`） | +| `departures` | `List` | 离开批次（`direction=DEPARTURE`） | + +**响应示例**： + +```json +{ + "code": 200, + "data": { + "orderId": 700001, + "hotelAssignments": [ + { + "assignmentId": 800001, + "orderId": 700001, + "familyIndex": 1, + "hotelId": 500001, + "hotelName": "香格里拉", + "roomTypeId": 500101, + "roomType": "大床房", + "dayNumber": 1, + "assignmentDate": "2026-07-01", + "upgradePrice": null, + "remark": null + } + ], + "vehicleAssignments": [ + { + "assignmentId": 900001, + "orderId": 700001, + "vehicleType": "丰田普拉多", + "vehicleCount": 1, + "plateNumber": "蒙A·A1234", + "driverName": "李师傅", + "driverPhone": "138****1234", + "remark": null, + "createTime": "2026-04-20 10:00:00" + } + ], + "transports": { + "orderId": 700001, + "arrivals": [ + { + "planId": 800001, + "orderId": 700001, + "direction": "ARRIVAL", + "directionLabel": "到达", + "transportType": "FLIGHT", + "transportTypeLabel": "飞机", + "transportNo": "CZ6255" + } + ], + "departures": [] + } + } +} +``` + +> 💡 三段子项**都带主键**：`hotelAssignments[].assignmentId` / `vehicleAssignments[].assignmentId` / `transports.arrivals[].planId`，从查看态进入编辑态的路径完全通畅。 + +--- + +## 二、现有接口字段修复 + +### 🐛 `GET /admin/order/{orderId}` — 订单详情 + +**修复**：`hotelAssignmentDetails[].assignmentDate` 之前返回 `null`（由于字段存储方式改为 `dayNumber`），现已由后端按 `order.departureDate + dayNumber - 1` 现算填充。 + +前端若此前已降级为展示 `-` 或基于 `dayNumber` 自行计算日期，可在本次迭代后恢复直接读取 `assignmentDate`。其他字段保持不变。 + +--- + +## 三、与已有接口关系 + +| 接口 | 作用 | 状态 | +| --- | --- | --- | +| `GET /admin/order/{orderId}/hotel-assignment` | 查酒店分配 | 已有（未变，仍可单独调） | +| `GET /admin/order/{orderId}/vehicle-assignment` | 查车辆分配 | 已有（未变，仍可单独调） | +| `GET /admin/order/{orderId}/arrival` | 查到达批次（按方向分组） | 已有（未变，仍可单独调） | +| `GET /admin/order/{orderId}/itinerary/summary` | 一次返回上述三段 | **本期新增** | + +聚合接口与三个独立接口**并存**： +- **查看态**：推荐走 `/itinerary/summary`，一次请求拿全。 +- **编辑态**：仍各自调子接口，减少无关数据传输。 + +--- + +## 四、数据库变更 + +**无**。纯服务层聚合，数据源均是既有表。 + +--- + +## 五、错误码 + +HTTP 始终返回 200，错误码在 `Result.code` 中。 + +| code | 触发 | 说明 | +| --- | --- | --- | +| 200 | 正常 | 成功（无分配数据返回空列表/空子对象） | +| 400 | 订单不存在 | `BusinessException` | + +--- + +## 六、关联 + +- PR: [wx/HL#1064](https://git.1814.love:8443/wx/HL/pulls/1064)（已合并到 dev） +- 相关接口： + - `GET /admin/order/{orderId}/hotel-assignment` · `GET /admin/order/{orderId}/vehicle-assignment` — 见 `2026-04-20_order-v2_admin-assignment-get.md` + - `GET /admin/order/{orderId}/arrival` — 见 `2026-04-20_order-v2_arrival.md`（C 端，管理端字段结构一致） + - `PUT /admin/order/{orderId}/hotel-assignment` `date → dayNumber` 破坏性变更 — 见 `2026-04-21_order-v2_hotel-assignment-day-number.md` diff --git a/changelogs/2026-04/2026-04-21_order-v2_admin-vehicle-assignment-count-removed.md b/changelogs/2026-04/2026-04-21_order-v2_admin-vehicle-assignment-count-removed.md new file mode 100644 index 0000000..ab5fd37 --- /dev/null +++ b/changelogs/2026-04/2026-04-21_order-v2_admin-vehicle-assignment-count-removed.md @@ -0,0 +1,73 @@ +# 管理端配车接口下线 vehicleCount 字段 — 2026-04-21 + +> **服务** hl-order-service-v2（端口 8094）· **类型** refactor · **关联** Issue #1053 / PR #1054 +> **破坏性变更**：请求 body 字段 `vehicleCount` 删除，前端不再传，后端固定写 1 + +--- + +## 一、影响接口 + +### ✏️ `PUT /admin/order/{orderId}/vehicle-assignment` — 分配车辆（管理端） + +**请求参数变更**：`VehicleAssignmentReqVO` 移除 `vehicleCount` 字段。当前阶段每单车辆数固定为 1，后端直接写入，前端无需传递。 + +**变更对比**： + +| 字段 | 状态 | 说明 | +| --- | --- | --- | +| ~~`vehicleCount`~~ | **已删除** | 前端传入将被忽略（JSON 未知字段不报错） | + +**保留字段**： + +| JSON 字段 | Java 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | --- | +| `vehicleModel` | `vehicleType` | `String` | ✅ ≤100 | 车型（`@JsonProperty("vehicleModel")` 对齐前端契约） | +| `plateNumber` | `plateNumber` | `String` | 否 ≤20 | 车牌号 | +| `driverName` | `driverName` | `String` | 否 ≤50 | 司机姓名 | +| `driverPhone` | `driverPhone` | `String` | 否 ≤20 | 司机电话 | +| `remark` | `remark` | `String` | 否 ≤500 | 备注 | + +**新请求示例**： + +```json +PUT /admin/order/700001/vehicle-assignment +{ + "vehicleModel": "商务车", + "plateNumber": "京A12345", + "driverName": "张三", + "driverPhone": "13800000000", + "remark": "" +} +``` + +**返回值** `Result`（`code=200` 即成功）。 + +--- + +### ℹ️ `GET /admin/order/{orderId}/vehicle-assignment` — 查车辆分配（未变） + +返回值 `VehicleAssignmentVO` 仍然包含 `vehicleCount` 字段（当前版本固定为 `1`），为后续多车扩展预留。 + +--- + +## 二、数据库变更 + +**无**。`order_vehicle_assignment` 表未改。 + +--- + +## 三、错误码 + +HTTP 始终返回 200，错误码在 `Result.code` 中。 + +| code | 触发 | 说明 | +| --- | --- | --- | +| 200 | 正常 | 成功 | +| 400 | `vehicleModel` 缺失/超长 | 参数校验失败 | + +--- + +## 四、关联 + +- Issue: [wx/HL#1053](https://git.1814.love:8443/wx/HL/issues/1053) +- PR: [wx/HL#1054](https://git.1814.love:8443/wx/HL/pulls/1054)（已合并到 dev）