hl-api-changelog/changelogs-v2/2026-06/10_3650_车型库计数字段上线sortOrder选填与文档契约勘误-新增字段-管理后台.md

【新增·管理后台】车型库计数字段(modelCount/inUseCount)上线 + 型号 sortOrder 改选填 + 文档契约勘误(page 参名/records/成功码 200)

存放目录: changelogs-v2/2026-06/ 涉及服务: hl-fleet-service(8087) PR: #3650 + #3651(均已合并 dev-v3,测试服已部署并 API 实测通过) | 无关联工单 | 日期: 2026-06-10 影响范围: 管理后台车型管理库页面(/admin/fleet/vehicle-types/* 全部 9 端点);另有 FLEET/HOUSE 文档勘误请前端自查

⚠️ 关键说明(前端必看 3 点)

1. 计数字段上线了:车型树/大类分页/型号分页现在直接返回 modelCount(大类下型号数)与 inUseCount(在役车辆数,大类级+型号级),左栏「N 款 · 在役 N 台」、头部 MiniStat、型号表「在役车辆」列、删除守卫提示「仍有 N 辆在役」都不用前端自己聚合了。口径=未软删全量,与删除守卫(600104/600105)同口径,实时查库。
2. 新增/编辑型号不用传 sortOrder 了(原必填,不传会 400):新增不传自动追加同大类末尾(现有最大+1,空则 1);编辑不传保持原值。原型表单本来就没有排序输入,前端按表单四字段(modelName/seats/basePrice/alias)直接提交即可。
3. 文档勘误,前端如曾照旧文档实现请自查 3 处(均为文档错、后端行为一直如此,后端无变化):
   • 分页参数名是 page 不是 pageNo(传 pageNo 会被静默忽略、永远返回第 1 页);
   • 分页响应列表字段是 records 不是 list(§0.6 及车辆/司机/H5/待审/看板各节示例已订正);
   • 成功码是 code: 200 不是 code: 0(FLEET 130 处、HOUSE 48 处示例已全部订正;判 code===0 会把所有成功当失败)。

1. 计数字段:涉及接口与新字段

接口	新字段	说明
GET /admin/fleet/vehicle-types(车型树)	大类级 modelCount、inUseCount;models[].inUseCount	两级计数一次带回
GET /admin/fleet/vehicle-types/page(大类分页)	records[].modelCount、records[].inUseCount	左栏导航/MiniStat 数据源
GET /admin/fleet/vehicle-types/models/page(型号分页)	records[].inUseCount	型号表「在役车辆」列数据源
POST/PUT 大类/型号(写接口)	出参=完整对象(含计数)	新建时计数=0;编辑返回真实计数

树接口响应示例(测试服实测):

{
  "code": 200,
  "data": [
    {
      "id": "1929151481086734337",
      "typeKey": "suv2",
      "typeName": "SUV 越野",
      "icon": "🚙",
      "sortOrder": 1,
      "modelCount": 1,
      "inUseCount": 0,
      "models": [
        { "id": "1929151628176175106", "vehicleTypeId": "1929151481086734337",
          "modelName": "丰田普拉多", "seats": 7, "basePrice": "100.00",
          "alias": "普拉多", "sortOrder": 1, "inUseCount": 0 }
      ]
    }
  ],
  "msg": "成功"
}

注意:models[] 里也带 vehicleTypeId 与 sortOrder(旧文档示例漏列,实际一直返回);basePrice 是字符串。

2. 新增/编辑型号:sortOrder 选填

场景	行为
新增不传 sortOrder	自动追加同大类末尾(现有最大+1,空大类=1)
编辑不传 sortOrder	保持原值不变
显式传	按传入值(行为不变)

新增型号请求示例(四字段即可,测试服实测返回 sortOrder=2 自动追加):

curl -X POST "https://api.test.1814.love:9443/admin/fleet/vehicle-types/{typeId}/models" \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"modelName":"丰田威尔法","seats":7,"basePrice":"2000.00","alias":"威尔法"}'

3. 错误码表补全(行为未变,文档原漏列)

code	msg	触发
600101	车型大类标识已存在	新增大类 typeKey 重复
600102	车型大类不存在	大类 id 无效(原文档误写「车型不存在」)
600103	车型型号已存在	同大类内型号名重复(新增/编辑改名)
600104	大类下存在型号,不能删除	删大类守卫
600105	型号被车辆引用,不能删除	删型号守卫(实测文案逐字一致)
600106	车型型号不存在	型号 id 无效

另:编辑大类时 typeKey 仍需传非空值(后端忽略其值,不传会 400 参数校验);编辑型号 alias 不传=保持原值、传 "" 才清空。

4. 文档版本

• FLEET API → v1.5.49 + v1.5.50(§1 全节契约订正 + 全文成功码勘误),文档站已同步:https://web.test.1814.love:9443/hl-docs/order-v3/api/API-SPEC-FLEET-V1.5.html
• HOUSE API → v1.1.5(48 处成功码勘误,无契约变化)