# 【前端对接·管理后台】车务会话有效用车需求守卫与调整页接送机时间 > **Issue**: [wx/HL#4829](https://git.1814.love:8443/wx/HL/issues/4829) > **服务**: hl-user-service + hl-order-service-v3 > **日期**: 2026-07-08 > **影响范围**: 订单详情「联系车务」、调整订单车辆页、车务聊天 --- ## 1. 结论 - 车务会话必须建立在“当前 active 用车需求”之后；没有有效用车需求时，后端会拒绝打开车务会话和向 `FLEET:{orderId}` 直接发消息。 - 调整订单车辆页新增大交通接送机/站时间摘要；没有任何可展示时间时返回 `暂无接送机时间`。 - 车辆需求车型组合仍按整段行程生效，不支持“前几天一辆车、后几天另一辆车”的分天换车型需求。 --- ## 2. 前端必须处理 | 场景 | 前端处理 | |------|----------| | 订单详情联系车务按钮 | 读 `GET /v3/admin/order/{id}/itinerary` 的 `canContactFleet`。为 `false` 时禁用/隐藏按钮，并展示 `contactFleetDisabledReason`。 | | 车务聊天开窗兜底 | `POST /admin/message/chat/open-fleet` 返回 `281013` 时提示后端 message，不要继续打开空会话。 | | 车务聊天直接发消息兜底 | 对 `FLEET:{orderId}` 调 `POST /admin/message/chat/{conversationKey}/messages` 返回 `281013` 时提示后端 message。 | | 调整订单车辆页顶部红框 | 读 `GET /v3/admin/order/{id}/adjustment/snapshot?scope=VEHICLE_REQ` 的 `vehicleTransportSummary`；有 `displayText` 显示摘要，没有则显示 `emptyText`。 | | 车辆需求车型组 | 继续提交 `fleet[].vehicleType/seats/count`，每组默认覆盖整段行程；不要增加前几天/后几天的分段车型 UI。 | --- ## 3. 接口变更 ### 3.1 订单行程 Tab ```http GET /v3/admin/order/2074303545149980674/itinerary Authorization: Bearer ``` 新增字段： | 字段 | 类型 | 说明 | |------|------|------| | `canContactFleet` | boolean | 是否允许联系车务；true 表示已有当前 active 用车需求。 | | `contactFleetDisabledReason` | string/null | 不可联系车务原因；`canContactFleet=false` 时返回。 | 无有效用车需求响应示例： ```json { "code": 200, "message": "成功", "success": true, "data": { "hotelGroup": { "requirement": { "requirementId": "90001", "status": "DONE" } }, "vehicleGroup": null, "unreadMessageCount": 0, "canContactFleet": false, "contactFleetDisabledReason": "请先提交有效用车需求后再联系车务" } } ``` 已有有效用车需求响应示例： ```json { "code": 200, "message": "成功", "success": true, "data": { "vehicleGroup": { "requirement": { "requirementId": "91011223344", "version": 1, "status": "PENDING", "vehicleTypeSummary": "BUSINESS×1 / SUV×1", "specialTags": ["中文司机"], "remark": "司机会蒙语" }, "assignments": [] }, "canContactFleet": true, "contactFleetDisabledReason": null } } ``` ### 3.2 打开车务会话 ```http POST /admin/message/chat/open-fleet Authorization: Bearer Content-Type: application/json { "orderId": "2074303545149980674", "peerAdminId": null } ``` 成功响应示例： ```json { "code": 200, "message": "成功", "success": true, "data": { "conversationKey": "FLEET:2074303545149980674", "isNew": false, "order": { "orderNo": "HL20260707092437709", "customerName": "测试客户", "productName": "测试核心产品-单档-固定订金", "tripDays": 3, "adultCount": 2, "childCount": 0 }, "thread": { "conversationKey": "FLEET:2074303545149980674", "messages": [] } } } ``` 无有效用车需求失败响应： ```json { "code": 281013, "message": "请先提交有效用车需求后再联系车务", "success": false, "data": null } ``` ### 3.3 发送车务消息 ```http POST /admin/message/chat/FLEET:2074303545149980674/messages Authorization: Bearer Content-Type: application/json { "content": "司机联系方式发我", "contentType": "TEXT" } ``` 说明： - 仅订单维度键 `FLEET:{orderId}` 会执行有效用车需求守卫。 - 历史 pair 私聊键如 `FLEET:{bizId}:{minAdminId}:{maxAdminId}` 不走本守卫。 无有效用车需求失败响应同 `281013`： ```json { "code": 281013, "message": "请先提交有效用车需求后再联系车务", "success": false, "data": null } ``` ### 3.4 调整订单车辆页快照 ```http GET /v3/admin/order/2074303545149980674/adjustment/snapshot?scope=VEHICLE_REQ Authorization: Bearer ``` 新增字段：`vehicleTransportSummary` ```json { "code": 200, "message": "成功", "success": true, "data": { "basic": { "orderNo": "HL20260707092437709", "customerName": "测试客户", "totalAmount": "6210.00" }, "vehicleRequirement": { "id": "91011223344", "version": 1, "status": "PENDING", "fleet": [ { "vehicleType": "BUSINESS", "seats": 7, "count": 1 } ], "specialTags": ["中文司机"], "remark": "需要大空间后备箱" }, "vehicleTransportSummary": { "hasPickupTime": true, "displayText": "接：2026-07-23 10:15 海拉尔东山机场 CA1234；送：2026-07-25 15:20 海拉尔站 K99", "emptyText": null, "arrivals": [ { "direction": "ARRIVAL", "directionLabel": "到达", "actionLabel": "接", "timeType": "ARRIVE_TIME", "time": "2026-07-23T10:15:00", "station": "海拉尔东山机场", "transportType": "FLIGHT", "transportTypeLabel": "飞机", "transportNo": "CA1234", "pickupRequired": true, "pickupRemark": "T3 出口举牌", "travelerNames": ["张三", "李四"] } ], "departures": [ { "direction": "DEPARTURE", "directionLabel": "离开", "actionLabel": "送", "timeType": "DEPART_TIME", "time": "2026-07-25T15:20:00", "station": "海拉尔站", "transportType": "TRAIN", "transportTypeLabel": "火车", "transportNo": "K99", "pickupRequired": true, "pickupRemark": "提前 2 小时送站", "travelerNames": ["张三", "李四"] } ] }, "editableTabLocksHint": ["VEHICLE_REQ"] } } ``` 无接送机时间响应示例： ```json { "code": 200, "message": "成功", "success": true, "data": { "vehicleRequirement": null, "vehicleTransportSummary": { "hasPickupTime": false, "displayText": null, "emptyText": "暂无接送机时间", "arrivals": [], "departures": [] } } } ``` 字段说明： | 字段 | 类型 | 说明 | |------|------|------| | `hasPickupTime` | boolean | 是否有至少一条可展示时间。 | | `displayText` | string/null | 后端拼好的简短摘要，适合顶部红框直接展示。 | | `emptyText` | string/null | 无时间时固定为 `暂无接送机时间`。 | | `arrivals[]` | array | 到达批次，时间优先取 `arriveTime`，自驾取 `selfDriveEta`。 | | `departures[]` | array | 离开批次，时间优先取 `departTime`，自驾取 `selfDriveEta`。 | | `timeType` | string | `ARRIVE_TIME` / `DEPART_TIME` / `SELF_DRIVE_ETA`。 | --- ## 4. 测试覆盖 后端已覆盖： ```bash mvn -pl hl-user-service "-Dtest=ChatManagerTest,ConversationKeyUtilTest" test mvn -pl hl-order-service-v3 -am "-Dtest=HouseOrderChatSummaryServiceTest,AdjustmentServiceTest,OrderDetailServiceTest" -DfailIfNoTests=false test ``` 覆盖点： - `open-fleet` 无 active 用车需求返回 `281013`，不创建车务成员行。 - `FLEET:{orderId}` 发送消息前执行同一守卫。 - 订单摘要返回 `vehicleRequirementId / vehicleRequirementStatus / canContactFleet`。 - 行程 Tab 返回 `canContactFleet / contactFleetDisabledReason`。 - 调整快照有大交通时间时返回接/送明细，无时间时返回 `暂无接送机时间`。