5.3 KiB
5.3 KiB
行程详情接口改造 — 集成相册、评价、进度统计
行程详情接口
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
})
五、注意事项
- 新增字段仅在对应阶段返回，其他阶段为 null 或不存在
isReviewed字段保留向后兼容，新代码建议优先使用reviewStatus判断- 相册相关的增删改接口已有，无需新开发：
- 小程序端查看：
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
- 小程序端查看：