wx/hl-api-changelog

派生 0

API Changelog Bot f2c9864c02 docs: 补充4856测试服验证结果

2026-07-08 18:20:10 +08:00

7.6 KiB

原始文件 Blame 文件历史

【前端对接·管理后台】订单调整用车座位数按车型型号下拉

Issue: wx/HL#4856
PR: wx/HL#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. 车型大类与座位下拉

GET /admin/fleet/vehicle-types/list
Authorization: Bearer <admin-token>

响应示例：

{
  "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. 提交车辆需求

PUT /v3/admin/order/2074746808742928386/vehicle-requirement
Authorization: Bearer <admin-token>
Content-Type: application/json

请求示例：

{
  "fleet": [
    {
      "vehicleType": "suv2",
      "seats": 5,
      "count": 1
    },
    {
      "vehicleType": "mpv",
      "seats": 7,
      "count": 1
    }
  ],
  "specialTags": ["儿童安全座椅", "中文司机"],
  "remark": "需要接机，后备箱放 2 个 28 寸行李箱"
}

成功响应示例：

{
  "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 中的座位数：

{
  "fleet": [
    {
      "vehicleType": "suv2",
      "seats": 19,
      "count": 1
    }
  ]
}

失败响应示例：

{
  "code": 582024,
  "message": "座位数不在该车型大类可选座位数中，请检查车型库",
  "success": false,
  "data": null
}

前端处理：

直接展示后端 message。
不要在前端自行兜底成任意座位数。
如果线上出现该错误，先检查页面是否使用了最新 seatOptions，再检查车型库维护数据。

5. 车务车型库不可用

订单服务提交前会只读调用车务车型库校验座位数。如果车务车型库不可用：

{
  "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. 后端本地验证

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。

8. 测试服验证

验证时间：2026-07-08 18:19:16
测试网关：https://api.test.1814.love:9443
测试账号：designer_4760 / fleet_mgr_4760
测试订单：HL20260708144554930 (2074746784613097473)

8.1 车型大类返回座位选项

GET /admin/fleet/vehicle-types/list 实测返回：

[
  { "typeKey": "suv2", "typeName": "SUV系列", "seatOptions": [5, 7] },
  { "typeKey": "mpv", "typeName": "商务车", "seatOptions": [7] },
  { "typeKey": "sedan", "typeName": "轿车系列", "seatOptions": [5] },
  { "typeKey": "bus", "typeName": "大巴系列", "seatOptions": [12, 15, 16, 19] }
]

DB 核对 fleet_vehicle_model：suv2 下真实车型型号 seats 去重后为 [5, 7]，与接口 seatOptions 一致。

8.2 非法座位数组合

请求：

{
  "fleet": [
    { "vehicleType": "suv2", "seats": 99, "count": 1 }
  ],
  "specialTags": ["中文司机"],
  "remark": "issue4856 invalid seat option verify"
}

响应：

{
  "code": 582024,
  "success": false,
  "message": "座位数不在该车型大类可选座位数中，请检查车型库"
}

8.3 合法座位数组合

请求：

{
  "fleet": [
    { "vehicleType": "suv2", "seats": 5, "count": 1 }
  ],
  "specialTags": ["中文司机"],
  "remark": "issue4856 valid seat option verify"
}

响应：

{
  "code": 200,
  "success": true,
  "message": "成功"
}

落库核对：

{
  "requirementId": "2074800483964272641",
  "version": 1,
  "status": "PENDING",
  "isActive": 1,
  "fleet": [
    { "vehicleType": "suv", "seats": 5, "count": 1 }
  ]
}

7.6 KiB 原始文件 Blame 文件历史 Unescape Escape