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

> 变更类型：🟡 增强（类目改字典驱动）+ ⚠️ 行为变更（后端撤校验，改前端限制）
> 端类型：管理后台
> 日期：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 |

**响应示例**（节选）：

```json
{
  "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 | https://git.1814.love:8443/wx/HL/pulls/3598 |
| 部署 | 已部署测试服并实测：两字典经网关 9443 各返 6 / 8 项（含 remark 上限） |
| 字典维护 | 系统管理 → 字典管理，type=`vehicle_attachment_category` / `driver_attachment_category` |
| 后端负责人 | wx |
