hl-api-changelog/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md

# 微信小程序 · 行程前出发准备页 + 订单详情页 聚合接口

**日期**:2026-04-21
**影响**:**微信小程序** 行程 Tab(行程前态)与订单详情页(5 态)
**PR**:#1074 · #1087 · #1090(V1) / #1078 · #1096(V3)
**Issue**:#1073 · #1086 · #1089(V1) / #1076 · #1095(V3)

---

## 概述

新增两个页面级聚合接口,一次拉全该页所需全部数据,替代前端分别调用 3~6 个细粒度接口的方案:

| 接口 | 对应页面 |
|---|---|
| V1 `GET /mp/trip/{orderId}/pre-trip-dashboard` | 行程前·出发准备(订单已确认、未出发) |
| V3 `GET /mp/order/{orderId}/dashboard` | 订单详情页(待付款/行程中/已完成/已取消/退款中 5 态) |

> V2 `GET /mp/trip/today-dashboard`(行程中页)另外交付,本文档只覆盖 V1 + V3。

---

## V1. 行程前出发准备页聚合

### 接口

```
GET /mp/trip/{orderId}/pre-trip-dashboard
```

**鉴权**:需要 Bearer token(登录小程序用户)。

### 入参

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| orderId | Path | Long | ✅ | 订单 ID |

### 出参 `Result<MpPreTripDashboardVO>`

| 字段 | 类型 | 说明 |
|---|---|---|
| orderHeader | OrderHeader | 订单头(倒计时卡片) |
| preTripChecklist | MpPreTripChecklistVO | 出发准备清单 |
| team | TeamVO | 带队团队 |
| tripOverview | `List<DayItem>` | 行程概览(每天一行) |
| customerServicePhone | String | 客服电话,如 `0470-8871922` |

**`OrderHeader`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| orderId | Long | 订单ID |
| orderNo | String | 订单编号 |
| productName | String | 产品名称 |
| productSubtitle | String | 产品副标题 |
| tierName | String | 档位名称,如 `舒适档`(未选档为 null) |
| tierDescription | String | 档位描述 |
| productCoverUrl | String | 产品封面 URL |
| departureDate | LocalDate | 出发日期 |
| tripDays | Integer | 行程天数 |
| tripNights | Integer | 行程晚数 |
| dateRange | String | 日期范围文字,如 `2026年7月1日 — 7月6日` |
| daysToDeparture | Integer | 距出发天数 |
| totalPeople | Integer | 总人数 |
| adultCount | Integer | 成人数 |
| childCount | Integer | 儿童数 |
| tripPhase | String | `BEFORE_START` / `IN_PROGRESS` / `ENDED` |

**`MpPreTripChecklistVO`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| totalCount | Integer | 总项数 |
| completedCount | Integer | 已完成项数 |
| items | `List<MpChecklistItemVO>` | 清单项,按 WARNING > PENDING > DONE 排序 |

**`MpChecklistItemVO`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| key | String | `DEPOSIT_PAID` / `TRAVELER_INFO` / `ARRIVAL_INFO` / `CONTRACT_SIGN` / `INSURANCE` / `CHECKLIST_CONFIRMED` |
| title | String | 标题 |
| subtitle | String | 副标题说明 |
| status | String | `DONE` / `PENDING` / `WARNING` |
| statusLabel | String | 状态中文标签 |
| actionType | String | `NAVIGATE` / `CONFIRM` / `CONTACT_CS`;null 表示纯展示 |
| actionPayload | `Map<String, Object>` | 动作参数载荷,如 `{pageKey: "arrival_form", orderId: "..."}` |

**`TeamVO`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| leader | MpGuideInfoVO | 领队(未分配为 null) |
| photographer | MpPhotographerInfoVO | 摄影师(未分配为 null) |
| driver | MpVehicleDetailVO | 司机(原型暂不展示,保持 null) |

`MpGuideInfoVO` / `MpPhotographerInfoVO` 字段:`staffId / name / avatarUrl / role / roleLabel / phone(脱敏) / remark / assigned`

**`DayItem`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| dayNumber | Integer | 第几天 |
| date | LocalDate | 当天日期 |
| title | String | 当天标题 |

### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "orderHeader": {
      "orderId": 20439,
      "orderNo": "HL20260701123",
      "productName": "草原环线",
      "productSubtitle": "6天5晚舒适套餐",
      "tierName": "舒适档",
      "tierDescription": "升级双早+SPA",
      "productCoverUrl": "https://cdn.1814.love/cover.png",
      "departureDate": "2026-07-01",
      "tripDays": 6,
      "tripNights": 5,
      "dateRange": "2026年7月1日 — 7月6日",
      "daysToDeparture": 12,
      "totalPeople": 2,
      "adultCount": 2,
      "childCount": 0,
      "tripPhase": "BEFORE_START"
    },
    "preTripChecklist": {
      "totalCount": 6,
      "completedCount": 3,
      "items": [
        {"key":"DEPOSIT_PAID","title":"订金已支付","status":"DONE","statusLabel":"已完成"},
        {"key":"ARRIVAL_INFO","title":"填写接送机信息","subtitle":"司机将根据此信息接送","status":"PENDING","statusLabel":"待处理","actionType":"NAVIGATE","actionPayload":{"pageKey":"arrival_form","orderId":"20439"}}
      ]
    },
    "team": {
      "leader": {"name":"巴图","roleLabel":"领队","phone":"138****5678","remark":"10年呼伦贝尔带队经验","assigned":true},
      "photographer": {"name":"李维","roleLabel":"摄影师","phone":"139****1234","assigned":true},
      "driver": null
    },
    "tripOverview": [
      {"dayNumber":1,"date":"2026-07-01","title":"海拉尔集合·接机入住"},
      {"dayNumber":2,"date":"2026-07-02","title":"呼籁营地 → 莫日格勒河 → 额尔古纳"}
    ],
    "customerServicePhone": "0470-8871922"
  },
  "success": true
}
```

### 边界行为

- `team.leader / photographer / driver` 任意一个字段可能为 null(未分配)
- `orderHeader.tierName / tierDescription` 未选档或下单时未绑定档位则为 null
- 订单不存在或无权限访问:HTTP 500,`message` 含 `orderId` 和错误原因
- `guide / photographer` 底层接口失败:对应字段置 null,主数据仍返回(降级)

---

## V3. 订单详情页聚合

### 接口

```
GET /mp/order/{orderId}/dashboard
```

**鉴权**:需要 Bearer token。

### 入参

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| orderId | Path | Long | ✅ | 订单 ID |

### 出参 `Result<MpOrderDashboardVO>`

| 字段 | 类型 | 说明 |
|---|---|---|
| order | MpOrderDetailVO | 订单主体,字段同 `GET /mp/order/{orderId}` 返回值 |
| files | FilesVO | 重要文件三合一 |
| insurance | MpInsuranceDetailVO | 保险详情(未投保为 null) |
| refund | RefundVO | 退款模块(非退款状态为 null) |

`order` 为完整的订单详情,常用字段:`orderId / orderNo / status / statusLabel / productName / productSubtitle / tierSeq / tierName / tierDescription / productCoverUrl / tripDays / totalPrice / paidAmount / depositAmount / paymentType / travelers / supplies / equipmentAdvice` 等。完整字段以 `GET /mp/order/{orderId}` 为准。

**`FilesVO`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| contract | MpContractSummaryVO | 合同(无合同为 null) |
| invoice | MpInvoiceSummaryVO | 发票(未开票为 null) |
| insurancePolicyPdfUrl | String | 保单 PDF 下载路径,如 `/mp/insurance/policy-pdf/20439` |

**`MpContractSummaryVO`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| contractId | Long | 合同ID |
| contractNo | String | 合同编号 |
| status | String | `PREPARING` / `UNSIGNED` / `SIGNED` / `VOID` 等 |
| statusLabel | String | 状态中文 |
| contractType | String | `TOUR` / `INSURANCE` |
| signedAt | LocalDateTime | 签署时间 |
| downloadUrl | String | 合同 PDF 下载链接 |

**`MpInvoiceSummaryVO`**:
| 字段 | 类型 | 说明 |
|---|---|---|
| invoiceId | Long | 发票ID |
| invoiceNo | String | 发票号 |
| status | String | `PENDING` / `ISSUED` / `FAILED` 等 |
| statusLabel | String | 状态中文 |
| titleType | String | `PERSONAL` / `COMPANY` |
| invoiceTitle | String | 发票抬头 |
| taxNumber | String | 税号 |
| amount | BigDecimal | 金额 |
| email | String | 接收邮箱 |
| issuedAt | LocalDateTime | 开票时间 |
| pdfUrl | String | 电子发票 PDF URL |

**`MpInsuranceDetailVO`**:字段见 `GET /mp/order/{orderId}/insurance`。含 `schemeId / schemeName / description / isOverseas / totalDays / notice / segments[] / policies[]`。

**`RefundVO`**(只在订单状态为 `CANCELLED` / `REFUNDING` / `REFUNDED` / `REFUND_REJECTED` / `APPEALING` 时有值,否则整个字段为 null):

| 字段 | 类型 | 说明 |
|---|---|---|
| detail | MpRefundDetailVO | 退款申请详情 |
| progress | MpRefundProgressVO | 退款进度时间线 |

`MpRefundDetailVO` 字段见 `GET /mp/order/{orderId}/refund-detail`。
`MpRefundProgressVO` 字段:`steps[] / currentStep / refundAmount / refundMethod / refundArrivalTime`。

### 响应示例

**已确认订单(无退款)**:

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "order": {
      "orderId": 20439,
      "status": "CONFIRMED",
      "statusLabel": "已确认",
      "productName": "草原环线",
      "productSubtitle": "6天5晚舒适套餐",
      "tierName": "舒适档",
      "tierDescription": "升级双早+SPA",
      "totalPrice": 5800.00,
      "travelers": [],
      "supplies": []
    },
    "files": {
      "contract": {"contractId":8001,"contractNo":"HL-2026-070128","status":"SIGNED","statusLabel":"已签署","contractType":"TOUR","downloadUrl":"https://cdn.1814.love/contract-8001.pdf"},
      "invoice": null,
      "insurancePolicyPdfUrl": "/mp/insurance/policy-pdf/20439"
    },
    "insurance": {
      "schemeName": "旅行意外险",
      "policies": [{"policyNo":"PA20260628****5512","status":"INSURED","statusLabel":"已承保"}]
    },
    "refund": null
  },
  "success": true
}
```

