yaosutu f4f767863d changelog(mp): 微信小程序 · 行程前出发准备页 + 订单详情页聚合接口 V1+V3

- 新接口 GET /mp/trip/{orderId}/pre-trip-dashboard (V1)
- 新接口 GET /mp/order/{orderId}/dashboard (V3)
- PR #1074/#1087/#1090/#1078/#1096 合集交付

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-21 16:19:13 +08:00

11 KiB

原始文件 Blame 文件历史

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

日期: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	当天标题

响应示例

{
  "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。

响应示例

已确认订单(无退款):

{
  "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
}

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

{
  "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 秒

11 KiB 原始文件 Blame 文件历史

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

概述

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

接口

入参

出参 Result<MpPreTripDashboardVO>

响应示例

边界行为

V3. 订单详情页聚合

接口

入参

出参 Result<MpOrderDashboardVO>

响应示例

边界行为

单测

规范注记

11 KiB

原始文件 Blame 文件历史

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

出参 `Result<MpPreTripDashboardVO>`

出参 `Result<MpOrderDashboardVO>`