docs(fleet): add vehicle type readonly contract handoff

2026-07-08 17:15:35 +08:00 · 2026-07-08 17:15:35 +08:00 · 236f2517bd
--- a/changelogs-v2/2026-07/49_4852_订单调整用车车型大类只读接口权限-管理后台.md
+++ b/changelogs-v2/2026-07/49_4852_订单调整用车车型大类只读接口权限-管理后台.md
@ -0,0 +1,175 @@
+# 【前端对接·管理后台】订单调整用车车型大类只读接口权限
+
+> 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。