**已取消订单(含退款进度)**:

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "order": {"orderId":20439,"status":"CANCELLED","statusLabel":"已取消"},
    "files": {
      "contract": null,
      "invoice": null,
      "insurancePolicyPdfUrl": "/mp/insurance/policy-pdf/20439"
    },
    "insurance": null,
    "refund": {
      "detail": {
        "applicationId": 6001,
        "status": "REFUNDING",
        "statusLabel": "退款中",
        "actualAmount": 1000.00,
        "refundType": "DEPOSIT",
        "refundTypeLabel": "订金退款"
      },
      "progress": {
        "currentStep": 2,
        "refundAmount": 1000.00,
        "refundMethod": "原路返回·微信",
        "steps": [
          {"title":"提交退款申请","status":"COMPLETED","time":"2026-04-15 10:30:00"},
          {"title":"商家审核","status":"ACTIVE","time":"2026-04-16 09:10:00"},
          {"title":"退款处理","status":"PENDING","time":null},
          {"title":"退款到账","status":"PENDING","time":null}
        ]
      }
    }
  },
  "success": true
}
```

### 边界行为

- 订单不存在或无权限:HTTP 500,`message` 含 `orderId`
- `contract / invoice / insurance` 底层接口失败:对应字段置 null,不影响订单主体
- 非退款状态订单:`refund = null`(不调用退款相关底层接口)
- 退款状态订单两个退款接口都返 null 时:`refund = null`(不返回 `{detail:null, progress:null}` 的壳子)

---

## 单测

| 测试类 | 覆盖用例 | 结果 |
|---|---|---|
| `PreTripDashboardAggregationServiceTest` | 正常路径 + guide 降级 + photographer 降级 + trip 错误码 + trip 空数据 + itinerarySummary 缺失 | 6/6 通过 |
| `OrderDashboardAggregationServiceTest` | 非退款状态 + 已取消状态(refund 填充) + 退款中但退款接口返 null + contract 降级 + invoice errorCode + order 错误码 / 空数据 / 异常 | 8/8 通过 |

---

## 规范注记

- 返回字段除 `MpChecklistItemVO.actionPayload`(任意 key 跳转载荷)外,**全部强类型 VO**,无 `Map<String, Object>`
- 所有 VO 用 `@JsonIgnoreProperties(ignoreUnknown = true)`,后端字段扩展不会影响前端反序列化
- 短 TTL 缓存:V1 30 秒 / V3 30 秒