# 【新增·管理后台】车型库计数字段(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 处成功码勘误,无契约变化)
