# 【前端对接·管理后台】订单调整用车车型大类只读接口权限

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

## 1. 结论

- 订单调整弹窗的车辆安排只允许选择“车型大类”，不要选择具体车型型号。
- 前端应调用 `GET /admin/fleet/vehicle-types/list` 渲染大类下拉，定制师等已登录后台角色可只读访问。
- `GET /admin/fleet/vehicle-types` 仍是车务管理树接口，返回 `models[]`，非车务角色访问仍会 403。
- 提交用车需求仍只传 `fleet[].vehicleType = typeKey`，不传 `modelId/modelName`。
- 没有有效用车需求时，联系车务应展示后端 `281013` 提示，不要把车型接口 403 文案误展示成车务会话问题。

## 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
    },
    {
      "id": "2057378611889180675",
      "typeKey": "mpv",
      "typeName": "商务车",
      "icon": "Van",
      "sortOrder": 2,
      "modelCount": 5,
      "inUseCount": 10
    }
  ]
}
```

前端取值：

| 用途 | 字段 |
|------|------|
| 下拉展示 | `typeName` |
| 下拉 value / 提交值 | `typeKey` |
| 辅助展示 | `modelCount`、`inUseCount` |
| 不要用于订单车辆需求 | `id`、具体车型 `modelId/modelName` |

## 3. 不要使用的接口

订单调整弹窗不要调用：

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

该接口是车务管理页的车型树，非车务角色仍会返回：

```json
{
  "code": 403,
  "message": "无权限访问车务管理，请切换到车务角色",
  "success": false,
  "data": null
}
```

车务角色下该接口会带 `models[]`，但 `models[]` 是车型管理/车辆档案/价格日历使用的具体型号，不适合订单用车需求。

## 4. 提交车辆需求

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

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

响应示例：

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

说明：

- `vehicleType` 允许传当前大类真实 `typeKey`，后端会做规范化保存。
- 一组车型默认覆盖整段行程；不要增加“前几天/后几天车型不同”的 UI。
- 多车需求用多组或 `count > 1` 表达。

## 5. 联系车务兜底

没有有效用车需求时：

```http
POST /admin/message/chat/open-fleet
Content-Type: application/json

{
  "orderId": "2074746808742928386",
  "peerAdminId": null
}
```

失败响应：

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

前端处理：

- 订单调整车辆安排页先提交有效用车需求，再允许联系车务。
- `281013` 直接提示后端 `message`。
- 不要因为车型树接口 403 而提示“切换车务角色”；订单调整页不应该调用车型树接口。

## 6. 后端验证

本地已验证：

```bash
mvn -pl hl-fleet-service -am "-Dtest=FleetAdminRoleGuardInterceptorTest,VehicleTypeControllerTest" -DfailIfNoTests=false test
mvn -pl hl-fleet-service spotless:check
```

覆盖点：

- `CUSTOMIZER` 可访问 `GET /admin/fleet/vehicle-types/list`。
- `CUSTOMIZER` 访问 `GET /admin/fleet/vehicle-types` 仍返回 403。
- 缺少 `X-Admin-Role` 时访问大类列表仍返回 401。