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 +``` + +响应示例: + +```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 +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。