wx/hl-api-changelog

派生 0

API Changelog Bot d9ecc04a93 docs(fleet): clarify vehicle model dropdown contracts

2026-07-05 15:59:14 +08:00

6.4 KiB

原始文件 永久链接 Blame 文件历史

车务看板车型分段展示与车型下拉接口检查（前端待处理）

日期：2026-07-05
端：管理后台
页面：
- 车务管理 / 派单看板 /fleet/board
- 订单详情 / 用车需求弹窗
结论：
- “实际车型”下拉的读取接口已有：GET /admin/fleet/vehicle-types，非分页，返回车型大类 + 型号树。
- 派单看板列表当前没有“前几天哪个车型、后几天哪个车型”的分段字段，不能靠前端从现有聚合字段硬推。
- 订单用车需求提交接口当前也没有 vehicleModelId / 分段日期字段；前端不要把实际型号名直接塞进旧的 vehicleType 字段。

1. 测试环境接口复验

1.1 派单看板列表

GET /admin/fleet/board/orders

测试环境返回 200，列表记录当前有这些关键字段：

字段	当前含义
`startDate`	本条派单行的开始日期
`endDate`	本条派单行的结束日期
`fleetItemIndex`	同一用车需求展开后的项次序
`requiredVehicles`	同订单聚合后的需求车型数组
`currentVehicleModel`	已派车辆型号快照，未派为空
`currentVehicleSeats`	已派车辆座位数，未派为空

实测同一个订单出现多条派单行时，返回形态类似：

[
  {
    "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 车型大类 + 实际型号树

GET /admin/fleet/vehicle-types

测试环境返回 200，非分页，结构为：

[
  {
    "id": "车型大类ID",
    "typeKey": "suv2",
    "typeName": "SUV系列",
    "modelCount": 5,
    "models": [
      {
        "id": "车型型号ID",
        "vehicleTypeId": "所属大类ID",
        "modelName": "丰田普拉多",
        "seats": 7,
        "basePrice": "1000.00",
        "alias": "",
        "inUseCount": 2
      }
    ]
  }
]

这个接口可以作为“实际车型”下拉的数据源。

对比：

GET /admin/fleet/vehicle-types/list

这个接口只返回车型大类，不含 models，不适合做“实际车型型号”下拉。

2. 前端处理要求

2.1 车型下拉改用实际车型树

用车需求弹窗里的“车型”下拉不要继续用静态字典或写死选项：

轿车
商务车
SUV
中巴
大巴
房车
行李车

应改读：

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 不要把实际型号名直接提交到旧字段

当前用车需求提交接口仍是旧契约：

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 不满足这个展示。

原因：

requiredVehicles 是订单级聚合数组，不是分段明细。
startDate/endDate 是当前派单行日期段，不表达“某个车型需求对应哪个日期段”。
订单用车需求源数据当前也没有每个车型项自己的开始/结束日期。

前端不要按以下方式硬推：

不要用 requiredVehicles 数组顺序 + fleetItemIndex 猜测日期段。
不要用整单 startDate/endDate 切分成前后几天。
不要根据人数、车型数量或卡片顺序推断车型分段。

如果页面要稳定展示“前几天 A 车型，后几天 B 车型”，需要后端补明确字段。建议目标形态如下：

{
  "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 聚合数组硬推“前几天/后几天”的车型分段。
若要展示车型分段，等后端补明确的分段字段后再接。

6.4 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape