hl-api-changelog/changelogs-v2/2026-06/19_4058_大交通接口对齐v2-结构调整+补全字段-修改接口-管理后台.md

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

{ "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

{ "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 返回（新分组结构）

{
  "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 入参（含接送）

{
  "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 出参

{ "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（list 对齐）、#4069（pickup+travelerType）、#4079（creatorType）
• PR: #4061、#4075、#4080

13.2 联系人

• 后端负责人: @yaosutu