216 行
6.4 KiB
Markdown
216 行
6.4 KiB
Markdown
# 车务看板车型分段展示与车型下拉接口检查（前端待处理）
|
||
|
||
- 日期：2026-07-05
|
||
- 端：管理后台
|
||
- 页面：
|
||
- 车务管理 / 派单看板 `/fleet/board`
|
||
- 订单详情 / 用车需求弹窗
|
||
- 结论：
|
||
- “实际车型”下拉的读取接口已有：`GET /admin/fleet/vehicle-types`，非分页，返回车型大类 + 型号树。
|
||
- 派单看板列表当前没有“前几天哪个车型、后几天哪个车型”的分段字段，不能靠前端从现有聚合字段硬推。
|
||
- 订单用车需求提交接口当前也没有 `vehicleModelId` / 分段日期字段；前端不要把实际型号名直接塞进旧的 `vehicleType` 字段。
|
||
|
||
## 1. 测试环境接口复验
|
||
|
||
### 1.1 派单看板列表
|
||
|
||
```http
|
||
GET /admin/fleet/board/orders
|
||
```
|
||
|
||
测试环境返回 `200`，列表记录当前有这些关键字段：
|
||
|
||
| 字段 | 当前含义 |
|
||
|------|----------|
|
||
| `startDate` | 本条派单行的开始日期 |
|
||
| `endDate` | 本条派单行的结束日期 |
|
||
| `fleetItemIndex` | 同一用车需求展开后的项次序 |
|
||
| `requiredVehicles` | 同订单聚合后的需求车型数组 |
|
||
| `currentVehicleModel` | 已派车辆型号快照，未派为空 |
|
||
| `currentVehicleSeats` | 已派车辆座位数，未派为空 |
|
||
|
||
实测同一个订单出现多条派单行时，返回形态类似：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"fleetItemIndex": 0,
|
||
"startDate": "2026-07-02",
|
||
"endDate": "2026-07-04",
|
||
"requiredVehicles": [
|
||
{ "vehicleType": "mpv", "categoryLabel": "商务车", "seats": 7, "count": 1 },
|
||
{ "vehicleType": "suv", "categoryLabel": "SUV", "seats": 5, "count": 2 }
|
||
]
|
||
},
|
||
{
|
||
"fleetItemIndex": 1,
|
||
"startDate": "2026-07-02",
|
||
"endDate": "2026-07-04",
|
||
"requiredVehicles": [
|
||
{ "vehicleType": "mpv", "categoryLabel": "商务车", "seats": 7, "count": 1 },
|
||
{ "vehicleType": "suv", "categoryLabel": "SUV", "seats": 5, "count": 2 }
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
这说明 `requiredVehicles` 是订单级聚合，不是“该日期段对应车型”的明细。前端不能用这个字段推断“前几天商务车，后几天 SUV”。
|
||
|
||
### 1.2 车型大类 + 实际型号树
|
||
|
||
```http
|
||
GET /admin/fleet/vehicle-types
|
||
```
|
||
|
||
测试环境返回 `200`，非分页，结构为：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "车型大类ID",
|
||
"typeKey": "suv2",
|
||
"typeName": "SUV系列",
|
||
"modelCount": 5,
|
||
"models": [
|
||
{
|
||
"id": "车型型号ID",
|
||
"vehicleTypeId": "所属大类ID",
|
||
"modelName": "丰田普拉多",
|
||
"seats": 7,
|
||
"basePrice": "1000.00",
|
||
"alias": "",
|
||
"inUseCount": 2
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
这个接口可以作为“实际车型”下拉的数据源。
|
||
|
||
对比：
|
||
|
||
```http
|
||
GET /admin/fleet/vehicle-types/list
|
||
```
|
||
|
||
这个接口只返回车型大类，不含 `models`，不适合做“实际车型型号”下拉。
|
||
|
||
## 2. 前端处理要求
|
||
|
||
### 2.1 车型下拉改用实际车型树
|
||
|
||
用车需求弹窗里的“车型”下拉不要继续用静态字典或写死选项：
|
||
|
||
- 轿车
|
||
- 商务车
|
||
- SUV
|
||
- 中巴
|
||
- 大巴
|
||
- 房车
|
||
- 行李车
|
||
|
||
应改读：
|
||
|
||
```http
|
||
GET /admin/fleet/vehicle-types
|
||
```
|
||
|
||
建议前端把 `data[].models[]` 拉平成可选项：
|
||
|
||
| 下拉内容 | 取值 |
|
||
|----------|------|
|
||
| 展示文案 | `modelName`，可附带 `seats`，例如 `丰田普拉多 · 7座` |
|
||
| 型号 ID | `models[].id` |
|
||
| 所属大类 | 外层 `id / typeKey / typeName` |
|
||
| 默认座位数 | `models[].seats` |
|
||
|
||
不要用 `/admin/fleet/vehicle-types/list` 做这个下拉；它只适合筛选大类，不含实际型号。
|
||
|
||
### 2.2 不要把实际型号名直接提交到旧字段
|
||
|
||
当前用车需求提交接口仍是旧契约：
|
||
|
||
```http
|
||
PUT /v3/admin/order/{id}/vehicle-requirement
|
||
```
|
||
|
||
当前入参仍只有：
|
||
|
||
| 字段 | 当前含义 |
|
||
|------|----------|
|
||
| `fleet[].vehicleType` | 车型分类 |
|
||
| `fleet[].seats` | 座位数 |
|
||
| `fleet[].count` | 辆数 |
|
||
|
||
当前没有：
|
||
|
||
- `fleet[].vehicleModelId`
|
||
- `fleet[].modelName`
|
||
- `fleet[].startDate`
|
||
- `fleet[].endDate`
|
||
|
||
所以前端不能把 `丰田普拉多` 这类 `modelName` 直接提交到 `vehicleType`。fleet 侧历史归一只识别 `suv / mpv / bus / sedan` 及少量中文分类别名，直接提交实际型号名会导致后续需求展开无法稳定归一。
|
||
|
||
如果本次只是“下拉数据来源先换成实际车型库”，前端可以先用车型树做展示和辅助填座位数，但真正保存实际型号 ID 需要后端补提交契约。
|
||
|
||
## 3. 派单看板“前几天哪个车型、后几天哪个车型”
|
||
|
||
当前 `GET /admin/fleet/board/orders` 不满足这个展示。
|
||
|
||
原因：
|
||
|
||
1. `requiredVehicles` 是订单级聚合数组，不是分段明细。
|
||
2. `startDate/endDate` 是当前派单行日期段，不表达“某个车型需求对应哪个日期段”。
|
||
3. 订单用车需求源数据当前也没有每个车型项自己的开始/结束日期。
|
||
|
||
前端不要按以下方式硬推：
|
||
|
||
- 不要用 `requiredVehicles` 数组顺序 + `fleetItemIndex` 猜测日期段。
|
||
- 不要用整单 `startDate/endDate` 切分成前后几天。
|
||
- 不要根据人数、车型数量或卡片顺序推断车型分段。
|
||
|
||
如果页面要稳定展示“前几天 A 车型，后几天 B 车型”，需要后端补明确字段。建议目标形态如下：
|
||
|
||
```json
|
||
{
|
||
"vehicleSegments": [
|
||
{
|
||
"startDate": "2026-05-19",
|
||
"endDate": "2026-05-21",
|
||
"vehicleModelId": "2090000000000000001",
|
||
"modelName": "丰田普拉多",
|
||
"vehicleType": "suv",
|
||
"vehicleTypeLabel": "SUV",
|
||
"seats": 7,
|
||
"count": 1
|
||
},
|
||
{
|
||
"startDate": "2026-05-22",
|
||
"endDate": "2026-05-24",
|
||
"vehicleModelId": "2090000000000000002",
|
||
"modelName": "别克GL8",
|
||
"vehicleType": "mpv",
|
||
"vehicleTypeLabel": "商务车",
|
||
"seats": 7,
|
||
"count": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
后端补契约前，派单看板建议仍按现有字段展示：
|
||
|
||
- 整体行程日期：`startDate ~ endDate`
|
||
- 需求车型 chip：`requiredVehicles[].categoryLabel + seats + count`
|
||
- 已派车辆：`currentVehicleModel / currentVehicleSeats / currentVehiclePlate`
|
||
|
||
## 4. 验收口径
|
||
|
||
- 用车需求弹窗车型下拉数据来自 `GET /admin/fleet/vehicle-types` 的 `models[]`，不再用写死选项。
|
||
- 下拉能展示实际型号名和座位数，例如 `丰田普拉多 · 7座`。
|
||
- 前端不把 `modelName` 直接提交到旧的 `fleet[].vehicleType`。
|
||
- 派单看板不基于 `requiredVehicles` 聚合数组硬推“前几天/后几天”的车型分段。
|
||
- 若要展示车型分段，等后端补明确的分段字段后再接。
|
||
|