131 行
5.2 KiB
Markdown
131 行
5.2 KiB
Markdown
# 车辆档案「车队归属 / 使用性质」改数据字典下拉 — 修改接口 — 管理后台
|
||
|
||
> 变更类型：🟡 增强（字段取值改字典驱动，字段名/类型不变）
|
||
> 端类型：管理后台
|
||
> 日期：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 |
|