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

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

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

「下载模板」按钮有后端接口了(原口径「前端静态资源承载模板」作废):
- GET /admin/fleet/vehicles/import/template → 车辆导入模板.xlsx
- GET /admin/fleet/drivers/import/template → 司机导入模板.xlsx
- 返回 .xlsx 文件流(Content-Disposition: attachment,不是 Result JSON 包络),axios 请用 responseType: 'blob' + Authorization 头,下载后另存。
模板是双 sheet:Sheet1 数据页只有表头行(与后端解析逐字一致,提示用户勿改表头;特意不放示例行,防止示例数据被原样导入);Sheet2「填写说明」逐列列出必填/格式/字典取值,前端无需再自造说明文案。
车辆导入新增第 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 导入后,车辆详情:

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

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

{ "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

2.8 KiB 原始文件 Blame 文件历史 Unescape Escape