# 接口变更记录 — 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`），前端做空判断