53 行
3.9 KiB
Markdown
53 行
3.9 KiB
Markdown
# 【修改·管理后台】车辆档案:列表新增常驻司机字段、详情补 typeKey/准驾/驾龄、keyword 支持搜车型、批量导入大修(CSV/警告档/局部更新)
|
|
|
|
> 存放目录: changelogs-v2/2026-06/
|
|
> 涉及服务: hl-fleet-service(8087)
|
|
> PR: #3653 + #3656(均已合并 dev-v3,**测试服已部署并 API 实测通过**) | 无关联工单 | 日期: 2026-06-10
|
|
> 影响范围: 管理后台**车辆档案**页面(`/admin/fleet/vehicles/*` 6 端点)+ 全文档级勘误自查项
|
|
|
|
## ⚠️ 关键说明(前端必看 4 点)
|
|
|
|
1. **车辆列表(§2.1)新增常驻司机三字段**:`primaryDriverId`/`primaryDriverName`/`primaryDriverLicenseType`(无常驻=null)。派单弹窗车卡显示常驻司机、车辆卡准驾徽章不用再反查司机侧。
|
|
2. **keyword 现在真的能搜车型了**:原来只搜车牌(文档一直写「车牌/车型」但代码只搜车牌,按车型名搜会静默返回空列表),现在车牌 OR 车型名模糊均命中。
|
|
3. **批量导入行为变化(重要)**:
|
|
- **更新已有车牌的行=11 个导入列的局部更新,空白列保持原值**——原来会把该车的附件全部清掉、解绑常驻司机、清空 VIN(已修复,放心重导);
|
|
- **CSV 真的可用了**(原来上传 .csv 直接 500;.xlsx 此前部署缺 POI 依赖实际也不可用,已一并修复);
|
|
- **新增警告档**:出参多 `warnedCount`/`warnings[{row,plate,field,msg}]`(保险不足 30 天/年检临期或已过期——**行仍然导入**,只是提醒;`warnedCount` 是 inserted+updated 的子集不是加法项);
|
|
- 文件解析失败现在返回业务错误码 **100001**(原来静默返回成功 0 行)。
|
|
4. **包络字段勘误(纯文档,后端行为没变)**:响应包络真实字段是 **`message`** 不是文档原来写的 `msg`(完整真形 `{code, data, message, success, traceId}`);如前端有按 `res.msg` 取提示文案的代码请自查(取不到值)。注意:**导入出参 errors/warnings 行内的 `msg` 是真实字段名,不受影响**。
|
|
|
|
## 1. 列表/详情新增字段
|
|
|
|
| 接口 | 新字段 | 说明 |
|
|
|------|--------|------|
|
|
| `GET /admin/fleet/vehicles/page` | `primaryDriverId`(String)/`primaryDriverName`/`primaryDriverLicenseType` | 常驻司机,无=null;司机未填准驾时也是 null(不会给空串) |
|
|
| `GET /admin/fleet/vehicles/{vehicleId}` | `typeKey`(大类Key,原来文档有代码没返)/`primaryDriverLicenseType`/`primaryDriverYears`(驾龄·年) | 详情主司机块徽章数据源;驾龄未填=null(不会给 0) |
|
|
|
|
## 2. 批量导入出参示例(测试服实测)
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"data": {
|
|
"totalRows": 1, "insertedCount": 1, "updatedCount": 0, "errorCount": 0,
|
|
"errors": [],
|
|
"warnedCount": 1,
|
|
"warnings": [ { "row": 2, "plate": "蒙A·T7777", "field": "insureDue", "msg": "保险不足 30 天" } ]
|
|
},
|
|
"message": "成功"
|
|
}
|
|
```
|
|
|
|
## 3. 契约细节订正(文档侧,代码行为如此)
|
|
|
|
- §2.2 详情「车辆不存在」错误码是 **600110**(原文档误写 404001,前端按 404001 匹配永不命中);
|
|
- `seats` 恒随车型冗余(入参不收、传了忽略;型号座位数变更自动回刷已绑车辆)——原文档「可选,默认取自车型」有歧义;
|
|
- 编辑(§2.4)入参必须带 `vehicleModelId`(原示例漏了,照抄会 400);附件保留项(带 id)可以不传 `mimeType` 了(原来会 400);**新增附件 mimeType 必填且白名单 jpeg/png/webp/pdf,不命中报 601005**(新校验);
|
|
- 附件混插排序修复:编辑时新图插在保留图前面,落库顺序现在与入参数组顺序一致(原来新增项会被挤到末尾);
|
|
- 601002/601003(类目/张数校验)确认废弃,类目走字典 `vehicle_attachment_category`;
|
|
- 600109(有未完成派单禁删)为契约先行,守卫随派单模块落地,当前删除不拦。
|
|
|
|
## 4. 文档版本
|
|
|
|
FLEET API → **v1.5.51 + v1.5.53**,文档站已同步:https://web.test.1814.love:9443/hl-docs/order-v3/api/API-SPEC-FLEET-V1.5.html(HOUSE/主文档的 msg→message 同步勘误见各自变更记录)
|