# 【修改·管理后台】车辆档案:列表新增常驻司机字段、详情补 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 同步勘误见各自变更记录)
