diff --git a/changelogs-v2/2026-07/22_车务看板车型分段展示与车型下拉接口检查-前端待处理-管理后台.md b/changelogs-v2/2026-07/22_车务看板车型分段展示与车型下拉接口检查-前端待处理-管理后台.md new file mode 100644 index 0000000..1c0aceb --- /dev/null +++ b/changelogs-v2/2026-07/22_车务看板车型分段展示与车型下拉接口检查-前端待处理-管理后台.md @@ -0,0 +1,215 @@ +# 车务看板车型分段展示与车型下拉接口检查(前端待处理) + +- 日期: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` 聚合数组硬推“前几天/后几天”的车型分段。 +- 若要展示车型分段,等后端补明确的分段字段后再接。 +