docs: 订单用车座位数按车型型号下拉

2026-07-08 18:12:52 +08:00 · 2026-07-08 18:12:52 +08:00 · f3b433a034
--- a/changelogs-v2/2026-07/50_4856_订单调整用车座位数按车型型号下拉-管理后台.md
+++ b/changelogs-v2/2026-07/50_4856_订单调整用车座位数按车型型号下拉-管理后台.md
@ -0,0 +1,207 @@
+# 【前端对接·管理后台】订单调整用车座位数按车型型号下拉
+
+> Issue: [wx/HL#4856](https://git.1814.love:8443/wx/HL/issues/4856)  
+> PR: [wx/HL#4857](https://git.1814.love:8443/wx/HL/pulls/4857)  
+> 服务: `hl-fleet-service`、`hl-order-service-v3`  
+> 日期: 2026-07-08  
+> 影响范围: 订单详情 / 调整订单弹窗 / 车辆安排
+
+## 1. 结论
+
+- 订单调整弹窗的车辆安排仍只选择“车型大类”，不选择具体车型型号。
+- 座位数不是车型大类固定值，而是该大类下所有真实车型型号 `seats` 去重后的下拉选项。
+- 前端调用 `GET /admin/fleet/vehicle-types/list`，用返回的 `seatOptions` 渲染座位数下拉。
+- 提交时 `fleet[].vehicleType` 传大类 `typeKey`，`fleet[].seats` 传用户从 `seatOptions` 中选中的座位数。
+- 后端会按真实车型库校验 `vehicleType + seats` 组合；不在该大类 `seatOptions` 内会拒绝提交。
+
+## 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,
+      "seatOptions": [5, 7]
+    },
+    {
+      "id": "2057378611889180675",
+      "typeKey": "mpv",
+      "typeName": "商务车",
+      "icon": "Van",
+      "sortOrder": 2,
+      "modelCount": 5,
+      "inUseCount": 10,
+      "seatOptions": [7, 9, 19]
+    }
+  ]
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `typeKey` | string | 车型大类提交值。历史兼容值如 `suv2` 后端会规范化保存。 |
+| `typeName` | string | 车型大类展示名。 |
+| `seatOptions` | number[] | 当前大类下车型型号 `seats` 去重升序后的可选座位数。 |
+| `modelCount` | number | 当前大类下车型型号数量。 |
+| `inUseCount` | number | 当前大类下在用车辆数量。 |
+
+前端处理规则：
+
+- 先选车型大类，再从该大类 `seatOptions` 渲染座位数下拉。
+- 座位数不允许手输，不允许用户改成 `seatOptions` 之外的值。
+- 切换车型大类后，如果原座位数不在新大类 `seatOptions` 中，需要清空座位数并要求重新选择。
+- `seatOptions` 为空时，该大类不能提交，提示“该车型大类暂无可用座位数，请先维护车型库”。
+
+## 3. 提交车辆需求
+
+```http
+PUT /v3/admin/order/2074746808742928386/vehicle-requirement
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+```
+
+请求示例：
+
+```json
+{
+  "fleet": [
+    {
+      "vehicleType": "suv2",
+      "seats": 5,
+      "count": 1
+    },
+    {
+      "vehicleType": "mpv",
+      "seats": 7,
+      "count": 1
+    }
+  ],
+  "specialTags": ["儿童安全座椅", "中文司机"],
+  "remark": "需要接机，后备箱放 2 个 28 寸行李箱"
+}
+```
+
+成功响应示例：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "id": "2074759000000000001",
+    "version": 1,
+    "isActive": true,
+    "status": "PENDING",
+    "submittedAt": "2026-07-08T18:40:00",
+    "claimerId": null,
+    "claimerName": null,
+    "claimedAt": null
+  }
+}
+```
+
+后端保存口径：
+
+- `fleet[].vehicleType` 保存为规范化后的车型大类，例如历史值 `suv2` 会保存为 `suv`。
+- `fleet[].seats` 是用户选择的座位数选项值，不代表具体车型型号 ID。
+- 一组车型默认覆盖整段行程；不会出现前几天和后几天车型大类不同的需求。
+- 多车需求通过多组 `fleet[]` 或单组 `count > 1` 表达。
+
+## 4. 非法座位数组合
+
+如果前端提交了不在该大类 `seatOptions` 中的座位数：
+
+```json
+{
+  "fleet": [
+    {
+      "vehicleType": "suv2",
+      "seats": 19,
+      "count": 1
+    }
+  ]
+}
+```
+
+失败响应示例：
+
+```json
+{
+  "code": 582024,
+  "message": "座位数不在该车型大类可选座位数中，请检查车型库",
+  "success": false,
+  "data": null
+}
+```
+
+前端处理：
+
+- 直接展示后端 `message`。
+- 不要在前端自行兜底成任意座位数。
+- 如果线上出现该错误，先检查页面是否使用了最新 `seatOptions`，再检查车型库维护数据。
+
+## 5. 车务车型库不可用
+
+订单服务提交前会只读调用车务车型库校验座位数。如果车务车型库不可用：
+
+```json
+{
+  "code": 582091,
+  "message": "车队车型库不可用，无法校验座位数选项",
+  "success": false,
+  "data": null
+}
+```
+
+前端处理：
+
+- 直接提示后端 `message`。
+- 不要绕过校验继续提交，因为否则会产生无法派车或错误座位数需求。
+
+## 6. 前端对接清单
+
+| 场景 | 处理方式 |
+|------|----------|
+| 初次打开车辆安排 | 调 `GET /admin/fleet/vehicle-types/list`，缓存本次弹窗内的大类和 `seatOptions`。 |
+| 选择车型大类 | 更新座位数下拉为该大类 `seatOptions`。 |
+| 选择座位数 | 只能从下拉中选，不能文本输入。 |
+| 切换车型大类 | 清空不兼容座位数，要求重新选择。 |
+| 提交车辆需求 | `vehicleType=typeKey`，`seats=选中的 seatOptions 值`，`count=车辆数量`。 |
+| `seatOptions=[]` | 禁止提交该大类，提示维护车型库。 |
+| 错误码 `582024` | 展示“座位数不在该车型大类可选座位数中，请检查车型库”。 |
+| 错误码 `582091` | 展示“车队车型库不可用，无法校验座位数选项”。 |
+
+## 7. 后端本地验证
+
+```bash
+mvn -pl hl-fleet-service -am -Dtest=VehicleTypeServiceTest -DfailIfNoTests=false test
+mvn -pl hl-order-service-v3 -am -Dtest=RequirementServiceTest -DfailIfNoTests=false test
+```
+
+覆盖点：
+
+- `GET /admin/fleet/vehicle-types/list` 返回 `seatOptions`。
+- `seatOptions` 来源于车型型号 `seats`，去重并升序。
+- 历史大类 key 兼容，例如 `suv2` 可映射到 `suv` 座位数选项。
+- 订单提交时合法 `vehicleType + seats` 通过。
+- 订单提交时非法 `vehicleType + seats` 返回 `582024`。