From a770215188ff1daf6ec7e0facb70be6a48fcecd9 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 19 Jun 2026 17:50:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=A4=A7=E4=BA=A4=E9=80=9A?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E5=AF=B9=E9=BD=90v2=E2=80=94=E2=80=94list?= =?UTF-8?q?=E5=88=86=E7=BB=84=E7=BB=93=E6=9E=84=E5=8F=98=E6=9B=B4+?= =?UTF-8?q?=E8=A1=A5=E5=85=A8label/=E6=8E=A5=E9=80=81/=E7=B1=BB=E5=9E=8B/?= =?UTF-8?q?=E6=9D=A5=E6=BA=90=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 管理后台大交通(#4061/#4075/#4080):list返回改{arrivals,departures}分组(破坏性)， 补 directionLabel/modeLabel/transportTypeLabel/selfDrivePeriodLabel+createTime+creatorType， add/edit入参补pickup，嵌套出行人补travelerType。 --- ...对齐v2-结构调整+补全字段-修改接口-管理后台.md | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 changelogs-v2/2026-06/19_4058_大交通接口对齐v2-结构调整+补全字段-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/19_4058_大交通接口对齐v2-结构调整+补全字段-修改接口-管理后台.md b/changelogs-v2/2026-06/19_4058_大交通接口对齐v2-结构调整+补全字段-修改接口-管理后台.md new file mode 100644 index 0000000..972fe59 --- /dev/null +++ b/changelogs-v2/2026-06/19_4058_大交通接口对齐v2-结构调整+补全字段-修改接口-管理后台.md @@ -0,0 +1,206 @@ +# 【修改接口·管理后台】⚠️ 大交通接口对齐 v2：list 返回结构调整 + 补全 label/接送/类型/来源字段 + +> **PR**: #4061 + #4075 + #4080 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-19 +> ⚠️ **list 返回结构破坏性变更**（平铺 List → 按方向分组对象），前端必改；另有多处出参/入参字段新增。 + +## 1. 接口背景 + +订单详情大交通模块（`/v3/admin/order/{id}/transport-plan/*`）的 v3 版本相比 v2 缺失较多字段，本次统一对齐 v2：① list 返回改为按方向分组；② 补全各枚举中文 label；③ 补 createTime/updateTime；④ add/edit 入参补接送字段 pickup；⑤ 嵌套出行人补类型 travelerType；⑥ 出参补创建来源 creatorType。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | +|---|------|------|------|----------| +| 1 | 大交通列表 | GET | /v3/admin/order/{id}/transport-plan/list | **返回结构变更** + 出参补字段 | +| 2 | 大交通新增 | POST | /v3/admin/order/{id}/transport-plan/add | 入参补 pickup + 出参补字段 | +| 3 | 大交通编辑 | POST | /v3/admin/order/{id}/transport-plan/{planId}/edit | 入参补 pickup + 出参补字段 | +| 4 | 大交通软删 | POST | /v3/admin/order/{id}/transport-plan/{planId}/delete | 无变化（返回 Boolean）| +| 5 | 大交通批量替换 | POST | /v3/admin/order/{id}/transport-plan/batch | 入参/出参补字段 | + +## 3. 接口详情 + +均需 JWT（管理员）。list 只读幂等；add/edit/delete/batch 为写操作（add 带 3 秒幂等 + 30 秒分布式锁）。 + +## 4. 接口入参 + +### 4.1 新增/编辑入参 TransportPlanReqVO + +| 字段 | 类型 | 必填 | 变更 | 说明 | +|------|------|------|------|------| +| direction | String | 是 | 不变 | 方向，见 §6 | +| transportType | String | 是 | 不变 | 交通类型，见 §6 | +| transportNo | String | 条件 | 不变 | 车次/航班号（FLIGHT/TRAIN 必填）| +| carrier | String | 否 | 不变 | 承运 | +| departStation / arriveStation | String | 否 | 不变 | 出发/到达站点 | +| departTime / arriveTime | DateTime | 条件 | 不变 | 出发/到达时间（FLIGHT/TRAIN 必填）| +| selfDrivePeriod | String | 条件 | 不变 | 自驾时段（SELF_DRIVE 必填），见 §6 | +| selfDriveEta | DateTime | 否 | 不变 | 自驾预计到达 | +| travelerIds | List | 是 | 不变 | 关联出行人 ID | +| remark | String | 否 | 不变 | 备注 | +| **pickupRequired** | Boolean | 否 | **新增** | 是否需平台接送 | +| **pickupRemark** | String | 否 | **新增** | 接送备注（如「需在 T3 出口举牌接机」）| + +### 4.2 批量替换入参 TransportPlanBatchReqVO + +```jsonc +{ "plans": [ TransportPlanReqVO, ... ] } // 包装对象（plans 数组），元素同 §4.1 +``` + +## 5. 出参（响应） + +### 5.1 list 返回结构 ⚠️ 破坏性变更 + +| | 改前 | 改后（TransportPlanListRespVO）| +|---|---|---| +| 结构 | `data` 是平铺数组 `List` | `data` = `{ orderId, arrivals[], departures[] }`（按方向分组）| + +前端必须改：原来直接遍历 `data`，现在遍历 `data.arrivals`（到达批次）和 `data.departures`（返程批次）。 + +### 5.2 批次元素 TransportPlanVO（list/add/edit/batch 共用） + +| 字段 | 类型 | 变更 | 说明 | +|------|------|------|------| +| id | String | 不变 | 批次 ID | +| orderId | String | 不变 | 订单 ID | +| direction | String | 不变 | 方向码 | +| **directionLabel** | String | **新增** | 方向中文，见 §6 | +| mode | String | 不变 | 一起/多批码 | +| **modeLabel** | String | **新增** | 中文（结合方向：一起到达/多批到达/一起返程/多批返程）| +| transportType | String | 不变 | 交通类型码 | +| **transportTypeLabel** | String | **新增** | 交通类型中文 | +| transportNo / carrier / departStation / arriveStation / departTime / arriveTime | - | 不变 | - | +| selfDrivePeriod | String | 不变 | 自驾时段码 | +| **selfDrivePeriodLabel** | String | **新增** | 自驾时段中文（含时间范围）| +| selfDriveEta | DateTime | 不变 | - | +| pickupRequired | Boolean | 不变 | 是否接送 | +| pickupRemark | String | 不变 | 接送备注 | +| **creatorType** | String | **新增** | 创建来源码：USER/ADMIN | +| **creatorTypeName** | String | **新增** | 创建来源中文：用户自填/定制师代录 | +| remark | String | 不变 | 备注 | +| **createTime** | DateTime | **新增** | 创建时间 | +| **updateTime** | DateTime | **新增** | 更新时间 | +| travelers | Array | 出参元素补字段 | 关联出行人，见 §5.3 | + +### 5.3 travelers 嵌套元素 TravelerRef + +| 字段 | 类型 | 变更 | 说明 | +|------|------|------|------| +| id | String | 不变 | 出行人 ID | +| name | String | 不变 | 姓名 | +| **travelerType** | String | **新增** | 出行人类型码 | +| **travelerTypeName** | String | **新增** | 出行人类型中文（成人/儿童/小童/幼童）| + +### 5.4 batch 出参 TransportPlanBatchRespVO + +```jsonc +{ "deletedCount": 2, "createdCount": 3, "plans": [ TransportPlanVO, ... ] } +``` + +### 5.5 delete 出参 + +`Boolean`（true=删除成功）。 + +## 6. 枚举 / 数据字典 + +| 枚举 | 值 → 中文 | +|------|----------| +| direction（方向）| ARRIVAL=到达 / DEPARTURE=离开 | +| mode（一起/多批）| TOGETHER=一起 / SEPARATE=多批（modeLabel 结合方向拼成「一起到达」等）| +| transportType（交通类型）| FLIGHT=飞机 / TRAIN=火车 / SELF_DRIVE=自驾 | +| selfDrivePeriod（自驾时段）| MORNING=上午(06:00-12:00) / AFTERNOON=下午(12:00-18:00) / EVENING=晚上(18:00-24:00) | +| creatorType（创建来源）| USER=用户自填 / ADMIN=定制师代录 | +| travelerType（出行人类型）| ADULT=成人 / CHILD=儿童 / YOUNG_CHILD=小童 / BABY=幼童（走数据字典 traveler_type）| + +> label 类字段均后端派生，前端直接显示；未知值返回 null。 + +## 7. 错误码 + +写接口沿用原有：581123（direction 非法）/581125（transportType 非法）/581140（字段组合非法）/581141（travelerId 不属本单）/581142（出发晚于到达）/581143（同方向出行人重复）。本次无新增。 + +## 8. 示例 + +### 8.1 list 返回（新分组结构） + +```json +{ + "code": 200, + "data": { + "orderId": "2067426687242375169", + "arrivals": [ + { + "id": "...", "direction": "ARRIVAL", "directionLabel": "到达", + "mode": "TOGETHER", "modeLabel": "一起到达", + "transportType": "FLIGHT", "transportTypeLabel": "飞机", + "transportNo": "CA1234", "departTime": "2026-07-01 08:00:00", + "pickupRequired": true, "pickupRemark": "T3 出口举牌接机", + "creatorType": "ADMIN", "creatorTypeName": "定制师代录", + "createTime": "2026-06-19 10:00:00", + "travelers": [ + { "id": "...", "name": "张伟", "travelerType": "ADULT", "travelerTypeName": "成人" } + ] + } + ], + "departures": [] + }, + "success": true +} +``` + +### 8.2 add 入参（含接送） + +```json +{ + "direction": "ARRIVAL", "transportType": "FLIGHT", "transportNo": "CA1234", + "departTime": "2026-07-01 08:00:00", "arriveTime": "2026-07-01 11:00:00", + "travelerIds": [70123, 70124], + "pickupRequired": true, "pickupRemark": "T3 出口举牌接机" +} +``` + +### 8.3 batch 出参 + +```json +{ "code": 200, "data": { "deletedCount": 2, "createdCount": 3, "plans": [ ... ] }, "success": true } +``` + +## 9. 业务边界 + +- list 仅返回该订单的大交通批次，按 direction 分到 arrivals/departures。 +- 一个出行人可关联多个批次（去程+返程）；一个批次含多个出行人。 +- pickup 仅展示/记录，不触发其他业务。 +- FLIGHT/TRAIN 必填车次+时间；SELF_DRIVE 必填时段、禁带车次/时间。 + +## 10. 修改前后对比 + +| 项 | 改前 | 改后 | +|---|---|---| +| list 返回 | 平铺 List | { orderId, arrivals[], departures[] } | +| 各枚举 label | 无（只有英文码）| directionLabel/modeLabel/transportTypeLabel/selfDrivePeriodLabel | +| createTime/updateTime | 无 | 有 | +| add/edit 接送入参 | 无（pickup 设不进去）| pickupRequired/pickupRemark 可写 | +| 嵌套出行人 | 仅 id+name | + travelerType/travelerTypeName | +| 创建来源 | 无 | creatorType/creatorTypeName | + +## 11. 影响评估 / 回滚 + +- **破坏向后兼容**：**是**（list 返回结构从数组变对象）。前端读取 list 必须改为 `data.arrivals` / `data.departures`。其余为新增字段，非破坏。 +- **前端必须同步**：list 展示必改；其余字段按需对接。 +- **回滚**：revert PR #4080 + #4075 + #4061 并重新部署 hl-order-service-v3。 + +## 12. 注意事项 + +- list 前端改造点：遍历对象改为遍历 arrivals + departures 两个数组。 +- 各 label 字段前端直接显示，不要再自行映射英文码。 +- 接送信息（pickup）管理后台 add/edit 现在可填可改。 +- batch 出参是「删/建计数 + 结果列表」，非分组结构（与 list 不同）。 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#4058](https://git.1814.love:8443/wx/HL/issues/4058)（list 对齐）、[#4069](https://git.1814.love:8443/wx/HL/issues/4069)（pickup+travelerType）、[#4079](https://git.1814.love:8443/wx/HL/issues/4079)（creatorType） +- **PR**: [#4061](https://git.1814.love:8443/wx/HL/pulls/4061)、[#4075](https://git.1814.love:8443/wx/HL/pulls/4075)、[#4080](https://git.1814.love:8443/wx/HL/pulls/4080) + +### 13.2 联系人 + +- **后端负责人**: @yaosutu