# API 变更通知 **更新时间**: 2026-05-08 15:00 **PR**: #1878 feat(order-v2): 到达/返程信息支持区分一起/多批两种模式 + #1887 修正接口描述 --- ## 破坏性变更：POST /mp/order/{orderId}/arrival 语义彻底变更 ### 变了什么（前端视角） **单数接口从「追加一条」变成「该方向全量替换 1 条」。** | 行为 | 旧逻辑（PR 前） | 新逻辑（PR 后） | |------|----------------|----------------| | 连续调 2 次 | 产生 2 条批次（追加） | 第 2 次会把第 1 次清掉，只保留最新 1 条 | | 想分批到达 | 多次调单数接口 | 必须改用 /arrival/batch（提交多元素数组） | | 已有批次被覆盖范围 | 无此逻辑 | 只清同一 direction 的旧批次，不影响另一方向 | 如果小程序之前通过多次调 POST /arrival 实现「分批到达」，现在必须改为调 POST /arrival/batch。 --- ## Bug 修复：POST /mp/order/{orderId}/arrival/batch 不再误删另一方向 | 行为 | 旧行为（有 bug） | 新行为（已修复） | |------|----------------|----------------| | 提交返程多批 | 把已填的到达批次也一起删掉 | 只删 direction=DEPARTURE 的旧批次，ARRIVAL 不受影响 | | 提交到达多批 | 把已填的返程批次也一起删掉 | 只删 direction=ARRIVAL 的旧批次，DEPARTURE 不受影响 | 如果前端之前因为这个 bug 做了「先查再保」之类的 workaround，可以清理掉。 --- ## 新增：GET 接口返回 mode + modeLabel 字段 GET /mp/order/{orderId}/arrival 返回的每个批次对象新增 2 个字段： | 字段 | 类型 | 说明 | |------|------|------| | mode | String | 模式枚举：TOGETHER 或 SEPARATE | | modeLabel | String | 按方向拼出的中文标签（见下表） | modeLabel 的 4 种值： | direction | mode | modeLabel | |-----------|------|----------| | ARRIVAL | TOGETHER | 一起到达 | | ARRIVAL | SEPARATE | 多批到达 | | DEPARTURE | TOGETHER | 一起返程 | | DEPARTURE | SEPARATE | 多批返程 | 前端可以用 arrivals[0]?.mode（或 departures[0]?.mode）来判断该方向当前 tab 模式，决定进入页面时默认选中哪个选项卡。 --- ## 新增错误码：580010 BATCH_DIRECTION_MIXED POST /mp/order/{orderId}/arrival/batch 增加新校验：请求数组里所有元素的 direction 必须一致（不能同一次 batch 里混提 ARRIVAL 和 DEPARTURE）。 | 错误码 | message | |--------|--------| | 580010 | 批量提交的批次必须同一方向（到达或返程） | 响应示例（错误）： ```json { "code": 580010, "message": "批量提交的批次必须同一方向（到达或返程）", "data": null } ``` --- ## 涉及的接口汇总 | # | 接口 | 方法 | 路径 | 变更类型 | 说明 | |---|------|------|------|----------|------| | 1 | 查询订单全量批次 | GET | /mp/order/{orderId}/arrival | 字段新增 | 每个批次对象新增 mode + modeLabel | | 2 | 新增交通批次 | POST | /mp/order/{orderId}/arrival | 语义破坏性变更 | 从追加改为该方向全量替换 1 条 | | 3 | 全量替换批次(多批) | POST | /mp/order/{orderId}/arrival/batch | Bug 修复 + 新增校验 | 修方向隔离 bug；新增 direction 混用校验 | | 4 | 修改交通批次 | PUT | /mp/order/{orderId}/arrival/plan/{planId} | 无变化 | - | | 5 | 删除交通批次 | DELETE | /mp/order/{orderId}/arrival/plan/{planId} | 无变化 | - | --- ## 接口详细定义 ### 1. GET /mp/order/{orderId}/arrival — 查询订单全量到达/离开批次 - **使用场景**：进入订单详情/行程页时查询，用返回的 arrivals[0]?.mode 和 departures[0]?.mode 决定各方向 tab 默认状态 - **路径参数**： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | orderId | Long | 是 | 订单 ID | - **响应字段（data 对象）**： | 字段 | 类型 | 说明 | |------|------|------| | orderId | Long | 订单 ID | | arrivals | Array | direction=ARRIVAL 的批次列表 | | departures | Array | direction=DEPARTURE 的批次列表 | arrivals/departures 内每个批次对象字段（MpArrivalPlanRespVO）： | 字段 | 类型 | 说明 | |------|------|------| | planId | Long | 批次 ID | | orderId | Long | 订单 ID | | direction | String | ARRIVAL/DEPARTURE | | directionLabel | String | 到达/离开 | | mode | String | **[本次新增]** TOGETHER/SEPARATE | | modeLabel | String | **[本次新增]** 一起到达/多批到达/一起返程/多批返程 | | transportType | String | FLIGHT/TRAIN/SELF_DRIVE | | transportTypeLabel | String | 飞机/火车/自驾 | | transportNo | String | 航班号/车次号（自驾为 null） | | carrier | String | 航司/铁路公司 | | departStation | String | 出发站/机场 | | arriveStation | String | 到达站/机场 | | departTime | String | 出发时间，格式 yyyy-MM-dd HH:mm:ss | | arriveTime | String | 到达时间，格式 yyyy-MM-dd HH:mm:ss | | selfDrivePeriod | String | 自驾时段（MORNING/AFTERNOON/EVENING），非自驾为 null | | selfDrivePeriodLabel | String | 上午/下午/晚上，非自驾为 null | | selfDriveEta | String | 自驾预计到达精确时间，非自驾为 null | | remark | String | 用户备注 | | creatorType | String | USER/ADMIN | | createTime | String | 创建时间 | | travelers | Array | 本批次出行人列表 | travelers 内每个出行人字段： | 字段 | 类型 | 说明 | |------|------|------| | travelerId | Long | 出行人 ID | | name | String | 姓名 | | travelerType | String | ADULT/CHILD/YOUNG_CHILD/BABY | - **响应示例（完整）**： ```json { "code": 200, "message": "success", "data": { "orderId": 700001, "arrivals": [ { "planId": 800001, "orderId": 700001, "direction": "ARRIVAL", "directionLabel": "到达", "mode": "TOGETHER", "modeLabel": "一起到达", "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" } ] } ], "departures": [ { "planId": 800002, "orderId": 700001, "direction": "DEPARTURE", "directionLabel": "离开", "mode": "SEPARATE", "modeLabel": "多批返程", "transportType": "TRAIN", "transportTypeLabel": "火车", "transportNo": "K209", "carrier": null, "departStation": "海拉尔", "arriveStation": "北京", "departTime": "2026-07-15 10:00:00", "arriveTime": "2026-07-16 08:00:00", "selfDrivePeriod": null, "selfDrivePeriodLabel": null, "selfDriveEta": null, "remark": null, "creatorType": "USER", "createTime": "2026-07-02 09:00:00", "travelers": [ { "travelerId": 10001, "name": "张三", "travelerType": "ADULT" } ] } ] } } ``` --- ### 2. POST /mp/order/{orderId}/arrival — 新增交通批次（单条，该方向全量替换） - **使用场景**：用户在「一起到达」或「一起返程」tab 填写单条信息并提交 - **语义重申**：调用此接口会把同 direction 的所有旧批次软删，再插入 1 条新批次。最终该方向只剩 1 条，mode 固定为 TOGETHER - **路径参数**： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | orderId | Long | 是 | 订单 ID | - **请求参数（JSON Body）**： | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | direction | String | 是 | ARRIVAL=到达 / DEPARTURE=离开 | | transportType | String | 是 | FLIGHT=飞机 / TRAIN=火车 / SELF_DRIVE=自驾 | | transportNo | String | 条件必填 | 航班号/车次号；FLIGHT/TRAIN 必填，SELF_DRIVE 不填 | | carrier | String | 否 | 航司/铁路公司，最长 64 字符 | | departStation | String | 条件必填 | 出发站/机场；DEPARTURE+FLIGHT/TRAIN 必填；ARRIVAL 可选 | | arriveStation | String | 条件必填 | 到达站/机场；ARRIVAL+FLIGHT/TRAIN 必填；DEPARTURE 可选 | | departTime | String | 条件必填 | 出发时间；DEPARTURE+FLIGHT/TRAIN 必填；格式 yyyy-MM-dd HH:mm:ss | | arriveTime | String | 条件必填 | 到达时间；ARRIVAL+FLIGHT/TRAIN 必填；格式 yyyy-MM-dd HH:mm:ss | | selfDrivePeriod | String | 条件必填 | 自驾时段；SELF_DRIVE 必填；MORNING/AFTERNOON/EVENING | | selfDriveEta | String | 否 | 自驾预计到达精确时间；SELF_DRIVE 可选；格式 yyyy-MM-dd HH:mm:ss | | remark | String | 否 | 用户备注，最长 255 字符 | | travelerIds | Array | 是 | 出行人 ID 列表，至少 1 人，必须属于本订单 | - **请求示例（到达+飞机）**： ```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 ] } ``` - **响应示例（完整）**： ```json { "code": 200, "message": "success", "data": { "planId": 800001, "orderId": 700001, "direction": "ARRIVAL", "directionLabel": "到达", "mode": "TOGETHER", "modeLabel": "一起到达", "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" } ] } } ``` --- ### 3. POST /mp/order/{orderId}/arrival/batch — 全量替换批次（多批模式） - **使用场景**：用户在「多批到达」或「多批返程」tab，一次性提交该方向所有批次 - **Bug 修复**：旧版本会把订单全部旧批次删掉（含另一方向），新版本只删 body 第一条元素对应的 direction - **新增校验**：body 数组里所有元素的 direction 必须一致，混提返回 code=580010 - **路径参数**： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | orderId | Long | 是 | 订单 ID | - **请求参数（JSON Body，数组）**：字段同上面单条接口，外层包数组 - **请求示例（多批返程）**： ```json [ { "direction": "DEPARTURE", "transportType": "FLIGHT", "transportNo": "CZ6256", "carrier": "南方航空", "departStation": "海拉尔东山", "arriveStation": "北京首都T3", "departTime": "2026-07-15 12:00:00", "arriveTime": "2026-07-15 15:30:00", "travelerIds": [ 10001 ] }, { "direction": "DEPARTURE", "transportType": "TRAIN", "transportNo": "K209", "departStation": "海拉尔", "arriveStation": "北京", "departTime": "2026-07-15 10:00:00", "arriveTime": "2026-07-16 08:00:00", "travelerIds": [ 10002 ] } ] ``` - **响应示例（完整）**： ```json { "code": 200, "message": "success", "data": { "orderId": 700001, "arrivals": [], "departures": [ { "planId": 800003, "orderId": 700001, "direction": "DEPARTURE", "directionLabel": "离开", "mode": "SEPARATE", "modeLabel": "多批返程", "transportType": "FLIGHT", "transportTypeLabel": "飞机", "transportNo": "CZ6256", "carrier": "南方航空", "departStation": "海拉尔东山", "arriveStation": "北京首都T3", "departTime": "2026-07-15 12:00:00", "arriveTime": "2026-07-15 15:30:00", "selfDrivePeriod": null, "selfDrivePeriodLabel": null, "selfDriveEta": null, "remark": null, "creatorType": "USER", "createTime": "2026-07-01 11:00:00", "travelers": [ { "travelerId": 10001, "name": "张三", "travelerType": "ADULT" } ] }, { "planId": 800004, "orderId": 700001, "direction": "DEPARTURE", "directionLabel": "离开", "mode": "SEPARATE", "modeLabel": "多批返程", "transportType": "TRAIN", "transportTypeLabel": "火车", "transportNo": "K209", "carrier": null, "departStation": "海拉尔", "arriveStation": "北京", "departTime": "2026-07-15 10:00:00", "arriveTime": "2026-07-16 08:00:00", "selfDrivePeriod": null, "selfDrivePeriodLabel": null, "selfDriveEta": null, "remark": null, "creatorType": "USER", "createTime": "2026-07-01 11:00:00", "travelers": [ { "travelerId": 10002, "name": "李四", "travelerType": "CHILD" } ] } ] } } ``` --- ## 枚举 / 字典值（完整） ### transport_direction（方向） | 值 | 中文 | 说明 | |----|------|------| | ARRIVAL | 到达 | 游客到达目的地 | | DEPARTURE | 离开 | 游客离开目的地（返程） | ### mode（模式，本次新增） | 值 | 中文 | 说明 | |----|------|------| | TOGETHER | 一起 | 该方向所有出行人同一批次 | | SEPARATE | 多批 | 该方向出行人分多个批次 | ### modeLabel（按 direction + mode 拼，本次新增） | direction | mode | modeLabel | |-----------|------|-----------| | ARRIVAL | TOGETHER | 一起到达 | | ARRIVAL | SEPARATE | 多批到达 | | DEPARTURE | TOGETHER | 一起返程 | | DEPARTURE | SEPARATE | 多批返程 | ### transport_type（交通方式） | 值 | 中文 | |----|------| | FLIGHT | 飞机 | | TRAIN | 火车 | | SELF_DRIVE | 自驾 | ### self_drive_period（自驾时段） | 值 | 中文 | 时间范围 | |----|------|---------| | MORNING | 上午 | 06:00-12:00 | | AFTERNOON | 下午 | 12:00-18:00 | | EVENING | 晚上 | 18:00 以后 | ### creator_type（创建者类型） | 值 | 中文 | |----|------| | USER | 用户自填 | | ADMIN | 定制师代录 | ### traveler_type（出行人类型） | 值 | 中文 | |----|------| | ADULT | 成人 | | CHILD | 儿童 | | YOUNG_CHILD | 幼儿 | | BABY | 婴儿 | --- ## 错误码（本模块完整） | code | message | 触发场景 | |------|---------|---------| | 580001 | 订单当前状态不可修改交通信息: {状态} | 订单不在可编辑状态 | | 580002 | 出行人列表不能为空 | travelerIds 为空 | | 580003 | 以下出行人不属于本订单: {ids} | travelerIds 包含不属于此订单的 ID | | 580004 | 航班号/车次号不能为空 | FLIGHT/TRAIN 时 transportNo 未填 | | 580005 | 到达机场/车站不能为空 | ARRIVAL+FLIGHT/TRAIN 时 arriveStation 未填 | | 580006 | 到达时间不能为空 | ARRIVAL+FLIGHT/TRAIN 时 arriveTime 未填 | | 580007 | 出发机场/车站不能为空 | DEPARTURE+FLIGHT/TRAIN 时 departStation 未填 | | 580008 | 出发时间不能为空 | DEPARTURE+FLIGHT/TRAIN 时 departTime 未填 | | 580009 | 自驾时段不能为空 | SELF_DRIVE 时 selfDrivePeriod 未填 | | 580010 | 批量提交的批次必须同一方向（到达或返程） | batch 接口 body 内 direction 混用（本次新增） | --- ## 业务规则 / 校验规则 1. POST /arrival（单数）：提交即清空同 direction 旧批次，再插入 1 条。最终该方向只有 1 条批次，mode 固定为 TOGETHER。 2. POST /arrival/batch：提交即清空同 direction 旧批次，再批量插入。有 2 条及以上时 mode 为 SEPARATE；仅 1 条时 mode 也是 SEPARATE（因为用户选择了「多批」入口）。 3. 两个接口只影响自己提交的 direction，不互相干扰（本次 bug 修复要点）。 4. PUT /arrival/plan/{planId} 修改单条，不影响其他批次，不改变 mode。 5. DELETE /arrival/plan/{planId} 只软删单条。 6. 以上操作均需订单处于可编辑状态，否则返回 580001。 --- ## 前端实现建议 --- ## 补充说明 - GET 接口新增 mode/modeLabel 字段，向后兼容（纯新增，无删改名），已有代码不受影响 - POST 单数接口语义变更属于破坏性变更，旧版用多次调单数接口实现分批的需改用 batch - 服务重启：需重启 hl-order-service-v2 和 hl-mp-service 后生效