# 【前端对接·管理后台】订单调整用车座位数按车型型号下拉

> Issue: [wx/HL#4856](https://git.1814.love:8443/wx/HL/issues/4856)  
> PR: [wx/HL#4857](https://git.1814.love:8443/wx/HL/pulls/4857)  
> 服务: `hl-fleet-service`、`hl-order-service-v3`  
> 日期: 2026-07-08  
> 影响范围: 订单详情 / 调整订单弹窗 / 车辆安排

## 1. 结论

- 订单调整弹窗的车辆安排仍只选择“车型大类”，不选择具体车型型号。
- 座位数不是车型大类固定值，而是该大类下所有真实车型型号 `seats` 去重后的下拉选项。
- 前端调用 `GET /admin/fleet/vehicle-types/list`，用返回的 `seatOptions` 渲染座位数下拉。
- 提交时 `fleet[].vehicleType` 传大类 `typeKey`，`fleet[].seats` 传用户从 `seatOptions` 中选中的座位数。
- 后端会按真实车型库校验 `vehicleType + seats` 组合；不在该大类 `seatOptions` 内会拒绝提交。

## 2. 车型大类与座位下拉

```http
GET /admin/fleet/vehicle-types/list
Authorization: Bearer <admin-token>
```

响应示例：

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    {
      "id": "2057378611889180674",
      "typeKey": "suv2",
      "typeName": "SUV系列",
      "icon": "Car",
      "description": null,
      "sortOrder": 1,
      "modelCount": 5,
      "inUseCount": 4,
      "seatOptions": [5, 7]
    },
    {
      "id": "2057378611889180675",
      "typeKey": "mpv",
      "typeName": "商务车",
      "icon": "Van",
      "sortOrder": 2,
      "modelCount": 5,
      "inUseCount": 10,
      "seatOptions": [7, 9, 19]
    }
  ]
}
```

字段说明：

| 字段 | 类型 | 说明 |
|------|------|------|
| `typeKey` | string | 车型大类提交值。历史兼容值如 `suv2` 后端会规范化保存。 |
| `typeName` | string | 车型大类展示名。 |
| `seatOptions` | number[] | 当前大类下车型型号 `seats` 去重升序后的可选座位数。 |
| `modelCount` | number | 当前大类下车型型号数量。 |
| `inUseCount` | number | 当前大类下在用车辆数量。 |

前端处理规则：

- 先选车型大类，再从该大类 `seatOptions` 渲染座位数下拉。
- 座位数不允许手输，不允许用户改成 `seatOptions` 之外的值。
- 切换车型大类后，如果原座位数不在新大类 `seatOptions` 中，需要清空座位数并要求重新选择。
- `seatOptions` 为空时，该大类不能提交，提示“该车型大类暂无可用座位数，请先维护车型库”。

## 3. 提交车辆需求

```http
PUT /v3/admin/order/2074746808742928386/vehicle-requirement
Authorization: Bearer <admin-token>
Content-Type: application/json
```

请求示例：

```json
{
  "fleet": [
    {
      "vehicleType": "suv2",
      "seats": 5,
      "count": 1
    },
    {
      "vehicleType": "mpv",
      "seats": 7,
      "count": 1
    }
  ],
  "specialTags": ["儿童安全座椅", "中文司机"],
  "remark": "需要接机，后备箱放 2 个 28 寸行李箱"
}
```

成功响应示例：

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "id": "2074759000000000001",
    "version": 1,
    "isActive": true,
    "status": "PENDING",
    "submittedAt": "2026-07-08T18:40:00",
    "claimerId": null,
    "claimerName": null,
    "claimedAt": null
  }
}
```

后端保存口径：

- `fleet[].vehicleType` 保存为规范化后的车型大类，例如历史值 `suv2` 会保存为 `suv`。
- `fleet[].seats` 是用户选择的座位数选项值，不代表具体车型型号 ID。
- 一组车型默认覆盖整段行程；不会出现前几天和后几天车型大类不同的需求。
- 多车需求通过多组 `fleet[]` 或单组 `count > 1` 表达。

## 4. 非法座位数组合

如果前端提交了不在该大类 `seatOptions` 中的座位数：

```json
{
  "fleet": [
    {
      "vehicleType": "suv2",
      "seats": 19,
      "count": 1
    }
  ]
}
```

失败响应示例：

