changelog: 车型库计数字段上线+sortOrder选填+文档契约勘误 (PR #3650/#3651)

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

@@ -0,0 +1,85 @@
+# 【新增·管理后台】车型库计数字段(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;编辑返回真实计数 |
+
+**树接口响应示例**(测试服实测):
+
+```json
+{
+  "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 自动追加):
+
+```bash
+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 处成功码勘误,无契约变化)