docs: 订单用车座位数按车型型号下拉
这个提交包含在：
API Changelog Bot
父节点
236f2517bd
当前提交
f3b433a034
@ -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`。
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户