【前端对接·管理后台】车务会话有效用车需求守卫与调整页接送机时间

Issue: wx/HL#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

GET /v3/admin/order/2074303545149980674/itinerary
Authorization: Bearer <admin-token>

新增字段：

字段	类型	说明
`canContactFleet`	boolean	是否允许联系车务；true 表示已有当前 active 用车需求。
`contactFleetDisabledReason`	string/null	不可联系车务原因；`canContactFleet=false` 时返回。

无有效用车需求响应示例：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "hotelGroup": {
      "requirement": {
        "requirementId": "90001",
        "status": "DONE"
      }
    },
    "vehicleGroup": null,
    "unreadMessageCount": 0,
    "canContactFleet": false,
    "contactFleetDisabledReason": "请先提交有效用车需求后再联系车务"
  }
}

已有有效用车需求响应示例：

{
  "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 打开车务会话

POST /admin/message/chat/open-fleet
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "orderId": "2074303545149980674",
  "peerAdminId": null
}

成功响应示例：

{
  "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": []
    }
  }
}

无有效用车需求失败响应：

{
  "code": 281013,
  "message": "请先提交有效用车需求后再联系车务",
  "success": false,
  "data": null
}

3.3 发送车务消息

POST /admin/message/chat/FLEET:2074303545149980674/messages
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "content": "司机联系方式发我",
  "contentType": "TEXT"
}

说明：

仅订单维度键 FLEET:{orderId} 会执行有效用车需求守卫。
历史 pair 私聊键如 FLEET:{bizId}:{minAdminId}:{maxAdminId} 不走本守卫。

无有效用车需求失败响应同 281013：

{
  "code": 281013,
  "message": "请先提交有效用车需求后再联系车务",
  "success": false,
  "data": null
}

3.4 调整订单车辆页快照

GET /v3/admin/order/2074303545149980674/adjustment/snapshot?scope=VEHICLE_REQ
Authorization: Bearer <admin-token>

新增字段：vehicleTransportSummary

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

无接送机时间响应示例：

{
  "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. 测试覆盖

后端已覆盖：

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。
调整快照有大交通时间时返回接/送明细，无时间时返回 暂无接送机时间。

8.1 KiB 原始文件 Blame 文件历史 Unescape Escape

【前端对接·管理后台】车务会话有效用车需求守卫与调整页接送机时间

1. 结论

2. 前端必须处理

3. 接口变更

3.1 订单行程 Tab

3.2 打开车务会话

3.3 发送车务消息

3.4 调整订单车辆页快照

4. 测试覆盖

8.1 KiB

原始文件 Blame 文件历史