docs(changelog): #6204 司机档案新增设备与车上装备字段

changelogs-v2/2026-08/23_6204_司机档案新增设备与车上装备字段-新增接口-管理后台.md

@@ -0,0 +1,194 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6204"
+title: "司机档案新增个人能力资产与装备字段"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+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