changelog: C端订单详情页重构接口变更（详情返回值变更+6个弹窗接口）

详情接口返回值从OrderDetailVO改为MpOrderDetailVO，新增serviceItems/priceBreakdown/refundProgress/tripProgress等字段，新增6个弹窗接口(tickets/hotels/meals/vehicle/guide/photographer)。 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-17 15:00:56 +08:00 · 2026-04-17 15:00:56 +08:00 · 4bbebf273b
--- a/changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md
+++ b/changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md
@ -0,0 +1,242 @@
+# 接口变更记录 — 2026-04-17
+
+> **服务** hl-order-service-v2 · **类型** feat · **说明** C端订单详情页重构（详情接口返回值变更 + 新增6个弹窗接口）
+
+## 变更总览
+
+- **hl-order-service-v2**
+  - MpOrder（C端）: 详情接口返回值从 `OrderDetailVO` 改为 `MpOrderDetailVO`
+  - MpOrder（C端）: 新增6个服务详情弹窗接口
+
+---
+
+## hl-order-service-v2
+
+### MpOrder（C端/内部）
+
+---
+
+### ✏️ `GET` /internal/mp/order/{orderId} — 订单详情（**返回值变更**）
+
+**变更前**返回 `OrderDetailVO`（管理端通用），**变更后**返回 `MpOrderDetailVO`（C端专用）。
+
+**删除的字段**（管理端专属，C端不再返回）:
+
+| 删除字段 | 说明 |
+| --- | --- |
+| `totalCost` | 总成本（仅管理员可见） |
+| `surchargeAmount` | 费用增加总额 |
+| `pendingUpgradeAmount` | 待确认差价 |
+| `depositRatio` | 订金比例 |
+| `balanceProofUrl` | 尾款凭证URL |
+| `balancePayMethod` | 尾款支付方式代码 |
+| `remark` | 订单备注 |
+| `checklistConfirmed` | 清单确认状态 |
+| `unlockRequestedAt` | 解锁请求时间 |
+| `confirmedAt` | 确认时间 |
+| `readyAt` | 就绪时间 |
+| `creatorAdminId` | 创建人管理员ID |
+| `creatorName` | 创建人姓名 |
+| `mchId` / `mchName` | 商户号/名称 |
+| `sharerOpenid` | 分享人openid |
+| `productSnapshot` | 产品快照JSON |
+| `expiryMinutes` | 支付时限分钟数 |
+| `timeline` | 时间线列表 |
+| `processStatus` / `processStatusLabel` | 内部流程状态 |
+| `discountReason` | 优惠原因 |
+| `discounts` / `surcharges` | 优惠/附加费明细列表 |
+| `transportSegments` | 交通信息列表 |
+| `roomInfo` / `hotelAssignments` / `hotelAssignmentDetails` | 房间/酒店分配 |
+| `vehicleInfo` | 车辆信息JSON |
+| `refundPolicy` / `refundPolicyId` | 退款政策 |
+| `contactName` / `contactPhone` | 联系人（出行人列表中已有） |
+
+**新增的字段**:
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| 🆕 `serviceItems` | `List<ServiceItemVO>` | 服务包含摘要列表，见下方结构 |
+| 🆕 `notIncluded` | `String` | 不含说明（如"往返大交通、个人消费"） |
+| 🆕 `priceBreakdown` | `PriceBreakdownVO` | 价格明细（按人头+优惠+总额），见下方结构 |
+| 🆕 `balancePayMethodLabel` | `String` | 尾款方式标签（如"落地后由领队收取"） |
+| 🆕 `refundProgress` | `RefundProgressVO` | 退款进度（退款中/已取消时有值），见下方结构 |
+| 🆕 `tripProgress` | `TripProgressVO` | 行程进度（仅行程中状态有值），见下方结构 |
+| 🆕 `invoiceStatus` | `String` | 发票状态：`ISSUED`=已开/`PENDING`=待开/`NOT_ISSUED`=未开/`AFTER_TRIP`=出行后开 |
+| 🆕 `productTypeLabel` | `String` | 产品类型中文标签 |
+
+**保留不变的字段**: `orderId`, `orderNo`, `groupCode`, `productId`, `productName`, `productCoverUrl`, `productType`, `departureDate`, `returnDate`, `tripDays`, `tripNights`, `adultCount`, `childCount`, `youngChildCount`, `babyCount`, `createTime`, `status`, `statusLabel`, `displayStatus`, `displayStatusLabel`, `cancelReason`, `cancelledAt`, `completedAt`, `expiryTime`, `totalPrice`, `depositAmount`, `balanceAmount`, `paidAmount`, `paymentType`, `paymentTypeLabel`, `paidAt`, `payMethodLabel`, `discountAmount`, `refundAmount`, `contracts`, `insurances`, `travelers`, `todos`, `reviewed`, `customizerId`, `customizerName`, `customizerAvatarUrl`, `customizerQrUrl`
+
+---
+
+### 新增结构体说明
+
+#### ServiceItemVO（服务包含摘要项）
+
+```json
+{
+  "type": "HOTEL",
+  "title": "住宿",
+  "summary": "5晚精选当地酒店",
+  "clickable": true
+}
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `type` | `String` | `HOTEL`/`MEAL`/`VEHICLE`/`GUIDE`/`PHOTOGRAPHER`/`TICKET`/`INSURANCE` |
+| `title` | `String` | 服务标题 |
+| `summary` | `String` | 摘要描述 |
+| `clickable` | `Boolean` | 是否可点击查看弹窗详情 |
+
+#### PriceBreakdownVO（价格明细）
+
+```json
+{
+  "items": [
+    { "label": "成人", "unitPrice": 2300.00, "quantity": 2, "amount": 4600.00 },
+    { "label": "儿童", "unitPrice": 1800.00, "quantity": 1, "amount": 1800.00 }
+  ],
+  "subtotal": 6400.00,
+  "discounts": [
+    { "tag": "早鸟优惠", "description": "提前30天", "amount": -400.00 }
+  ],
+  "totalDiscount": -400.00,
+  "totalPayable": 6000.00
+}
+```
+
+#### RefundProgressVO（退款进度）
+
+```json
+{
+  "steps": [
+    { "title": "提交退款申请", "description": "用户发起退款", "status": "COMPLETED", "time": "2026-06-25T16:32:00" },
+    { "title": "商家审核中", "description": "客服正在审核您的退款申请", "status": "ACTIVE", "time": null },
+    { "title": "退款处理", "description": "原路退回您的微信账户", "status": "PENDING", "time": null },
+    { "title": "退款到账", "description": "预计1-3个工作日", "status": "PENDING", "time": null }
+  ],
+  "currentStep": 1,
+  "refundAmount": 1000.00,
+  "refundMethod": null,
+  "refundArrivalTime": null
+}
+```
+
+| step.status | 说明 |
+| --- | --- |
+| `COMPLETED` | 已完成 |
+| `ACTIVE` | 进行中（当前步骤） |
+| `PENDING` | 待处理 |
+
+#### TripProgressVO（行程进度）
+
+```json
+{
+  "currentDay": 2,
+  "totalDays": 6,
+  "progressPercent": 33,
+  "todayDestination": "莫日格勒河"
+}
+```
+
+---
+
+### 🆕 `GET` /internal/mp/order/{orderId}/tickets — 门票清单弹窗
+
+**返回** `MpTicketListVO`:
+
+```json
+{
+  "hint": "以下景点门票已包含在套餐内，无需另购",
+  "items": [
+    { "seq": 1, "scenicName": "莫日格勒河", "coverUrl": "...", "dayNumber": 2, "originalPrice": 80.00, "included": true }
+  ],
+  "totalValue": 340.00,
+  "footerText": "全部已含·无需再付"
+}
+```
+
+### 🆕 `GET` /internal/mp/order/{orderId}/hotels — 住宿清单弹窗
+
+**返回** `MpHotelListVO`:
+
+```json
+{
+  "hint": "5晚精选当地酒店",
+  "items": [
+    { "hotelName": "海拉尔铂尔曼大酒店", "coverUrl": "...", "dayNumber": 1, "hotelType": "5星", "roomType": "大床房" }
+  ],
+  "footerNote": "实际入住酒店以出行前确认为准"
+}
+```
+
+### 🆕 `GET` /internal/mp/order/{orderId}/meals — 餐饮清单弹窗
+
+**返回** `MpMealListVO`:
+
+```json
+{
+  "hint": "已含5早8正餐",
+  "specialMeals": [
+    { "dayNumber": 2, "mealName": "蒙古包午餐·手把肉宴", "mealType": "午餐", "description": "含奶茶/手把肉/烤包子" }
+  ],
+  "stats": { "breakfast": "5餐·酒店自助", "specialDinner": "3餐", "regularDinner": "5餐·当地特色餐厅" },
+  "footerNote": "对食物有过敏请提前告知领队"
+}
+```
+
+### 🆕 `GET` /internal/mp/order/{orderId}/vehicle — 用车详情弹窗
+
+**返回** `MpVehicleDetailVO`:
+
+```json
+{
+  "hint": "一家一车不拼团·全程同一辆车",
+  "vehicleName": "别克GL8·商务MPV",
+  "coverUrl": "...",
+  "description": "独立航空座椅·后排空调·USB充电",
+  "matchRule": "匹配规则：根据出行人数自动配车"
+}
+```
+
+### 🆕 `GET` /internal/mp/order/{orderId}/guide — 领队详情弹窗
+
+**返回** `MpGuideInfoVO`:
+
+```json
+{
+  "name": "巴图",
+  "avatarUrl": "...",
+  "role": "主领队",
+  "phone": "13800001111",
+  "remark": "10年呼伦贝尔带队经验"
+}
+```
+
+> ⚠️ 产品服务快照扩展完成前，`name`/`avatarUrl`/`phone`/`remark` 可能为空
+
+### 🆕 `GET` /internal/mp/order/{orderId}/photographer — 摄影详情弹窗
+
+**返回** `MpPhotographerInfoVO`:
+
+```json
+{
+  "name": "李维",
+  "avatarUrl": "...",
+  "role": "摄影师",
+  "phone": "13900002222",
+  "remark": "自然人像专长"
+}
+```
+
+> ⚠️ 同领队，产品服务快照扩展完成前字段可能为空
+
+---
+
+> ⚠️ **前端注意**:
+> 1. 详情接口返回值结构已变更，需按新的 `MpOrderDetailVO` 字段对接
+> 2. 6个弹窗接口按需调用（用户点击 serviceItems 某项时才调）
+> 3. `coverUrl`/`description`/`originalPrice` 等字段在产品服务快照扩展完成前可能为 `null` 或空字符串，请做空判断
+> 4. `refundProgress` 仅退款中/已取消且有退款时有值，其他状态为 `null`
+> 5. `tripProgress` 仅行程中状态有值，其他状态为 `null`
+> 6. `priceBreakdown` 仅新创建的订单有值（历史订单为 `null`），前端做空判断