---
schema: "hl-changelog/v2"
ticket: "6204"
title: "司机档案新增个人能力资产与装备字段"
consumer: "admin"
author: "wx(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "be171bf7"
target_release: ""
verified_at: "2026-08-23"
status_note: "已合并 dev-v3 并部署测试服，经网关 API 实测 assets/equipments 往返一致"
updated_at: "2026-08-23"
base: "dev-v3"
---

# 司机档案：新增个人能力资产与装备字段

> **PR**: [#6214](https://git.1814.love:8443/wx/HL/pulls/6214)
> **服务**: hl-fleet-service (8087/8187)
> **作者**: wx
> **更新时间**: 2026-08-23

---

## 变更概述

司机档案新增两个结构化字段，类目由数据字典驱动，后续新增类目只加字典数据，零代码。

### 数据字典（前端需动态读取）

| 字典类型 | 字典值 | 中文标签 | remark（采集指引） |
|----------|--------|----------|-------------------|
| `driver_asset_type` | `drone` | 无人机 | `model` — 采集设备型号 |
| `driver_asset_type` | `camera` | 专业摄影机 | `model` — 采集设备型号 |
| `driver_asset_type` | `tour_guide_cert` | 导游证 | `certNo` — 采集证号 |
| `driver_equipment` | `kite` | 风筝 | 空 — 仅有无 |
| `driver_equipment` | `football` | 足球 | 空 — 仅有无 |
| `driver_equipment` | `camping_chair` | 露营椅 | 空 — 仅有无 |

**前端获取方式**: `GET /admin/dict/data/{type}` — `driver_asset_type` 和 `driver_equipment`

---

## 变更接口

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 新增司机档案 | POST | `/admin/fleet/drivers` | 请求体新增字段 | assets/equipments 可选 |
| 2 | 编辑司机档案 | PUT | `/admin/fleet/drivers/{driverId}` | 请求体新增字段 | assets/equipments 可选 |
| 3 | 查询司机档案详情 | GET | `/admin/fleet/drivers/{driverId}` | 响应体新增字段 | assets/equipments |
| 4 | 分页查询司机列表 | GET | `/admin/fleet/drivers/page` | 响应体新增字段 | assets/equipments |

---

## 接口详情

### 新增 VO: `DriverAssetVO`

响应和请求中的 `assets` 数组元素：

| 字段 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|
| `assetType` | String | ✅ | 长度 ≤ 32 | 资产类型编码，来自字典 `driver_asset_type`（drone/camera/tour_guide_cert） |
| `model` | String | ❌ | 长度 ≤ 64 | 设备型号，字典 remark=model 时采集 |
| `certNo` | String | ❌ | 长度 ≤ 64 | 证号，字典 remark=certNo 时采集 |

### 1. 新增司机档案 `POST /admin/fleet/drivers`

#### 请求体新增字段

```json
{
  "assets": [
    { "assetType": "drone", "model": "DJI Mavic 3" },
    { "assetType": "tour_guide_cert", "certNo": "L-2026-001" }
  ],
  "equipments": ["kite", "football"]
}
```

#### 响应示例（新增字段部分）

```json
{
  "code": 200,
  "data": {
    "id": "2091464705498394626"
  },
  "success": true
}
```

### 2. 编辑司机档案 `PUT /admin/fleet/drivers/{driverId}`

#### 请求体新增字段

```json
{
  "assets": [
    { "assetType": "drone", "model": "DJI Mavic 3 Pro" }
  ],
  "equipments": ["kite", "football", "camping_chair"]
}
```

**编辑语义**: 全量覆盖。不传 assets/equipments 保持原值，传空数组 `[]` 清空。

### 3. 查询司机档案详情 `GET /admin/fleet/drivers/{driverId}`

#### 响应新增字段

```json
{
  "code": 200,
  "data": {
    "assets": [
      { "assetType": "drone", "model": "DJI Mavic 3", "certNo": null },
      { "assetType": "tour_guide_cert", "model": null, "certNo": "L-2026-001" }
    ],
    "equipments": ["kite", "football"]
  },
  "success": true
}
```

### 4. 分页查询司机列表 `GET /admin/fleet/drivers/page`

#### 响应新增字段（列表项同详情）

```json
{
  "code": 200,
  "data": {
    "list": [
      {
        "assets": [
          { "assetType": "drone", "model": "DJI Mavic 3", "certNo": null }
        ],
        "equipments": ["kite", "football"]
      }
    ]
  },
  "success": true
}
```

---

## 边界行为

- **空态**: 未填写时返回 `assets: []`, `equipments: []`
- **非法字典值**: 提交非法 assetType/equipments → 400（错误码 100001）
- **model/certNo 非必填**: 后端只校验 type 合法性，扩展键原样存储不强制

---

## 前端接入提示

- **表单选项**: 动态调 `GET /admin/dict/data/driver_asset_type` 和 `GET /admin/dict/data/driver_equipment` 渲染
- **输入框控制**: 根据字典 remark 决定渲染什么输入框：
  - `remark=model` → 设备型号输入框
  - `remark=certNo` → 证号输入框
  - 空 → 仅 checkbox/switch（有无）
- **导游证照片**: 继续走现有 `qualification` 附件类目上传，不重复建设
- **H5 司机入驻/续签** 同样支持 assets/equipments 字段，接口另见 changelog（如有）

---

## 测试环境已验证

```
POST /admin/fleet/drivers   → 200 + assets/equipments 写入成功 ✓
GET  /admin/fleet/drivers/{id} → 200 + assets/equipments 回读一致 ✓
```

验证司机: `driverId=2091464705498394626`（已清理）

---

## 关联 / 联系人

### 链接

- **Issue**: [#6204](https://git.1814.love:8443/wx/HL/issues/6204)
- **PR**: [#6214](https://git.1814.love:8443/wx/HL/pulls/6214)
- **Merge commit**: [f2a02ee3a](https://git.1814.love:8443/wx/HL/commit/f2a02ee3a8b2c43c91a892fac253d4e085fbd63c)

### 联系人

- **后端负责人**: @wx