From 236f2517bd7abb8fe61741c2db38cf981cc31754 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Wed, 8 Jul 2026 17:15:35 +0800
Subject: [PATCH] docs(fleet): add vehicle type readonly contract handoff

---
 ...¢å�•è°ƒæ•´ç”¨è½¦è½¦åž‹å¤§ç±»å�ªè¯»æŽ¥å�£æ�ƒé™�-管ç�†å�Žå�°.md | 175 ++++++++++++++++++
 1 file changed, 175 insertions(+)
 create mode 100644 changelogs-v2/2026-07/49_4852_订�调整用车车型大类�读接���-管���.md

diff --git a/changelogs-v2/2026-07/49_4852_订�调整用车车型大类�读接���-管���.md b/changelogs-v2/2026-07/49_4852_订�调整用车车型大类�读接���-管���.md
new file mode 100644
index 0000000..a888e0e
--- /dev/null
+++ 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。