From 3d1aae55c93693512d510d17093521760a77c4c6 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Wed, 25 Mar 2026 10:52:53 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=8C=E7=A8=8B=E8=AF=A6=E6=83=85=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E6=94=B9=E9=80=A0=EF=BC=9A=E9=9B=86=E6=88=90=E7=9B=B8?=
 =?UTF-8?q?=E5=86=8C+=E8=AF=84=E4=BB=B7+=E8=BF=9B=E5=BA=A6=E7=BB=9F?=
 =?UTF-8?q?=E8=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-03/2026-03-25_trip_detail_upgrade.md | 135 ++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 changelogs/2026-03/2026-03-25_trip_detail_upgrade.md

diff --git a/changelogs/2026-03/2026-03-25_trip_detail_upgrade.md b/changelogs/2026-03/2026-03-25_trip_detail_upgrade.md
new file mode 100644
index 0000000..18f5e2f
--- /dev/null
+++ b/changelogs/2026-03/2026-03-25_trip_detail_upgrade.md
@@ -0,0 +1,135 @@
+# 行程详情接口改造 — 集成相册、评价、进度统计
+
+> 行程详情接口 `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`