# 【新增·管理后台】车辆/司机批量导入:新增「下载导入模板」接口 ×2,车辆导入支持直接绑常驻司机

> 存放目录: changelogs-v2/2026-06/
> 涉及服务: hl-fleet-service(8087)
> PR: #3687(已合并 dev-v3,**测试服已部署并 API 实测通过**) | 无关联工单(wx 2026-06-11 拍定) | 日期: 2026-06-11
> 影响范围: 管理后台**车辆档案**与**司机档案**的批量导入功能

## ⚠️ 关键说明(前端必看 3 点)

1. **「下载模板」按钮有后端接口了**(原口径「前端静态资源承载模板」作废):
   - `GET /admin/fleet/vehicles/import/template` → 车辆导入模板.xlsx
   - `GET /admin/fleet/drivers/import/template` → 司机导入模板.xlsx
   - **返回 .xlsx 文件流**(`Content-Disposition: attachment`,**不是 Result JSON 包络**),axios 请用 `responseType: 'blob'` + Authorization 头,下载后另存。
2. **模板是双 sheet**:Sheet1 数据页只有表头行(与后端解析逐字一致,提示用户勿改表头;特意不放示例行,防止示例数据被原样导入);Sheet2「填写说明」逐列列出必填/格式/字典取值,前端无需再自造说明文案。
3. **车辆导入新增第 12 列「常驻司机手机号」**(可选):按手机号反查司机直接绑定常驻(严格 1:1)。司机不存在 → 该行报错「常驻司机手机号未找到对应司机」;司机已是别车常驻 → 该行报错(605022 文案);**更新已有车时该列空白=保持原绑定(不会解绑)**。

## 1. 接口契约

| 接口 | 方法 | 返回 |
|---|---|---|
| `/admin/fleet/vehicles/import/template` | GET | xlsx 文件流(12 列表头 + 填写说明 sheet) |
| `/admin/fleet/drivers/import/template` | GET | xlsx 文件流(15 列表头 + 填写说明 sheet) |

实测响应头(测试服):

```
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment;filename="%E8%BD%A6%E8%BE%86%E5%AF%BC%E5%85%A5%E6%A8%A1%E6%9D%BF.xlsx"
```

## 2. 车辆导入带常驻司机实测(测试服)

CSV 行 `蒙A-TPL99,<modelId>,own,company,,,,,,,营运租赁,13977665544` 导入后,车辆详情:

```json
{ "plate": "蒙A-TPL99", "primaryDriverId": "2064920199034810370", "primaryDriverName": "模板测试司机" }
```

反例(手机号无司机)实测:

```json
{ "errorCount": 1, "errors": [ { "row": 2, "plate": "蒙A-TPL98", "msg": "常驻司机手机号未找到对应司机: 13900009999" } ] }
```

## 3. 顺带勘误

司机导入表头「性别」列此前文档/Swagger 误写成「性别(男/女/未知)」——**实际解析 key 就是「性别」两个字**,照旧写法该列整列取不到值。以模板端点下发的表头为准(模板与解析同源,不会再漂移)。

## 4. 文档

FLEET API → **v1.5.56**(§2.6a/§3.6a 新端点 + §2.6 12 列契约),文档站:https://web.test.1814.love:9443/hl-docs/order-v3/api/API-SPEC-FLEET-V1.5.html