From f4f767863df1e7f84a72baa153fbadb05215a1b6 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 21 Apr 2026 16:18:52 +0800 Subject: [PATCH] =?UTF-8?q?changelog(mp):=20=E5=BE=AE=E4=BF=A1=E5=B0=8F?= =?UTF-8?q?=E7=A8=8B=E5=BA=8F=20=C2=B7=20=E8=A1=8C=E7=A8=8B=E5=89=8D?= =?UTF-8?q?=E5=87=BA=E5=8F=91=E5=87=86=E5=A4=87=E9=A1=B5=20+=20=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E8=AF=A6=E6=83=85=E9=A1=B5=20=E8=81=9A=E5=90=88?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=20V1+V3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新接口 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) --- .../2026-04/2026-04-21_mp-dashboard-v1-v3.md | 330 ++++++++++++++++++ 1 file changed, 330 insertions(+) create mode 100644 changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md diff --git a/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md b/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md new file mode 100644 index 0000000..9b37573 --- /dev/null +++ b/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md @@ -0,0 +1,330 @@ +# 微信小程序 · 行程前出发准备页 + 订单详情页 聚合接口 + +**日期**: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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| orderHeader | OrderHeader | 订单头(倒计时卡片) | +| preTripChecklist | MpPreTripChecklistVO | 出发准备清单 | +| team | TeamVO | 带队团队 | +| tripOverview | `List` | 行程概览(每天一行) | +| 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` | 清单项,按 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` | 动作参数载荷,如 `{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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` +- 所有 VO 用 `@JsonIgnoreProperties(ignoreUnknown = true)`,后端字段扩展不会影响前端反序列化 +- 短 TTL 缓存:V1 30 秒 / V3 30 秒