hl-api-changelog/changelogs-v2/2026-06/08_3598_附件类目改数据字典驱动-修改接口-管理后台.md

车辆/司机附件「类目」改数据字典驱动 + 后端撤类目/张数校验 — 修改接口 — 管理后台

变更类型：🟡 增强（类目改字典驱动）+ ⚠️ 行为变更（后端撤校验，改前端限制） 端类型：管理后台 日期：2026-06-08 服务：hl-fleet-service + hl-user-service（字典种子）

---

1. 背景

车辆档案 / 司机档案的「附件类目」（category）过去是后端硬编码枚举（含每类目张数上限），后端做两道校验：类目非法（601002）、张数超上限（601003）。

本次改为数据字典驱动：类目列表 + 各类目张数上限都放字典，前端从字典接口拉取后渲染上传区块、并由前端按字典里的上限限制单类目上传张数。后端不再校验类目合法性、不再校验张数上限（601002 / 601003 已废弃）。

---

2. 变更清单

#	变更	说明
1	类目改字典	车辆 6 类、司机 8 类改为字典 vehicle_attachment_category / driver_attachment_category，可后台增减
2	张数上限放字典 remark	每个类目的上限写在字典项的 remark（纯数字），前端读取并限制单类目张数
3	⚠️ 后端撤校验	后端不再校验类目合法性 + 张数上限，601002 / 601003 废弃（不再抛出）
4	上传区块前端渲染	前端从字典动态渲染上传区块（类目名 = dictLabel，提交值 = dictValue）

---

3. 字典怎么取（通用接口，已有）

项目	值
方法 / 路径	GET /admin/dict/data/{dictType}
认证	Bearer Token（管理后台 JWT）
取上限	字典项的 remark 字段 = 该类目张数上限（字符串数字，parseInt）

3.1 车辆附件类目 vehicle_attachment_category

GET /admin/dict/data/vehicle_attachment_category

dictValue	dictLabel	remark(张数上限)
exterior	外观照	6
interior	内饰照	3
insurance	保险单据	2
inspection	年检单据	2
operation_license	营运证	2
other	其他	5

3.2 司机附件类目 driver_attachment_category

GET /admin/dict/data/driver_attachment_category

dictValue	dictLabel	remark(张数上限)
id_card	身份证	2
driver_license	驾驶证	2
portrait	肖像照	2
health_cert	健康证	2
training_cert	培训证书	5
award	荣誉奖励	5
qualification	从业资格证	3
other	其他	5

响应示例（节选）：

{
  "code": 200, "success": true,
  "data": [
    {"dictValue": "exterior", "dictLabel": "外观照", "sortOrder": 10, "status": "ACTIVE", "remark": "6"},
    {"dictValue": "interior", "dictLabel": "内饰照", "sortOrder": 20, "status": "ACTIVE", "remark": "3"}
  ]
}

---

4. 保存接口（不变）

车辆 POST/PUT /admin/fleet/vehicles、司机 POST/PUT /admin/fleet/drivers 的 attachments[].category 字段：传选中类目的 dictValue（exterior / id_card …）。字段名、类型、结构全不变；后端只是不再校验该值。

---

5. 前端迁移清单

1. 上传区块改字典渲染：车辆 / 司机档案的附件上传区块改为从 /admin/dict/data/vehicle_attachment_category（或 driver）拉类目动态渲染，dictLabel 作区块标题、dictValue 作提交 category。
2. 张数限制读字典：每个类目允许上传的最大张数 = 该字典项 remark（parseInt(remark)）。前端负责限制（达上限禁止再选/上传）；后端不再拦。
3. 类目可后台增减：运营在「系统管理 → 字典管理」新增类目，前端会自动多出一个上传区块（无需改前端代码），新类目上限同样读其 remark。
4. 错误码：601002 / 601003 已废弃，后端不再返回；前端如有针对这两个码的提示分支可移除。
5. 详情分组：司机详情 attachments 仍按 8 个固定字段分组返回（idCard/driverLicense/portrait/healthCert/trainingCert/award/qualification/other），不变。

---

6. 关联

项目	信息
PR	wx/HL#3598
部署	已部署测试服并实测：两字典经网关 9443 各返 6 / 8 项（含 remark 上限）
字典维护	系统管理 → 字典管理，type=vehicle_attachment_category / driver_attachment_category
后端负责人	wx