hl-api-changelog/changelogs-v2/2026-05/21_2812_司机详情attachments强类型化-修改接口-管理后台.md

【修改接口·管理后台】司机详情 attachments 弱类型 Map 改强类型 DriverAttachmentsVO (#2812)

PR: #2818 | 服务: hl-fleet-service | 更新时间: 2026-05-21 15:30

存放目录: changelogs-v2/2026-05/ 关联前序: 21_2791_司机档案-修改接口-管理后台.md（commit 761ca07）

---

⚠️ 关键变化（30 秒速读）

GET /admin/fleet/drivers/{driverId} 的响应字段 attachments 类型变了：

项	改前	改后
类型	Map<string, DriverAttachmentRespVO[]>（动态 key）	DriverAttachmentsVO（8 个固定字段）
前端用法	data.attachments['id_card'] 字符串访问	data.attachments.idCard 字段访问
TypeScript 类型	没有具体字段名	8 个具体字段（含类型提示）

前序 changelog 废止内容：21_2791_司机档案-修改接口-管理后台.md §3.2 详情接口 + §9 业务边界 中所有把 attachments 描述为 Map<String, List<>> 的部分已废，以本文档为准。

前端必须改动（不是兼容的）：所有 data.attachments[key] 形式的访问要改成 data.attachments.xxx 字段访问。

---

1. 接口背景

attachments 当前用 Map<String, List<DriverAttachmentRespVO>> 返回违反 HL 项目规则 [禁止弱类型返回值]：

• Swagger / TypeScript 生成的类型是 { [key: string]: DriverAttachmentRespVO[] }，没有具体字段名
• 前端 IDE 不能自动补全
• 拼错 key 编译期不报错
• 文档无法自包含描述每个类目出参

改为强类型 DriverAttachmentsVO，8 个 List 字段对应 8 个固定类目（与 DriverAttachmentCategoryEnum 严格对齐）。

---

2. 变更清单

#	方法	路径	变更类型	说明
1	GET	/admin/fleet/drivers/{driverId}	修改	响应字段 attachments 类型变化（详见 §3.1）

仅 1 个端点受影响。其余 5 个司机档案接口（page / create / update / delete / import）不受影响。

---

3. 接口详情

3.1 司机详情 — attachments 字段类型变化

GET /admin/fleet/drivers/{driverId}

改后的 attachments 字段结构

字段：DriverAttachmentsVO 对象（不再是 Map）。

字段	类型	默认	张数上限（来自 DriverAttachmentCategoryEnum）
idCard	DriverAttachmentRespVO[]	[]	2（"换证留历史"：支持正反 2 张或新旧 2 套）
driverLicense	DriverAttachmentRespVO[]	[]	2（换证留历史）
portrait	DriverAttachmentRespVO[]	[]	2（换证留历史）
healthCert	DriverAttachmentRespVO[]	[]	2
trainingCert	DriverAttachmentRespVO[]	[]	5
award	DriverAttachmentRespVO[]	[]	5
qualification	DriverAttachmentRespVO[]	[]	3
other	DriverAttachmentRespVO[]	[]	5

每个字段默认空数组（不为 null），前端无需判空，直接 .map() 渲染即可。

DriverAttachmentRespVO[] 单条项字段（不变）：

字段	类型	说明
id	string	附件 ID（Long 序列化为 String）
driverId	string	所属司机 ID
category	string	类目
sortNo	int	同类目排序（0-based）
url	string	OSS URL
mimeType	string	例 image/jpeg

改后响应示例（节选）

{
  "code": 200,
  "data": {
    "id": "1234567890123456789",
    "name": "张三",
    "...其他字段保持不变...": "...",
    "attachments": {
      "idCard": [
        { "id": "...", "driverId": "...", "category": "id_card", "sortNo": 0, "url": "https://oss/.../id-front.jpg", "mimeType": "image/jpeg" },
        { "id": "...", "driverId": "...", "category": "id_card", "sortNo": 1, "url": "https://oss/.../id-back.jpg", "mimeType": "image/jpeg" }
      ],
      "driverLicense": [
        { "id": "...", "driverId": "...", "category": "driver_license", "sortNo": 0, "url": "https://oss/.../license.jpg", "mimeType": "image/jpeg" }
      ],
      "portrait": [],
      "healthCert": [],
      "trainingCert": [],
      "award": [],
      "qualification": [],
      "other": []
    },
    "relatedOrders": [...]
  },
  "msg": "成功"
}

---

6. 枚举 / 数据字典

无新增枚举。category 字段语义和取值与前序 changelog 21_2791_司机档案-修改接口-管理后台.md §6.1 一致（8 个值），唯一差异是 API 响应不再以 category 字符串作为 key，而是用 VO 字段名（驼峰）。

类目 ↔ VO 字段对应关系：

DB / category 字段值	VO 字段（驼峰）
id_card	idCard
driver_license	driverLicense
portrait	portrait
health_cert	healthCert
training_cert	trainingCert
award	award
qualification	qualification
other	other

注意单条 DriverAttachmentRespVO.category 仍然是 id_card / driver_license 等下划线值（不变）。改的是外层分组的 key 形式。

---

7. 错误码

无变化。

---

10. 修改前后对比

10.1 字段级对比

字段	改前	改后
attachments 类型	Map<string, DriverAttachmentRespVO[]>	DriverAttachmentsVO（8 个固定 List 字段）
attachments key 形式	DB 下划线值（id_card / driver_license / portrait / ...）	VO 驼峰字段（idCard / driverLicense / portrait / ...）
类目缺失	该 key 不在 Map 里	该字段是空数组 []

10.2 前端代码对照

// 改前
const idCardAttachments = data.attachments['id_card'] ?? [];
const licenseAttachments = data.attachments['driver_license'] ?? [];

// 改后
const idCardAttachments = data.attachments.idCard;     // 不用判空
const licenseAttachments = data.attachments.driverLicense;

---

11. 影响评估

• 是否破坏向后兼容：⚠️ 是（字段类型变了，前端必须改）
• 前端是否必须同步上线：是（老前端按 Map 解析会拿到 undefined）
• 影响其他后端服务：无（DriverDetailRespVO 仅 admin 接口返回，不走 Feign）
• 影响已有数据：无（仅 API 序列化形式变化，DB 无变）

---

12. 注意事项

• 前端 workaround 清理点：
  • 改前如果前端有 const map = data.attachments; const idCard = map['id_card'] ?? []; 之类 workaround，改成 data.attachments.idCard 即可
  • 改前如果前端硬编码遍历类目（如 for (const key of ['id_card', 'driver_license'])），改成直接读 VO 字段
  • 改前如果前端有 if (map['portrait']) 判空逻辑，直接删 —— 强类型 VO 字段必非 null（默认空数组）
• 前序 changelog 描述废止：21_2791_司机档案-修改接口-管理后台.md 已发出的 attachments Map 描述以本文档为准，前序 changelog 不会修改（changelog 只追加不回写历史）

---

13. 关联 / 联系人

13.1 链接

• Issue: #2812
• PR: #2818
• Merge commit: 8c340550
• 前序 changelog（attachments Map 描述废）: 21_2791_司机档案-修改接口-管理后台.md
• 规则: HL MEMORY.md → feedback_no-map-return-type.md （禁止弱类型返回值）

13.2 联系人

• 后端负责人: @yst（腰苏图）
• 前端对接（管理后台）: 待指派