diff --git a/changelogs-v2/2026-07/24_5236_用车接送改由大交通默认驱动-修改接口-管理后台.md b/changelogs-v2/2026-07/24_5236_用车接送改由大交通默认驱动-修改接口-管理后台.md new file mode 100644 index 0000000..8f4d0de --- /dev/null +++ b/changelogs-v2/2026-07/24_5236_用车接送改由大交通默认驱动-修改接口-管理后台.md @@ -0,0 +1,122 @@ +--- +schema: "hl-changelog/v2" +ticket: "5236" +title: "用车接送改由大交通默认驱动" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "后端 PR #5241 已合并至 dev-v3(9578f78d5),order/fleet 已部署测试环境(b57ce915/0da3b9e6),双实例 internal 契约与网关汇总/列表/详情已验证;前端仍为 pending,待删除车辆接送开关并改用大交通摘要。" +updated_at: "2026-07-24" +base: "dev-v3" +--- + +# 用车接送改由大交通默认驱动 + +## 关联 + +- Issue: [wx/HL#5236](https://git.1814.love:8443/wx/HL/issues/5236) +- Backend PR: [wx/HL#5241](https://git.1814.love:8443/wx/HL/pulls/5241) +- Supersedes: [wx/HL#5193](https://git.1814.love:8443/wx/HL/issues/5193) 中“用车需求独立决定接送”的业务口径 +- 服务: `hl-order-service-v3`、`hl-fleet-service` +- 前端仓库/分支: `mmg/hl-ui` / `v2.1` + +## 关键变化 + +车辆安排不再让定制师重复选择“是否需要接机/接站”和“是否需要送机/送站”。 +接送结论由订单当前大交通批次直接决定: + +- `ARRIVAL` 批次聚合接机/接站。 +- `DEPARTURE` 批次聚合送机/送站。 +- 同方向任一批 `pickupRequired=true`,该方向为需要接送。 +- 同方向全部批次均为 `false`,该方向为客人自理。 +- 没有该方向批次时返回 `null`,表示未知。 +- 新建大交通未传 `pickupRequired` 时默认保存为 `true`;显式 `false` 保持客人自理。 + +用车需求和订单调整中的 `pickupRequired`、`dropoffRequired` 字段暂不删除,继续兼容旧请求和回显, +但不再覆盖实时大交通结论。 + +## 变更接口 + +| 方法 | 路径 | 变化 | +|---|---|---| +| `POST` | `/v3/admin/order/:id/transport-plan/add` | 新增大交通未传 `pickupRequired` 时默认 `true` | +| `POST` | `/v3/admin/order/:id/transport-plan/batch` | 批量替换中每个未传值的批次默认 `true` | +| `POST` | `/v3/admin/order/:id/transport-plan/:planId/edit` | 未传该字段时保留原值;显式值正常覆盖 | +| `PUT` | `/v3/admin/order/:id/vehicle-requirement` | 两个接送字段改为兼容字段,不再是权威来源 | +| `GET` | `/v3/admin/order/:id/adjustment/snapshot?scope=VEHICLE_REQ` | 继续通过 `vehicleTransportSummary` 返回大交通批次摘要 | +| `POST` | `/v3/admin/order/:id/adjustment/submit` | `updates.vehicleRequirement` 中两个接送字段仅兼容接收 | +| `GET` | `/admin/fleet/board/orders` | 卡片接送就绪状态改为按实时大交通方向聚合 | +| `GET` | `/admin/fleet/board/orders/:orderId` | `transport.pickupRequired/dropoffRequired` 只取实时大交通聚合 | + +小程序内部大交通新增与批量接口使用相同默认规则,但本 changelog 的前端处理范围仅为管理后台。 + +## 字段语义 + +### 大交通请求 `pickupRequired` + +| 场景 | 入参 | 保存结果 | +|---|---|---| +| 新增单批/批量批次未传 | 字段省略或 `null` | `true` | +| 新增单批/批量批次显式自理 | `false` | `false` | +| 编辑既有批次未传 | 字段省略或 `null` | 保留原值 | +| 编辑既有批次显式修改 | `true` / `false` | 按提交值覆盖 | + +数据库列仍为 `TINYINT(1) NOT NULL`,仅把新记录的数据库默认值从 `0` 改为 `1`,不回填或改写历史行。 + +### 派单详情响应 + +| 字段 | 类型 | 空值 | 说明 | +|---|---|---|---| +| `transport.pickupRequired` | `Boolean` | 无 ARRIVAL 批次时为 `null` | ARRIVAL 批次聚合 | +| `transport.dropoffRequired` | `Boolean` | 无 DEPARTURE 批次时为 `null` | DEPARTURE 批次聚合 | +| `transport.arrive/depart` | `Object/null` | 对应整团批次不存在时为 `null` | 到达/返程整团大交通 | +| `transport.batches[]` | `Object[]` | 无分批时为空数组 | 分批大交通,保留方向、时间、站点和关联出行人 | + +## 前端处理 + +1. 删除“调整订单 → 车辆安排”中的“是否需要接机/接站”和“是否需要送机/送站”两个开关。 +2. 提交用车需求或订单调整时,不再主动提交 `pickupRequired`、`dropoffRequired`。 +3. 车辆安排页直接展示 `vehicleTransportSummary.arrivals[]` 与 `departures[]`;继续使用其中的 + `direction`、`time`、`station`、`transportNo`、`pickupRequired`、`pickupRemark` 和 + `travelerNames[]`。 +4. 派单看板和详情不得回退到 `vehicleRequirement.pickupRequired/dropoffRequired`; + 使用看板接送摘要与详情 `transport.pickupRequired/dropoffRequired`。 +5. 雪花 ID 仍按字符串处理,本次没有字段删除、类型变化或新增错误码。 + +## 展示矩阵 + +| 大交通场景 | 接机/接站 | 送机/送站 | 页面展示 | +|---|---:|---:|---| +| ARRIVAL 任一批需要,DEPARTURE 全部自理 | `true` | `false` | 分方向显示“平台接 / 客人自理” | +| ARRIVAL 全部自理,DEPARTURE 任一批需要 | `false` | `true` | 分方向显示“客人自理 / 平台送” | +| 同方向多批混合 | `true` | 按返程批次聚合 | 明细保留每个批次及关联出行人 | +| 只有 ARRIVAL | 按到达批次聚合 | `null` | 返程显示未提供,不回退旧用车需求 | +| 只有 DEPARTURE | `null` | 按返程批次聚合 | 到达显示未提供,不回退旧用车需求 | +| 完全无大交通 | `null` | `null` | 显示“暂无接送机时间” | + +## 验证证据 + +- Order 定向测试 57 项通过。 +- Fleet `BoardOrderServiceTest` 50 项通过。 +- 调整/需求/出行人兼容链路 357 项通过。 +- 调整快照完整字段断言 `AdjustmentServiceTest` 10 项通过。 +- `mvn -pl hl-order-service-v3 -am verify` 通过。 +- Order 模块 Surefire 汇总 6646 项,0 失败、0 错误、28 跳过。 +- `mvn -pl hl-fleet-service -am verify` 通过:Fleet 模块 2361 项,0 失败、0 错误、1 跳过。 +- Fleet `spotless:check` 与 `git diff --check` 通过。 +- OpenAPI/oasdiff: `not_configured`,使用源码字段/语义比对和测试作为 fallback。 +- Spring Cloud Contract: `not_configured`,使用 order-v3 生产者与 Fleet 消费者测试作为 fallback。 +- 后端 PR #5241 已合并,merge commit 为 `9578f78d5f0241db502d94b22283cbff0a351c53`。 +- 测试环境部署任务:order `b57ce915`、fleet `0da3b9e6`。 +- `order_transport_plan.pickup_required` 已验证为 `TINYINT(1) NOT NULL DEFAULT 1`,Flyway + `20260724.001` 执行成功。 +- order `8086/8186` 均通过 `/v3/internal/order/orders/:orderId/transport` 与批量看板上下文实测; + `true/false/null` 三态及 ARRIVAL/DEPARTURE 分方向聚合符合字段语义。 +- 测试网关 `/admin/fleet/board/summary`、`/orders`、`/orders/:orderId` 均返回成功; + 详情连续 4 次通过,运行时证据为 `D:/work2/hl-workflow/.tmp/5236-gateway-evidence.json`。