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

Issue: wx/HL#4852
PR: wx/HL#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. 车型大类下拉

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

响应示例：

{
  "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. 不要使用的接口

订单调整弹窗不要调用：

GET /admin/fleet/vehicle-types

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

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

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

4. 提交车辆需求

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 寸行李箱"
}

响应示例：

{
  "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. 联系车务兜底

没有有效用车需求时：

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

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

失败响应：

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

前端处理：

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

6. 后端验证

本地已验证：

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。

4.2 KiB 原始文件 Blame 文件历史

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

1. 结论

2. 车型大类下拉

3. 不要使用的接口

4. 提交车辆需求

5. 联系车务兜底

6. 后端验证

4.2 KiB

原始文件 Blame 文件历史