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>
这个提交包含在：
yaosutu
父节点
7fe50232a1
当前提交
4bbebf273b
@ -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`），前端做空判断
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户