# 车务看板车型分段展示与车型下拉接口检查（前端待处理）

- 日期：2026-07-05
- 端：管理后台
- 页面：
  - 车务管理 / 派单看板 `/fleet/board`
  - 订单详情 / 用车需求弹窗
- 结论：
  - “实际车型”下拉的读取接口已有：`GET /admin/fleet/vehicle-types`，非分页，返回车型大类 + 型号树。
  - 派单看板列表当前没有“前几天哪个车型、后几天哪个车型”的分段字段，不能靠前端从现有聚合字段硬推。
  - 订单用车需求提交接口当前也没有 `vehicleModelId` / 分段日期字段；前端不要把实际型号名直接塞进旧的 `vehicleType` 字段。

## 1. 测试环境接口复验

### 1.1 派单看板列表

```http
GET /admin/fleet/board/orders
```

测试环境返回 `200`，列表记录当前有这些关键字段：

| 字段 | 当前含义 |
|------|----------|
| `startDate` | 本条派单行的开始日期 |
| `endDate` | 本条派单行的结束日期 |
| `fleetItemIndex` | 同一用车需求展开后的项次序 |
| `requiredVehicles` | 同订单聚合后的需求车型数组 |
| `currentVehicleModel` | 已派车辆型号快照，未派为空 |
| `currentVehicleSeats` | 已派车辆座位数，未派为空 |

实测同一个订单出现多条派单行时，返回形态类似：

```json
[
  {
    "fleetItemIndex": 0,
    "startDate": "2026-07-02",
    "endDate": "2026-07-04",
    "requiredVehicles": [
      { "vehicleType": "mpv", "categoryLabel": "商务车", "seats": 7, "count": 1 },
      { "vehicleType": "suv", "categoryLabel": "SUV", "seats": 5, "count": 2 }
    ]
  },
  {
    "fleetItemIndex": 1,
    "startDate": "2026-07-02",
    "endDate": "2026-07-04",
    "requiredVehicles": [
      { "vehicleType": "mpv", "categoryLabel": "商务车", "seats": 7, "count": 1 },
      { "vehicleType": "suv", "categoryLabel": "SUV", "seats": 5, "count": 2 }
    ]
  }
]
```

这说明 `requiredVehicles` 是订单级聚合，不是“该日期段对应车型”的明细。前端不能用这个字段推断“前几天商务车，后几天 SUV”。

### 1.2 车型大类 + 实际型号树

```http
GET /admin/fleet/vehicle-types
```

测试环境返回 `200`，非分页，结构为：

```json
[
  {
    "id": "车型大类ID",
    "typeKey": "suv2",
    "typeName": "SUV系列",
    "modelCount": 5,
    "models": [
      {
        "id": "车型型号ID",
        "vehicleTypeId": "所属大类ID",
        "modelName": "丰田普拉多",
        "seats": 7,
        "basePrice": "1000.00",
        "alias": "",
        "inUseCount": 2
      }
    ]
  }
]
```

这个接口可以作为“实际车型”下拉的数据源。

对比：

```http
GET /admin/fleet/vehicle-types/list
```

这个接口只返回车型大类，不含 `models`，不适合做“实际车型型号”下拉。

## 2. 前端处理要求

### 2.1 车型下拉改用实际车型树

用车需求弹窗里的“车型”下拉不要继续用静态字典或写死选项：

- 轿车
- 商务车
- SUV
- 中巴
- 大巴
- 房车
- 行李车

应改读：

```http
GET /admin/fleet/vehicle-types
```

建议前端把 `data[].models[]` 拉平成可选项：

| 下拉内容 | 取值 |
|----------|------|
| 展示文案 | `modelName`，可附带 `seats`，例如 `丰田普拉多 · 7座` |
| 型号 ID | `models[].id` |
| 所属大类 | 外层 `id / typeKey / typeName` |
| 默认座位数 | `models[].seats` |

不要用 `/admin/fleet/vehicle-types/list` 做这个下拉；它只适合筛选大类，不含实际型号。

### 2.2 不要把实际型号名直接提交到旧字段

当前用车需求提交接口仍是旧契约：

```http
PUT /v3/admin/order/{id}/vehicle-requirement
```

当前入参仍只有：

| 字段 | 当前含义 |
|------|----------|
| `fleet[].vehicleType` | 车型分类 |
| `fleet[].seats` | 座位数 |
| `fleet[].count` | 辆数 |

当前没有：

- `fleet[].vehicleModelId`
- `fleet[].modelName`
- `fleet[].startDate`
- `fleet[].endDate`

所以前端不能把 `丰田普拉多` 这类 `modelName` 直接提交到 `vehicleType`。fleet 侧历史归一只识别 `suv / mpv / bus / sedan` 及少量中文分类别名，直接提交实际型号名会导致后续需求展开无法稳定归一。

如果本次只是“下拉数据来源先换成实际车型库”，前端可以先用车型树做展示和辅助填座位数，但真正保存实际型号 ID 需要后端补提交契约。

## 3. 派单看板“前几天哪个车型、后几天哪个车型”

当前 `GET /admin/fleet/board/orders` 不满足这个展示。

原因：

1. `requiredVehicles` 是订单级聚合数组，不是分段明细。
2. `startDate/endDate` 是当前派单行日期段，不表达“某个车型需求对应哪个日期段”。
3. 订单用车需求源数据当前也没有每个车型项自己的开始/结束日期。

前端不要按以下方式硬推：

- 不要用 `requiredVehicles` 数组顺序 + `fleetItemIndex` 猜测日期段。
- 不要用整单 `startDate/endDate` 切分成前后几天。
- 不要根据人数、车型数量或卡片顺序推断车型分段。

如果页面要稳定展示“前几天 A 车型，后几天 B 车型”，需要后端补明确字段。建议目标形态如下：

```json
{
  "vehicleSegments": [
    {
      "startDate": "2026-05-19",
      "endDate": "2026-05-21",
      "vehicleModelId": "2090000000000000001",
      "modelName": "丰田普拉多",
      "vehicleType": "suv",
      "vehicleTypeLabel": "SUV",
      "seats": 7,
      "count": 1
    },
    {
      "startDate": "2026-05-22",
      "endDate": "2026-05-24",
      "vehicleModelId": "2090000000000000002",
      "modelName": "别克GL8",
      "vehicleType": "mpv",
      "vehicleTypeLabel": "商务车",
      "seats": 7,
      "count": 1
    }
  ]
}
```

后端补契约前，派单看板建议仍按现有字段展示：

- 整体行程日期：`startDate ~ endDate`
- 需求车型 chip：`requiredVehicles[].categoryLabel + seats + count`
- 已派车辆：`currentVehicleModel / currentVehicleSeats / currentVehiclePlate`

## 4. 验收口径

- 用车需求弹窗车型下拉数据来自 `GET /admin/fleet/vehicle-types` 的 `models[]`，不再用写死选项。
- 下拉能展示实际型号名和座位数，例如 `丰田普拉多 · 7座`。
- 前端不把 `modelName` 直接提交到旧的 `fleet[].vehicleType`。
- 派单看板不基于 `requiredVehicles` 聚合数组硬推“前几天/后几天”的车型分段。
- 若要展示车型分段，等后端补明确的分段字段后再接。