比较提交
2 次代码提交
7fe50232a1
...
8dafe1b9cb
| 作者 | SHA1 | 提交日期 | |
|---|---|---|---|
| 8dafe1b9cb | |||
|
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`），前端做空判断
|
||||
@ -0,0 +1,119 @@
|
||||
# 到达信息接口新增 — 2026-04-20
|
||||
|
||||
> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** Issue #990 / PR #992 + Issue #998 / PR #1000
|
||||
> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) / hl-resource-service(8082)
|
||||
> **前端实际请求前缀**: `/mp/order/{orderId}/arrival`（5 接口）+ `/mp/transport/{flight|train}`（2 接口）
|
||||
|
||||
---
|
||||
|
||||
## 一、能力概述
|
||||
|
||||
订单出行前/后，用户可填写接送机信息。一个订单可分**多个批次**（每批一套交通方案 + 多个出行人），天然支持"一家分两批到达"。覆盖原型 8 个到达弹窗：
|
||||
|
||||
| 原型节点 | 功能 | 主要接口 |
|
||||
| --- | --- | --- |
|
||||
| 6pfmI | 填写到达·单批 | `POST /arrival` |
|
||||
| uq0UL | 分批到达列表 | `GET /arrival` + `POST /arrival/batch` |
|
||||
| K2s5H | 添加批次弹窗 | `POST /arrival` |
|
||||
| L4xYN | 已识别航班回显 | `GET /transport/flight` → `POST /arrival` |
|
||||
| oVMYy | 选择航班 | `GET /transport/flight` |
|
||||
| AQ21V | 空态 | `GET /transport/flight`（结果空） |
|
||||
| amizC | 手动填写 | `POST /arrival`（最小字段） |
|
||||
| Bf9jC | 添加人员 | （出行人接口，另 Issue） |
|
||||
|
||||
---
|
||||
|
||||
## 二、接口清单
|
||||
|
||||
鉴权：user token（登录态）
|
||||
|
||||
| 方法 | 路径 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| GET | `/mp/order/{orderId}/arrival` | 查全量批次（按方向分组） |
|
||||
| POST | `/mp/order/{orderId}/arrival` | 新增一个批次 |
|
||||
| POST | `/mp/order/{orderId}/arrival/batch` | 一次性提交多个批次（全量替换，空数组=清空） |
|
||||
| PUT | `/mp/order/{orderId}/arrival/plan/{planId}` | 修改批次（全量覆盖） |
|
||||
| DELETE | `/mp/order/{orderId}/arrival/plan/{planId}` | 删除批次 |
|
||||
| GET | `/mp/transport/flight?flightNo=&date=` | 按航班号+日期查航班动态 |
|
||||
| GET | `/mp/transport/train?trainNo=&date=` | 按车次号+日期查火车动态 |
|
||||
|
||||
---
|
||||
|
||||
## 三、请求体
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"direction": "ARRIVAL", // ARRIVAL 到达 / DEPARTURE 离开
|
||||
"transportType": "FLIGHT", // FLIGHT / TRAIN / SELF_DRIVE
|
||||
"transportNo": "CZ6255",
|
||||
"carrier": "南方航空",
|
||||
"departStation": "北京首都T3",
|
||||
"arriveStation": "海拉尔东山",
|
||||
"departTime": "2026-07-10 08:30:00",
|
||||
"arriveTime": "2026-07-10 11:00:00",
|
||||
"selfDrivePeriod": "AFTERNOON", // MORNING / AFTERNOON / EVENING
|
||||
"selfDriveEta": "2026-07-10 15:30:00",
|
||||
"remark": "带小孩,需婴儿座椅",
|
||||
"travelerIds": [10001, 10002]
|
||||
}
|
||||
```
|
||||
|
||||
**字段必填矩阵**（前端表单校验对齐）：
|
||||
|
||||
| 字段 | ARRIVAL + FLIGHT/TRAIN | DEPARTURE + FLIGHT/TRAIN | SELF_DRIVE |
|
||||
| --- | --- | --- | --- |
|
||||
| transportNo | ✅ | ✅ | — |
|
||||
| arriveStation | ✅ | 选 | — |
|
||||
| arriveTime | ✅ | 选 | — |
|
||||
| departStation | 选 | ✅ | — |
|
||||
| departTime | 选 | ✅ | — |
|
||||
| carrier | 选 | 选 | — |
|
||||
| selfDrivePeriod | — | — | ✅ |
|
||||
| travelerIds | ✅（≥1） | ✅（≥1） | ✅（≥1） |
|
||||
|
||||
原则：**司机接机只看到达、送机只看出发**。amizC 手动填只 4 字段就是这个设计。
|
||||
|
||||
---
|
||||
|
||||
## 四、响应体
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"orderId": "2046159434324783106", // String 防大数精度丢失
|
||||
"arrivals": [ // ARRIVAL 批次列表
|
||||
{
|
||||
"planId": "2046165477229555714",
|
||||
"direction": "ARRIVAL",
|
||||
"directionLabel": "到达",
|
||||
"transportType": "FLIGHT",
|
||||
"transportTypeLabel": "飞机",
|
||||
"transportNo": "CZ6255",
|
||||
"arriveStation": "海拉尔东山",
|
||||
"arriveTime": "2026-07-10 15:30:00",
|
||||
"creatorType": "USER",
|
||||
"travelers": [
|
||||
{"travelerId": "10001", "name": "张三", "travelerType": "ADULT"},
|
||||
{"travelerId": "10002", "name": "李四", "travelerType": "ADULT"}
|
||||
]
|
||||
}
|
||||
],
|
||||
"departures": [] // DEPARTURE 批次列表，同结构
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
约定：
|
||||
|
||||
- **所有 ID 是 String**（雪花 ID 防大数精度丢失）
|
||||
- 未传字段返回 `null`，列表空返回 `[]`
|
||||
- 时间统一 `yyyy-MM-dd HH:mm:ss`
|
||||
- 所有枚举字段配 `xxxLabel` 中文标签
|
||||
|
||||
---
|
||||
|
||||
## 五、关联
|
||||
|
||||
- Issue: [wx/HL#990](https://git.1814.love:8443/wx/HL/issues/990) / [wx/HL#998](https://git.1814.love:8443/wx/HL/issues/998)
|
||||
- PR: [wx/HL#992](https://git.1814.love:8443/wx/HL/pulls/992) / [wx/HL#1000](https://git.1814.love:8443/wx/HL/pulls/1000)（均已合并到 dev）
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户