# 车辆档案「车队归属 / 使用性质」改数据字典下拉 — 修改接口 — 管理后台

> 变更类型：🟡 增强（字段取值改字典驱动，字段名/类型不变）
> 端类型：管理后台
> 日期：2026-06-08
> 服务：hl-fleet-service + hl-user-service（字典种子）

---

## 1. 背景

车辆档案（新增 / 编辑）表单里两个字段过去是写死的：
- `fleet`（车队归属）原是后端 `@Pattern` 写死枚举 own/coopA/coopB；
- `regCertUsage`（使用性质）原是纯自由文本输入框。

本次把这两个字段改为**数据字典驱动**，前端应改为**下拉选择框**，选项从通用字典接口实时拉取。这样合作车队、使用性质都能在字典后台增减，无需改代码发版。

> 字段名、类型、提交入参格式**全不变**，前端只是把输入控件换成下拉、并从字典接口取选项。

---

## 2. 变更清单

| 字段 | 位置 | 旧控件 | 新控件 | 字典 type | 存的值 |
|---|---|---|---|---|---|
| `fleet` 车队归属 | 车辆档案新增/编辑表单 | 写死下拉 own/coopA/coopB | 字典下拉 | `fleet_attribution` | dictValue（own/coopA/coopB code） |
| `regCertUsage` 使用性质 | 车辆档案新增/编辑表单 | 自由文本框 | 字典下拉 | `vehicle_reg_cert_usage` | dictValue（中文：营运租赁等） |

---

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

| 项目 | 值 |
|---|---|
| 方法 | GET |
| 路径 | `/admin/dict/data/{dictType}` |
| 认证 | Bearer Token（管理后台 JWT） |

前端渲染下拉：用 `dictValue` 作为选项的 value（提交给后端的值）、`dictLabel` 作为显示文案。已按 `sortOrder` 升序返回。

### 3.1 车队归属 `fleet_attribution`

**请求**
```
GET /admin/dict/data/fleet_attribution
Authorization: Bearer <token>
```
**响应**
```json
{
  "code": 200, "message": "成功", "success": true,
  "data": [
    {"dictValue": "own",   "dictLabel": "自有",     "sortOrder": 10, "status": "ACTIVE"},
    {"dictValue": "coopA", "dictLabel": "合作车队A", "sortOrder": 20, "status": "ACTIVE"},
    {"dictValue": "coopB", "dictLabel": "合作车队B", "sortOrder": 30, "status": "ACTIVE"}
  ]
}
```

### 3.2 使用性质 `vehicle_reg_cert_usage`

**请求**
```
GET /admin/dict/data/vehicle_reg_cert_usage
Authorization: Bearer <token>
```
**响应**
```json
{
  "code": 200, "message": "成功", "success": true,
  "data": [
    {"dictValue": "营运租赁", "dictLabel": "营运租赁", "sortOrder": 10, "status": "ACTIVE"},
    {"dictValue": "非营运",   "dictLabel": "非营运",   "sortOrder": 20, "status": "ACTIVE"},
    {"dictValue": "旅游客运", "dictLabel": "旅游客运", "sortOrder": 30, "status": "ACTIVE"}
  ]
}
```

> 使用性质的 value=label（都是中文），照抄行驶证「使用性质」栏；车队归属 value 是英文 code、label 是中文，**提交给保存接口的是 dictValue（own/coopA/coopB），展示用 dictLabel**。

---

## 4. 保存接口入参（不变，仅举例）

车辆新增 `POST /admin/fleet/vehicles` / 编辑 `PUT /admin/fleet/vehicles/{vehicleId}`，body 里 `fleet` 传选中的 dictValue、`regCertUsage` 传选中的 dictValue：

```json
{
  "plate": "蒙A-66666",
  "vehicleModelId": "...",
  "fleet": "own",
  "regCertUsage": "营运租赁",
  "...": "..."
}
```

---

## 5. 前端迁移清单

1. **车队归属**：输入控件改为下拉，选项 `GET /admin/dict/data/fleet_attribution`；提交 `fleet` = 选中项 `dictValue`；列表/详情回显时用 `dictValue` 在字典里查 `dictLabel` 显示（也可直接缓存该字典做映射）。
2. **使用性质**：自由文本框改为下拉，选项 `GET /admin/dict/data/vehicle_reg_cert_usage`；提交 `regCertUsage` = 选中项 `dictValue`（中文）。
3. **存量数据兼容**：历史车辆的 `fleet`/`regCertUsage` 值与字典 value 一致（own/coopA/coopB、营运租赁等），回显正常；若遇到字典里没有的历史脏值，下拉做「未匹配则原样显示」兜底。
4. 后端已去掉写死枚举校验，**字典后台新增的合作车队（如 coopC）/ 新使用性质会自动出现在下拉**，前端无需改代码。

---

## 6. 附带：错误码提示已全中文化（无需前端改动，仅告知）

后端把车务错误提示里的英文术语换成了中文，前端若直接透传后端 `message` 展示会更友好：

| 旧提示 | 新提示 |
|---|---|
| VIN 已存在 | 车架号已存在 |
| token 无效 / 已过期 / 已使用 | 邀请链接无效 / 已过期 / 已使用 |
| OCR 识别失败 | 证件识别失败 |
| 车型大类 key 已存在 | 车型大类标识已存在 |

> 另：车辆档案错误码编号文档此前与代码不一致，已按代码对齐——「车架号已存在」实际码 **600107**（非文档旧标的 600101）、「车型不存在」**600108**。前端按 `message` 文案处理即可，一般无需硬编码错误码。

---

## 7. 关联

| 项目 | 信息 |
|---|---|
| PR | https://git.1814.love:8443/wx/HL/pulls/3596 |
| 部署 | 已部署测试服并实测：两字典经网关 9443 各返 3 项（fleet_attribution / vehicle_reg_cert_usage） |
| 字典维护 | 系统管理 → 字典管理，type=`fleet_attribution` / `vehicle_reg_cert_usage` |
| 后端负责人 | wx |