# 行程详情接口改造 — 集成相册、评价、进度统计

> 行程详情接口 `GET /mp/trip/{orderId}` 增量改造，按三种行程阶段新增字段。**原有字段全部保留不变，纯新增。**

---

## 一、接口信息

| 项目 | 说明 |
|------|------|
| 接口路径 | `GET /mp/trip/{orderId}` |
| 涉及服务 | hl-mp-service（BFF）→ hl-order-service → hl-review-service |
| 需重启服务 | hl-order-service、hl-review-service、hl-mp-service |

---

## 二、新增字段（按行程阶段）

### 2.1 开始前（tripPhase = "BEFORE_START"）

| 新增字段 | 类型 | 说明 |
|---------|------|------|
| `itinerarySummary` | `Array<Object>` | 行程路线摘要，用于渲染 DAY 卡片列表 |
| `itinerarySummary[].dayNumber` | Integer | 第几天 |
| `itinerarySummary[].dayTitle` | String | 当天标题（如"森林公园休闲"） |
| `itinerarySummary[].dayCoverUrl` | String \| null | 当天封面图URL |

### 2.2 行程中（tripPhase = "IN_PROGRESS"）

| 新增字段 | 类型 | 说明 |
|---------|------|------|
| `traveledDistanceKm` | Integer | 已行驶里程（km），含当天 |
| `visitedScenicCount` | Integer | 已到访景点数，含当天 |
| `pendingScenicCount` | Integer | 待到访景点数（未来天数） |
| `todayTitle` | String \| null | 当日行程标题（如"DAY 2 森林公园休闲"中的"森林公园休闲"） |

### 2.3 已结束（tripPhase = "ENDED"）

#### 旅拍相册

| 新增字段 | 类型 | 说明 |
|---------|------|------|
| `albumStatus` | String | 相册状态：`NONE`=无相册, `GENERATING`=生成中(有文件夹无文件), `READY`=已生成 |
| `albumFolderCount` | Integer | 相册文件夹数 |
| `albumFileCount` | Integer | 相册文件总数（照片+视频） |
| `albumCoverUrl` | String \| null | 相册封面图URL |

#### 行程评价

| 新增字段 | 类型 | 说明 |
|---------|------|------|
| `reviewStatus` | String | 评价状态：`NONE`=未评价, 其他值为评价审核状态（如 `APPROVED`） |
| `reviewId` | String \| null | 评价ID，可用于跳转查看评价详情 |
| `ratingItinerary` | Integer \| null | 行程安排评分(1-5) |
| `ratingAccommodation` | Integer \| null | 住宿安排评分(1-5) |
| `ratingDriver` | Integer \| null | 司机服务评分(1-5) |
| `ratingDining` | Integer \| null | 餐饮质量评分(1-5) |
| `ratingOverall` | Integer \| null | 整体满意度评分(1-5) |
| `ratingLevel` | String \| null | 评价等级：`GOOD`/`MEDIUM`/`BAD` |
| `reviewContent` | String \| null | 评价文字内容 |
| `isReviewed` | Boolean | 是否已评价（兼容旧字段，true=已评价） |

---

## 三、原有字段（不变）

以下字段保持不变，前端无需修改现有逻辑：

**通用字段**：orderId, orderNo, productName, productCoverUrl, departureDate, tripDays, tripNights, status, tripPhase, currentDayNumber, countdownDays, countdownHours, dateRange, totalPeople, productDescription, guideName, guidePhone, guideAvatar, guideStaffType, meetingTime, meetingLocation, meetingNodeName, customizerId, customizerName, customizerAvatarUrl, customizerQrUrl, contracts, insurances, itineraryDays, totalScenicCount, totalDistanceKm, avgDailyDistanceKm

**开始前特有**：warmTips, bookingNotice, suppliesList, cancelPolicy, refundPolicyId

**行程中特有**：travelTips, todayDayNumber

**已结束特有**：completedAt

---

## 四、使用场景

### 场景1：已结束页面 — 旅拍相册区域

```
if (albumStatus === 'NONE') → 不显示相册区域
if (albumStatus === 'GENERATING') → 显示"旅拍相册生成中" + 加载动画
if (albumStatus === 'READY') → 显示"旅拍相册已生成" + albumCoverUrl封面 + "查看相册"按钮
  点击查看相册 → 跳转相册页面（已有 /mp/album/orders/{orderId}/folders 接口）
```

### 场景2：已结束页面 — 行程评价区域

```
if (reviewStatus === 'NONE') → 显示评价入口（星级选择 + "提交评价"按钮）
if (reviewStatus !== 'NONE' && isReviewed) → 显示已提交的评分星级
  ratingOverall → 整体满意度星级
  ratingDriver → 定制师/司机满意度星级
  点击"查看评价" → 跳转评价详情（用 reviewId）
```

### 场景3：已结束页面 — 行程回顾

```
totalDistanceKm → 总里程（如"2485公里"）
avgDailyDistanceKm → 日均里程（如"393公里"）
totalScenicCount → 到访景点数（如"12个"）
```

### 场景4：行程中页面 — 顶部进度

```
traveledDistanceKm → 已行驶里程
visitedScenicCount → 已到访景点
pendingScenicCount → 待到访景点
todayTitle → 当日标题（如"森林公园休闲"）
currentDayNumber → 第几天（如 2）
```

### 场景5：开始前页面 — 行程路线DAY列表

```
itinerarySummary.forEach(day => {
  渲染卡片：DAY {day.dayNumber} {day.dayTitle}
  背景图：day.dayCoverUrl
})
```

---

## 五、注意事项

1. 新增字段**仅在对应阶段**返回，其他阶段为 null 或不存在
2. `isReviewed` 字段保留向后兼容，新代码建议优先使用 `reviewStatus` 判断
3. 相册相关的增删改接口已有，无需新开发：
   - 小程序端查看：`GET /mp/album/orders/{orderId}/folders`、`GET /mp/album/folders/{folderId}/files`
   - 后台管理：`POST /admin/order/{orderId}/album/folder`、`POST /admin/order/album/folder/{folderId}/files`