# 【修改接口·管理后台】⚠️ 大交通接口对齐 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