```json
{
  "code": 582024,
  "message": "座位数不在该车型大类可选座位数中，请检查车型库",
  "success": false,
  "data": null
}
```

前端处理：

- 直接展示后端 `message`。
- 不要在前端自行兜底成任意座位数。
- 如果线上出现该错误，先检查页面是否使用了最新 `seatOptions`，再检查车型库维护数据。

## 5. 车务车型库不可用

订单服务提交前会只读调用车务车型库校验座位数。如果车务车型库不可用：

```json
{
  "code": 582091,
  "message": "车队车型库不可用，无法校验座位数选项",
  "success": false,
  "data": null
}
```

前端处理：

- 直接提示后端 `message`。
- 不要绕过校验继续提交，因为否则会产生无法派车或错误座位数需求。

## 6. 前端对接清单

| 场景 | 处理方式 |
|------|----------|
| 初次打开车辆安排 | 调 `GET /admin/fleet/vehicle-types/list`，缓存本次弹窗内的大类和 `seatOptions`。 |
| 选择车型大类 | 更新座位数下拉为该大类 `seatOptions`。 |
| 选择座位数 | 只能从下拉中选，不能文本输入。 |
| 切换车型大类 | 清空不兼容座位数，要求重新选择。 |
| 提交车辆需求 | `vehicleType=typeKey`，`seats=选中的 seatOptions 值`，`count=车辆数量`。 |
| `seatOptions=[]` | 禁止提交该大类，提示维护车型库。 |
| 错误码 `582024` | 展示“座位数不在该车型大类可选座位数中，请检查车型库”。 |
| 错误码 `582091` | 展示“车队车型库不可用，无法校验座位数选项”。 |

## 7. 后端本地验证

```bash
mvn -pl hl-fleet-service -am -Dtest=VehicleTypeServiceTest -DfailIfNoTests=false test
mvn -pl hl-order-service-v3 -am -Dtest=RequirementServiceTest -DfailIfNoTests=false test
```

覆盖点：

- `GET /admin/fleet/vehicle-types/list` 返回 `seatOptions`。
- `seatOptions` 来源于车型型号 `seats`，去重并升序。
- 历史大类 key 兼容，例如 `suv2` 可映射到 `suv` 座位数选项。
- 订单提交时合法 `vehicleType + seats` 通过。
- 订单提交时非法 `vehicleType + seats` 返回 `582024`。

## 8. 测试服验证

验证时间：2026-07-08 18:19:16  
测试网关：`https://api.test.1814.love:9443`  
测试账号：`designer_4760` / `fleet_mgr_4760`  
测试订单：`HL20260708144554930` (`2074746784613097473`)

### 8.1 车型大类返回座位选项

`GET /admin/fleet/vehicle-types/list` 实测返回：

```json
[
  { "typeKey": "suv2", "typeName": "SUV系列", "seatOptions": [5, 7] },
  { "typeKey": "mpv", "typeName": "商务车", "seatOptions": [7] },
  { "typeKey": "sedan", "typeName": "轿车系列", "seatOptions": [5] },
  { "typeKey": "bus", "typeName": "大巴系列", "seatOptions": [12, 15, 16, 19] }
]
```

DB 核对 `fleet_vehicle_model`：`suv2` 下真实车型型号 seats 去重后为 `[5, 7]`，与接口 `seatOptions` 一致。

### 8.2 非法座位数组合

请求：

```json
{
  "fleet": [
    { "vehicleType": "suv2", "seats": 99, "count": 1 }
  ],
  "specialTags": ["中文司机"],
  "remark": "issue4856 invalid seat option verify"
}
```

响应：

```json
{
  "code": 582024,
  "success": false,
  "message": "座位数不在该车型大类可选座位数中，请检查车型库"
}
```

### 8.3 合法座位数组合

请求：

```json
{
  "fleet": [
    { "vehicleType": "suv2", "seats": 5, "count": 1 }
  ],
  "specialTags": ["中文司机"],
  "remark": "issue4856 valid seat option verify"
}
```

响应：

```json
{
  "code": 200,
  "success": true,
  "message": "成功"
}
```

落库核对：

```json
{
  "requirementId": "2074800483964272641",
  "version": 1,
  "status": "PENDING",
  "isActive": 1,
  "fleet": [
    { "vehicleType": "suv", "seats": 5, "count": 1 }
  ]
}
```