From 1a326b0b12d0ee5c09a009c0b1290ea8fd085b02 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 11 Jun 2026 12:03:13 +0800 Subject: [PATCH] =?UTF-8?q?changelog:=20=E8=BD=A6=E8=BE=86/=E5=8F=B8?= =?UTF-8?q?=E6=9C=BA=E5=AF=BC=E5=85=A5=E6=A8=A1=E6=9D=BF=E4=B8=8B=E8=BD=BD?= =?UTF-8?q?=C3=972=20+=20=E8=BD=A6=E8=BE=86=E5=AF=BC=E5=85=A5=E5=B8=B8?= =?UTF-8?q?=E9=A9=BB=E5=8F=B8=E6=9C=BA=E5=88=97=20(PR=20#3687)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...入模板下载与常驻司机导入-新增接口-管理后台.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 changelogs-v2/2026-06/11_3687_车辆司机导入模板下载与常驻司机导入-新增接口-管理后台.md diff --git a/changelogs-v2/2026-06/11_3687_车辆司机导入模板下载与常驻司机导入-新增接口-管理后台.md b/changelogs-v2/2026-06/11_3687_车辆司机导入模板下载与常驻司机导入-新增接口-管理后台.md new file mode 100644 index 0000000..1871404 --- /dev/null +++ b/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,,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