diff --git a/changelogs-v2/2026-07/50_4856_订单调整用车座位数按车型型号下拉-管理后台.md b/changelogs-v2/2026-07/50_4856_订单调整用车座位数按车型型号下拉-管理后台.md new file mode 100644 index 0000000..2efd537 --- /dev/null +++ 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 +``` + +响应示例: + +```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 +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`。