From 2d7ffb0cb19bdf94b82b6dfe93991d304b5c657f Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 10 Jun 2026 16:21:33 +0800 Subject: [PATCH] =?UTF-8?q?changelog:=20=E8=BD=A6=E5=9E=8B=E5=BA=93?= =?UTF-8?q?=E8=AE=A1=E6=95=B0=E5=AD=97=E6=AE=B5=E4=B8=8A=E7=BA=BF+sortOrde?= =?UTF-8?q?r=E9=80=89=E5=A1=AB+=E6=96=87=E6=A1=A3=E5=A5=91=E7=BA=A6?= =?UTF-8?q?=E5=8B=98=E8=AF=AF=20(PR=20#3650/#3651)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...线sortOrder选填与文档契约勘误-新增字段-管理后台.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 changelogs-v2/2026-06/10_3650_车型库计数字段上线sortOrder选填与文档契约勘误-新增字段-管理后台.md diff --git a/changelogs-v2/2026-06/10_3650_车型库计数字段上线sortOrder选填与文档契约勘误-新增字段-管理后台.md b/changelogs-v2/2026-06/10_3650_车型库计数字段上线sortOrder选填与文档契约勘误-新增字段-管理后台.md new file mode 100644 index 0000000..41eb7d5 --- /dev/null +++ b/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 处成功码勘误,无契约变化)