changelog: 车辆/司机导入模板下载×2 + 车辆导入常驻司机列 (PR #3687)

changelogs-v2/2026-06/11_3687_车辆司机导入模板下载与常驻司机导入-新增接口-管理后台.md

@@ -0,0 +1,51 @@
+# 【新增·管理后台】车辆/司机批量导入:新增「下载导入模板」接口 ×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