From 6657de14049ef089c7b24cb66ce60afc2b9bfd00 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 23 Aug 2026 10:21:57 +0000 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#6204=20=E5=8F=B8=E6=9C=BA?= =?UTF-8?q?=E6=A1=A3=E6=A1=88=E6=96=B0=E5=A2=9E=E8=AE=BE=E5=A4=87=E4=B8=8E?= =?UTF-8?q?=E8=BD=A6=E4=B8=8A=E8=A3=85=E5=A4=87=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...案新增设备与车上装备字段-新增接口-管理后台.md | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 changelogs-v2/2026-08/23_6204_司机档案新增设备与车上装备字段-新增接口-管理后台.md diff --git a/changelogs-v2/2026-08/23_6204_司机档案新增设备与车上装备字段-新增接口-管理后台.md b/changelogs-v2/2026-08/23_6204_司机档案新增设备与车上装备字段-新增接口-管理后台.md new file mode 100644 index 00000000..56419ce9 --- /dev/null +++ b/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 \ No newline at end of file