diff --git a/changelogs/2026-03/2026-03-25_order_transport.md b/changelogs/2026-03/2026-03-25_order_transport.md new file mode 100644 index 0000000..a0b1e4d --- /dev/null +++ b/changelogs/2026-03/2026-03-25_order_transport.md @@ -0,0 +1,97 @@ +# 订单交通信息(接送站)— 航班/火车实时动态 + +> 为订单添加去程接站/回程送站的航班或火车信息,查询时自动从飞常准API获取实时动态(到达时间、延误状态等)。 + +--- + +## 一、管理端接口 + +### 1.1 添加交通信息 +``` +POST /admin/order/{orderId}/transport +``` + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| legType | String | 是 | OUTBOUND=去程接站, RETURN=回程送站 | +| transportType | String | 是 | FLIGHT=航班, TRAIN=火车 | +| transportNo | String | 是 | 航班号(如CA1234)或车次(如G71) | +| departureStation | String | 否 | 出发站/机场 | +| arrivalStation | String | 否 | 到达站/机场 | +| travelDate | String | 是 | 乘坐日期(yyyy-MM-dd) | +| remark | String | 否 | 备注 | + +### 1.2 编辑交通信息 +``` +PUT /admin/order/transport/{transportId} +``` +请求体同上(所有字段可选更新) + +### 1.3 删除交通信息 +``` +DELETE /admin/order/transport/{transportId} +``` + +### 1.4 查询订单交通信息(含实时动态) +``` +GET /admin/order/{orderId}/transports +``` + +--- + +## 二、小程序端接口 + +### 2.1 填写交通信息 +``` +POST /mp/order/{orderId}/transport +``` +请求体同管理端 + +### 2.2 查看交通信息 +``` +GET /mp/order/{orderId}/transports +``` + +--- + +## 三、响应结构 OrderTransportVO + +| 字段 | 类型 | 说明 | +|------|------|------| +| transportId | String | 交通信息ID | +| orderId | String | 订单ID | +| legType | String | OUTBOUND/RETURN | +| transportType | String | FLIGHT/TRAIN | +| transportNo | String | 航班号或车次 | +| departureStation | String | 出发站 | +| arrivalStation | String | 到达站 | +| travelDate | String | 乘坐日期 | +| remark | String | 备注 | +| createdByType | String | ADMIN=管理员填, USER=用户填 | +| **planDepartTime** | String | 计划出发时间(实时) | +| **planArriveTime** | String | 计划到达时间(实时) | +| **actualDepartTime** | String | 实际/预计出发时间(实时) | +| **actualArriveTime** | String | 实际/预计到达时间(实时) | +| **liveStatus** | String | 状态:计划/起飞/到达/延误/晚点等(实时) | +| **extraInfo** | Map | 额外信息(航站楼/登机口/出口等) | + +**加粗字段**为查询时从飞常准API实时获取,不存数据库。 + +--- + +## 四、使用场景 + +``` +1. 订单确认后,管理员在订单详情填写客人的去程航班/火车 +2. 或者客人自己在小程序"补充信息"时填写 +3. 司机/管理员查看时,自动显示实时到达时间和延误状态 +4. 接站时间有变(延误等),页面自动反映最新状态 +``` + +## 五、涉及服务 + +需重启:**hl-order-service、hl-transport-service、hl-mp-service** + +## 六、数据库变更 + +新增表 `order_transport`(DDL: `sql/order_transport.sql`),测试环境已执行。