From 4bbebf273b1824b6a90699a52e7a07f7fd02c8c5 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 17 Apr 2026 15:00:56 +0800 Subject: [PATCH] =?UTF-8?q?changelog:=20C=E7=AB=AF=E8=AE=A2=E5=8D=95?= =?UTF-8?q?=E8=AF=A6=E6=83=85=E9=A1=B5=E9=87=8D=E6=9E=84=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E5=8F=98=E6=9B=B4=EF=BC=88=E8=AF=A6=E6=83=85=E8=BF=94=E5=9B=9E?= =?UTF-8?q?=E5=80=BC=E5=8F=98=E6=9B=B4+6=E4=B8=AA=E5=BC=B9=E7=AA=97?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 详情接口返回值从OrderDetailVO改为MpOrderDetailVO， 新增serviceItems/priceBreakdown/refundProgress/tripProgress等字段， 新增6个弹窗接口(tickets/hotels/meals/vehicle/guide/photographer)。 Co-Authored-By: Claude Opus 4.6 (1M context) --- ...04-17_order-v2_mp-order-detail-refactor.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 changelogs/2026-04/2026-04-17_order-v2_mp-order-detail-refactor.md diff --git 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 new file mode 100644 index 0000000..1966484 --- /dev/null +++ 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` | 服务包含摘要列表，见下方结构 | +| 🆕 `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`），前端做空判断