From b5941e4f34e9529d927965b1d1c52c347a1ded3d Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 21 Apr 2026 16:30:50 +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=AE=A2=E5=8D=95=E5=88=B0?= =?UTF-8?q?=E8=BE=BE/=E7=A6=BB=E5=BC=80=E4=BF=A1=E6=81=AF=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3(5=20=E4=B8=AA=20CRUD)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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} PR #1000 (Closes #998) Co-Authored-By: Claude Opus 4.7 (1M context) --- .../2026-04/2026-04-21_mp-order-arrival.md | 276 ++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 changelogs/2026-04/2026-04-21_mp-order-arrival.md diff --git a/changelogs/2026-04/2026-04-21_mp-order-arrival.md b/changelogs/2026-04/2026-04-21_mp-order-arrival.md new file mode 100644 index 0000000..909c6fa --- /dev/null +++ b/changelogs/2026-04/2026-04-21_mp-order-arrival.md @@ -0,0 +1,276 @@ +# 微信小程序 · 订单到达/离开信息接口(5 个 CRUD) + +**日期**:2026-04-21 +**影响**:**微信小程序** 行程前·出发准备页(原型 `ew2Kk`)、订单详情到达信息弹窗(原型 `6pfmI / uq0UL / K2s5H / L4xYN / oVMYy / AQ21V / amizC`) +**PR**:#1000(Closes #998) + +--- + +## 概述 + +订单"分批到达/离开"模型,用户在行程前填写: + +- **到达(ARRIVAL)**:从住所抵达目的地 +- **离开(DEPARTURE)**:从目的地返程 + +每个订单可有多批(带小孩/家人分几趟飞),每批一条 `MpArrivalPlanRespVO` 记录,包含交通方式、班次、站点、时间、本批涉及的出行人。 + +共 **5 个 CRUD** 接口:查全量、新增、全量替换、修改、删除。 + +--- + +## 1. 查全量批次 + +``` +GET /mp/order/{orderId}/arrival +``` + +**鉴权**:Bearer token。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | + +### 出参 `Result` + +| 字段 | 类型 | 说明 | +|---|---|---| +| orderId | Long | 订单ID | +| arrivals | `List` | 到达批次列表 | +| departures | `List` | 离开批次列表 | + +`MpArrivalPlanRespVO` 字段见第 2 节出参。 + +### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "orderId": 700001, + "arrivals": [ + { + "planId": 800001, + "orderId": 700001, + "direction": "ARRIVAL", + "directionLabel": "到达", + "transportType": "FLIGHT", + "transportTypeLabel": "飞机", + "transportNo": "CZ6255", + "carrier": "南方航空", + "departStation": "北京首都T3", + "arriveStation": "海拉尔东山", + "departTime": "2026-07-10 08:30:00", + "arriveTime": "2026-07-10 11:00:00", + "selfDrivePeriod": null, + "selfDrivePeriodLabel": null, + "selfDriveEta": null, + "remark": "带小孩,需婴儿座椅", + "creatorType": "USER", + "createTime": "2026-07-01 10:00:00", + "travelers": [ + {"travelerId":10001,"name":"张三","travelerType":"ADULT"}, + {"travelerId":10002,"name":"张小三","travelerType":"CHILD"} + ] + } + ], + "departures": [] + }, + "success": true +} +``` + +--- + +## 2. 新增批次 + +``` +POST /mp/order/{orderId}/arrival +``` + +**鉴权**:Bearer token。 +**创建者类型**:`creatorType=USER`(用户自填)。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | + +Body `MpArrivalPlanSaveReqVO`: + +| 字段 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---| +| direction | String | ✅ | - | `ARRIVAL` / `DEPARTURE`(字典 `transport_direction`) | +| transportType | String | ✅ | - | `FLIGHT` / `TRAIN` / `SELF_DRIVE`(字典 `transport_type` 子集) | +| transportNo | String | FLIGHT/TRAIN 必填 | ≤32 | 航班号/车次号,如 `CZ6255` | +| carrier | String | 否 | ≤64 | 航司/铁路公司,如 `南方航空` | +| departStation | String | 否 | ≤64 | 出发站/机场 | +| arriveStation | String | 否 | ≤64 | 到达站/机场 | +| departTime | LocalDateTime | 否 | - | 出发时间 | +| arriveTime | LocalDateTime | 否 | - | 到达时间 | +| selfDrivePeriod | String | SELF_DRIVE 必填 | - | `MORNING` / `AFTERNOON` / `EVENING`(字典 `self_drive_period`) | +| selfDriveEta | LocalDateTime | 否 | - | 自驾预计到达精确时间 | +| remark | String | 否 | ≤255 | 用户备注 | +| travelerIds | `List` | ✅ 非空 | - | 本批次涉及的出行人 ID 列表;必须属于本订单 | + +### 出参 `Result` + +| 字段 | 类型 | 说明 | +|---|---|---| +| planId | Long | 批次ID | +| orderId | Long | 订单ID | +| direction | String | 方向 | +| directionLabel | String | 方向中文标签 | +| transportType | String | 交通方式 | +| transportTypeLabel | String | 交通方式中文标签 | +| transportNo | String | 航班号/车次号 | +| carrier | String | 航司/铁路公司 | +| departStation | String | 出发站 | +| arriveStation | String | 到达站 | +| departTime | LocalDateTime | 出发时间 | +| arriveTime | LocalDateTime | 到达时间 | +| selfDrivePeriod | String | 自驾时段 | +| selfDrivePeriodLabel | String | 自驾时段中文标签,如 `下午(12:00-18:00)` | +| selfDriveEta | LocalDateTime | 自驾预计到达 | +| remark | String | 备注 | +| creatorType | String | `USER`(用户自填)/`ADMIN`(定制师代录)(字典 `creator_type`) | +| createTime | LocalDateTime | 创建时间 | +| travelers | `List` | 本批次涉及的出行人(脱敏) | + +**`MpArrivalPlanTravelerSimpleVO`**: +| 字段 | 类型 | 说明 | +|---|---|---| +| travelerId | Long | 出行人ID | +| name | String | 姓名 | +| travelerType | String | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY`(字典 `traveler_type`) | + +### 请求示例 + +```json +{ + "direction": "ARRIVAL", + "transportType": "FLIGHT", + "transportNo": "CZ6255", + "carrier": "南方航空", + "departStation": "北京首都T3", + "arriveStation": "海拉尔东山", + "departTime": "2026-07-10 08:30:00", + "arriveTime": "2026-07-10 11:00:00", + "remark": "带小孩,需婴儿座椅", + "travelerIds": [10001, 10002] +} +``` + +--- + +## 3. 全量替换 + +``` +POST /mp/order/{orderId}/arrival/batch +``` + +**鉴权**:Bearer token。 + +先软删当前所有批次,再按请求体批量创建。空数组 `[]` = 清空订单的所有到达/离开批次。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | + +Body:`List`(每项结构同第 2 节)。 + +### 出参 + +`Result` — 替换完成后的全量数据,结构同第 1 节。 + +--- + +## 4. 修改批次 + +``` +PUT /mp/order/{orderId}/arrival/plan/{planId} +``` + +**鉴权**:Bearer token。 + +**覆盖语义**:按字段全量覆盖,包括 `travelerIds`(替换旧关联)。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | +| planId | Path | Long | ✅ | + +Body:`MpArrivalPlanSaveReqVO`(同第 2 节)。 + +### 出参 + +`Result` — 修改后的批次,结构同第 2 节。 + +--- + +## 5. 删除批次 + +``` +DELETE /mp/order/{orderId}/arrival/plan/{planId} +``` + +**鉴权**:Bearer token。 + +**级联**:软删关联的出行人绑定行。 + +### 入参 + +| 参数 | 位置 | 类型 | 必填 | +|---|---|---|---| +| orderId | Path | Long | ✅ | +| planId | Path | Long | ✅ | + +### 出参 + +`Result`: + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +--- + +## 边界行为 + +- **字段校验**:`transportType=FLIGHT/TRAIN` 时 `transportNo` 必填;`transportType=SELF_DRIVE` 时 `selfDrivePeriod` 必填 +- **出行人校验**:`travelerIds` 中的 ID 必须属于本订单,否则 400 +- **订单不存在/无权限**:500,`message` 含 `orderId` +- 用户填的批次 `creatorType=USER`;定制师后台代录的 `creatorType=ADMIN` + +--- + +## 辅助接口(填写表单时用,来自同一批交付) + +``` +GET /mp/transport/flight?flightNo=CZ6255&date=2026-07-10 按航班号查航班动态 +GET /mp/transport/train?trainNo=G71&date=2026-07-10 按车次号查火车 +``` + +出参 `Result>` / `Result>`,字段:`flightNo/trainNo / airline / departAirport / arriveAirport / scheduledDepartTime / scheduledArriveTime / flightStatus / remark`。 + +--- + +## 字典依赖 + +| 字典类型 | 说明 | +|---|---| +| `transport_direction` | `ARRIVAL` / `DEPARTURE` | +| `transport_type` | `FLIGHT` / `TRAIN` / `SELF_DRIVE`(本场景只用这 3 个子集) | +| `self_drive_period` | `MORNING` / `AFTERNOON` / `EVENING` | +| `creator_type` | `USER` / `ADMIN` | +| `traveler_type` | `ADULT` / `CHILD` / `YOUNG_CHILD` / `BABY` | + +所有 `xxxLabel` 字段均由 BFF 透传自 order-v2,已经是中文展示值。