docs(changelog): 大交通接口对齐v2——list分组结构变更+补全label/接送/类型/来源字段

管理后台大交通(#4061/#4075/#4080):list返回改{arrivals,departures}分组(破坏性)，补 directionLabel/modeLabel/transportTypeLabel/selfDrivePeriodLabel+createTime+creatorType， add/edit入参补pickup，嵌套出行人补travelerType。
2026-06-19 17:50:07 +08:00 · 2026-06-19 17:50:07 +08:00 · a770215188
--- a/changelogs-v2/2026-06/19_4058_大交通接口对齐v2-结构调整+补全字段-修改接口-管理后台.md
+++ 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<Long> | 是 | 不变 | 关联出行人 ID |
+| remark | String | 否 | 不变 | 备注 |
+| **pickupRequired** | Boolean | 否 | **新增** | 是否需平台接送 |
+| **pickupRemark** | String | 否 | **新增** | 接送备注（如「需在 T3 出口举牌接机」）|
+
+### 4.2 批量替换入参 TransportPlanBatchReqVO
+
+```jsonc
+{ "plans": [ TransportPlanReqVO, ... ] }   // 包装对象（plans 数组），元素同 §4.1
+```
+
+## 5. 出参（响应）
+
+### 5.1 list 返回结构 ⚠️ 破坏性变更
+
+| | 改前 | 改后（TransportPlanListRespVO）|
+|---|---|---|
+| 结构 | `data` 是平铺数组 `List<TransportPlanVO>` | `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<TransportPlanVO> | { 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