# 行程详情接口 itineraryDays / dailyItinerary / hotelArrangements 三字段强类型化 — 2026-04-21

> **服务** hl-order-service-v2（端口 8094）· **类型** refactor · **关联** Issue #1119 / PR #1123
> **破坏性程度**：JSON 结构完全不变，**前端只需升级 TypeScript 类型定义**

---

## 一、影响接口

所有返回 `TripDetailVO` 的接口（三字段类型变更，字段名和 JSON 路径保持一致）：

- `GET /admin/order/{orderId}/trip` — 管理端行程详情
- `GET /mp/trip/{orderId}` — 小程序行程详情（BFF 透传）
- `GET /mp/trip/today` — 小程序今日行程（BFF 透传）

## 二、字段类型变更

| 字段 | 旧类型 | 新类型 |
| --- | --- | --- |
| `itineraryDays` | `List<Map<String, Object>>` | `List<TripItineraryDayVO>`（按 `dayNumber` 升序） |
| `dailyItinerary` | `List<Map<String, Object>>` | `List<TripItineraryNodeVO>`（所有天节点扁平拼接） |
| `hotelArrangements` | `List<Map<String, Object>>` | `List<TripHotelArrangementVO>`（按 `hotelId` 合并同家酒店多房型） |

## 三、新强类型结构

### `TripItineraryDayVO`（每日行程）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `dayNumber` | `Integer` | 第几天（从 1 开始） |
| `date` | `LocalDate` | 当天日期 |
| `weekday` | `String` | 星期中文（如 "周三"） |
| `dayTitle` | `String` | 当日主题 |
| `scenicCount` | `Integer` | 当日景点数（已排除 SKIPPED 节点） |
| `dayDistanceKm` | `Integer` | 当日总里程（km） |
| `nodes` | `List<TripItineraryNodeVO>` | 节点时间线 |
| `hotels` | `List<TripHotelArrangementVO>` | 当晚酒店（无则为空列表） |

### `TripItineraryNodeVO`（时间线节点）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `nodeSeq` | `Integer` | 当天第几站（从 1 开始） |
| `nodeType` | `String` | `SCENIC` / `MEAL` / `HOTEL` / `TRANSPORT` / `ACTIVITY` / `GATHER` / `DISMISS` |
| `nodeTypeLabel` | `String` | 中文标签 |
| `title` | `String` | 节点标题 |
| `subtitle` | `String` | 副标题 / 描述 |
| `plannedTime` | `String` | 计划时间 `HH:mm` |
| `durationMinutes` | `Integer` | 至下一节点车程（分钟） |
| `distanceKm` | `Integer` | 至下一节点距离（km） |
| `editStatus` | `String` | `ADDED` / `REPLACED` / `MODIFIED` / `SKIPPED`；null=未改动 |
| `resourceId` | `Long` | 关联资源主键 |
| `resourceType` | `String` | 对齐 nodeType |

### `TripHotelArrangementVO`（每晚酒店）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `dayNumber` | `Integer` | 对应第几天 |
| `date` | `LocalDate` | 入住日期 |
| `hotelId` | `Long` | 酒店ID |
| `hotelName` | `String` | 酒店名称 |
| `checkInTime` | `String` | 入住时间 `HH:mm` |
| `checkOutTime` | `String` | 退房时间 `HH:mm` |
| `longitude` / `latitude` | `BigDecimal` | 坐标（导航用） |
| `address` | `String` | 地址 |
| `photoUrls` | `List<String>` | 酒店照片 |
| `rooms` | `List<TripHotelRoomVO>` | 房型列表 |
| `wifi` | `TripHotelWifiVO` | WiFi（酒店未录入时为 null） |
| `changedFromYesterday` | `Boolean` | 与前一晚不是同一家酒店 |

### `TripHotelRoomVO` / `TripHotelWifiVO`

```
TripHotelRoomVO { roomType, quantity, areaSqm, amenities: List<String> }
TripHotelWifiVO { ssid, password }
```

## 四、兼容性

- **JSON 结构完全不变**：字段名、嵌套路径、值类型在 JSON 层保持一致，前端只需把 TypeScript 类型从 `Record<string, any>[]` 升级为强类型接口
- 聚合接口 `GET /mp/trip/today-dashboard` 下游消费已同步升级（见 `2026-04-21_mp_today-dashboard-full-aggregation.md`）

## 五、关联

- Issue: [wx/HL#1119](https://git.1814.love:8443/wx/HL/issues/1119)
- PR: [wx/HL#1123](https://git.1814.love:8443/wx/HL/pulls/1123)（已合并到 dev）
- 后续：酒店 WiFi 字段补齐见 `2026-04-21_resource_hotel-wifi-fields.md`
