# 【前端对接·管理后台】车务查看订单详情即进入配车中

> **Issue**: [wx/HL#4787](https://git.1814.love:8443/wx/HL/issues/4787)  
> **服务**: hl-fleet-service + hl-order-service-v3  
> **日期**: 2026-07-06  
> **影响范围**: 车务派单看板 / 矩阵派单 / 订单详情状态联动  
> **前端代码**: 不需要直接修改，本通知用于纠正状态口径和测试断言

---

## 1. 结论

车务没有房务式“抢单池”。车务用户只要打开订单详情，就代表车务已经接手该订单的当前 active 用车需求，后端会把用车需求推进到 `PROCESSING`（配车中）。

触发接口只有现有详情接口：

```http
GET /admin/fleet/board/orders/{orderId}
```

前端不需要新增调用，不要调用旧 order-v3 抢单接口，也不要等“展开建单”后再认为订单进入配车中。

---

## 2. 行为变化

| 场景 | 后端行为 | 前端处理 |
|------|----------|----------|
| 当前 active 用车需求是 `PENDING` | 打开详情后同步改为 `PROCESSING`，并同步 `order_main.vehicle_control_status=PROCESSING` | 继续打开详情即可；后续订单状态从后端刷新 |
| 当前 active 用车需求已是 `PROCESSING` | 幂等成功，不重复制造副作用 | 不需要特殊处理 |
| 当前 active 用车需求已是 `DONE` | 不回退到 `PROCESSING` | 不要把已派完订单展示回配车中 |
| 当前 active 用车需求是 `REJECTED_TO_CONSULTANT` / `REJECTED_TO_ADMIN` / `PENDING_REVIEW` | 不允许被详情查看拉回 `PROCESSING` | 展示后端返回状态，不要本地覆盖 |
| order-v3 详情降级或无当前需求 | 详情接口尽量返回可展示数据，状态回写失败只告警，不阻断详情 | 前端仍按 `relatedDetailReady` 和空字段兜底展示 |

---

## 3. 请求示例

```http
GET /admin/fleet/board/orders/2070756230887890945
Authorization: Bearer <admin-token>
```

路径参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | string/long | 是 | 订单 ID。前端按字符串保存，避免 JS 长整型精度问题 |

无 query 参数，无 request body。

---

## 4. 响应示例

响应结构不新增字段，本次变化是状态副作用。

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "id": "2070756230887890945",
    "orderNo": "HL20260702092466935",
    "customerName": "张伟",
    "productName": "测试核心产品-单档-固定订金",
    "headcount": 2,
    "startDate": "2026-05-09",
    "endDate": "2026-05-11",
    "vehicleTypeSummary": "SUV×1",
    "plannerNote": "[单1:流程-全流程-目标态:已完成-验:全链路E2E,mock合同保险,BUG1配车null司机] 需求床房，方便带孩子入住",
    "transport": {
      "arrive": null,
      "depart": null,
      "batches": []
    },
    "currentAssignment": null,
    "relatedDetailReady": true
  }
}
```

字段说明：

| 字段 | 说明 |
|------|------|
| `currentAssignment=null` | 当前没有已派/占位派单，不代表不能进入配车中。查看详情本身已经触发车务接手 |
| `transport.arrive/depart=null` | 大交通缺失时真实返回空槽，不要 mock 时间 |
| `transport.batches=[]` | 源订单没有大交通批次，前端按空列表展示 |
| `relatedDetailReady=false` | order-v3 上下文拉取降级，前端可展示本地快照和空字段 |

---

## 5. 状态副作用示例

调用详情前：

```json
{
  "orderId": "2070756230887890945",
  "requirementId": "2070756234515968001",
  "order_vehicle_requirement.status": "PENDING",
  "order_main.vehicle_control_status": "PENDING"
}
```

调用详情后：

```json
{
  "orderId": "2070756230887890945",
  "requirementId": "2070756234515968001",
  "order_vehicle_requirement.status": "PROCESSING",
  "order_main.vehicle_control_status": "PROCESSING"
}
```

已完成/驳回态不会回退：

```json
{
  "before": "DONE",
  "after": "DONE",
  "reason": "已完成派单不能被迟到的详情查看拉回配车中"
}
```

```json
{
  "before": "REJECTED_TO_CONSULTANT",
  "after": "REJECTED_TO_CONSULTANT",
  "reason": "车务已驳回给定制师，详情查看不能覆盖驳回态"
}
```

---

## 6. 前端验收点

1. 从派单看板或矩阵打开订单详情后，订单侧车务状态应刷新为配车中。
2. 不要在前端模拟 `PROCESSING`；刷新后以接口返回/订单详情真实状态为准。
3. 不要调用房务抢单接口或旧 order-v3 车控抢单接口。
4. 已派完订单再次打开详情，不能在 UI 上被改回“配车中”。
5. 驳回给定制师/驳回给车务管理员/待审核的用车需求，不能因为打开详情被前端本地覆盖为“配车中”。
6. 大交通缺失仍然是合法数据：`arrive=null`、`depart=null`、`batches=[]` 时按缺失展示，不要 mock。

---

## 7. 后端验证口径

本地已覆盖：

```bash
mvn -pl hl-fleet-service -am "-Dtest=BoardOrderServiceTest,AssignmentServiceTest,AssignmentOccupancyListenerTest" -DfailIfNoTests=false -DfailIfNoSpecifiedTests=false test
mvn -pl hl-order-service-v3 -am "-Dtest=RequirementServiceVehicleStatusTest" -DfailIfNoTests=false -DfailIfNoSpecifiedTests=false test
mvn -pl hl-fleet-service spotless:check
git diff --check
```

待 PR 合并并部署测试服后，会继续用真实车务账号验证：

- `GET /admin/fleet/board/orders/{orderId}`：`PENDING -> PROCESSING`
- 重复打开详情：`PROCESSING -> PROCESSING`
- DONE/驳回态订单：不回退
- 订单主表 `vehicle_control_status` 与当前 active 用车需求状态同步