hl-api-changelog/changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md

接口变更记录 — 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（服务包含摘要项）

{
  "type": "HOTEL",
  "title": "住宿",
  "summary": "5晚精选当地酒店",
  "clickable": true
}

字段	类型	说明
type	String	HOTEL/MEAL/VEHICLE/GUIDE/PHOTOGRAPHER/TICKET/INSURANCE
title	String	服务标题
summary	String	摘要描述
clickable	Boolean	是否可点击查看弹窗详情

PriceBreakdownVO（价格明细）

{
  "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（退款进度）

{
  "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（行程进度）

{
  "currentDay": 2,
  "totalDays": 6,
  "progressPercent": 33,
  "todayDestination": "莫日格勒河"
}

---

🆕 GET /internal/mp/order/{orderId}/tickets — 门票清单弹窗

返回 MpTicketListVO:

{
  "hint": "以下景点门票已包含在套餐内，无需另购",
  "items": [
    { "seq": 1, "scenicName": "莫日格勒河", "coverUrl": "...", "dayNumber": 2, "originalPrice": 80.00, "included": true }
  ],
  "totalValue": 340.00,
  "footerText": "全部已含·无需再付"
}

🆕 GET /internal/mp/order/{orderId}/hotels — 住宿清单弹窗

返回 MpHotelListVO:

{
  "hint": "5晚精选当地酒店",
  "items": [
    { "hotelName": "海拉尔铂尔曼大酒店", "coverUrl": "...", "dayNumber": 1, "hotelType": "5星", "roomType": "大床房" }
  ],
  "footerNote": "实际入住酒店以出行前确认为准"
}

🆕 GET /internal/mp/order/{orderId}/meals — 餐饮清单弹窗

返回 MpMealListVO:

{
  "hint": "已含5早8正餐",
  "specialMeals": [
    { "dayNumber": 2, "mealName": "蒙古包午餐·手把肉宴", "mealType": "午餐", "description": "含奶茶/手把肉/烤包子" }
  ],
  "stats": { "breakfast": "5餐·酒店自助", "specialDinner": "3餐", "regularDinner": "5餐·当地特色餐厅" },
  "footerNote": "对食物有过敏请提前告知领队"
}

🆕 GET /internal/mp/order/{orderId}/vehicle — 用车详情弹窗

返回 MpVehicleDetailVO:

{
  "hint": "一家一车不拼团·全程同一辆车",
  "vehicleName": "别克GL8·商务MPV",
  "coverUrl": "...",
  "description": "独立航空座椅·后排空调·USB充电",
  "matchRule": "匹配规则：根据出行人数自动配车"
}

🆕 GET /internal/mp/order/{orderId}/guide — 领队详情弹窗

返回 MpGuideInfoVO:

{
  "name": "巴图",
  "avatarUrl": "...",
  "role": "主领队",
  "phone": "13800001111",
  "remark": "10年呼伦贝尔带队经验"
}

⚠️ 产品服务快照扩展完成前，name/avatarUrl/phone/remark 可能为空

🆕 GET /internal/mp/order/{orderId}/photographer — 摄影详情弹窗

返回 MpPhotographerInfoVO:

{
  "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），前端做空判断