# 【新功能·H5 + 管理后台】司机入职采集全面对齐档案：车辆/司机补字段 + 附件类目（前端待接）

> 端：H5 司机入职登记 + hl-ui 管理后台（车务·待审核·审核抽屉/编辑档案）| 服务：hl-fleet-service | PR #3913 + #3914 / 工单 #3912 | 已合并 dev-v3 + 部署测试服双实例 | 2026-06-17

## ⚠️ 关键说明

H5 入职采集的字段/附件远少于车辆/司机档案支持项，车管审核/编辑时要重敲。本期后端把缺口补齐，**需前端在 H5 加输入/上传位 + 审核抽屉/编辑档案做预填回显**。

## 1. H5 第 4 步「行驶证/自带车」需新增（前端要加）

提交接口 `POST /mp/fleet/onboard/submit/new` 的 `vehicle` 块**新增字段**：

| 字段 | 类型 | 来源 | 说明 |
|------|------|------|------|
| `vin` | string | 行驶证 OCR | 车架号（已在上一期 #3907 加） |
| `regDate` | string(date) | 行驶证 OCR | 注册日期 |
| `insureDue` | string(date) | 手填 | 保险到期日（行驶证无，司机手填） |
| `regCertUsage` | string | 行驶证 OCR + 司机改 | 使用性质，**按字典 `vehicle_reg_cert_usage` 取值：营运租赁/非营运/旅游客运** |
| `regCertNo` | string | 行驶证 OCR | 行驶证号/档案编号 |
| `regCertOwner` | string | 行驶证 OCR | 所有人 |
| `insuranceUrls` | string[] | 上传 | 保险单据照 |
| `inspectionUrls` | string[] | 上传 | 年检单据照 |
| `operationLicenseUrls` | string[] | 上传 | 营运证照 |
| `otherUrls` | string[] | 上传 | 其他车辆附件 |

- **行驶证 OCR 接口现多返回** `regDate / regCertUsage / regCertNo / regCertOwner`（连同 vin），请前端 OCR 后自动带入对应输入框。
- **使用性质映射**：OCR 原文常是「营运」「非营运」，请前端按字典 `vehicle_reg_cert_usage`（营运租赁/非营运/旅游客运）映射成下拉选项再提交。
- **营运证必传**：使用性质为营运类（非「非营运」且非空）时，`operationLicenseUrls` 必须有图，否则提交返 **`600314` 营运车必须上传营运证**。非营运/未填则选填。

## 2. H5 司机证件步骤需新增 5 类附件上传（前端要加）

`submit/new` 顶层**新增字段**（多图 URL 数组，对齐车务档案 `driver_attachment_category` 字典）：

| 字段 | 类目 | 档案张数上限 |
|------|------|------|
| `healthCertUrls` | 健康证 health_cert | 2 |
| `trainingCertUrls` | 培训证书 training_cert | 5 |
| `awardUrls` | 荣誉奖励 award | 5 |
| `qualificationUrls` | 从业资格证 qualification | 3 |
| `driverOtherUrls` | 其他 other | 5 |

均选填；审核通过后后端自动搬进司机档案附件区（编辑司机抽屉可见）。

## 3. 审核详情接口新增回显字段（前端用来预填审核抽屉/编辑档案）

`GET /admin/fleet/drivers/pending/{pendingId}`：

- `vehicle` 块**新增**：`regDate / insureDue / regCertUsage / regCertNo / regCertOwner` + `insuranceUrls / inspectionUrls / operationLicenseUrls / otherUrls`（+ 上一期已加 `vin / suggestedModelId / suggestedModelName / suggestedSeats`）。
- 顶层**新增** `driverAttachments` 块：`healthCertUrls / trainingCertUrls / awardUrls / qualificationUrls / driverOtherUrls`。
- 顶层**新增** `modeLabel`（新招/续签）、`reviewStatusLabel`（待审核/已通过/已驳回）——与列表项口径一致，审核抽屉不必再自行映射码值。

请前端审核抽屉/编辑档案据此预填全部回显字段。

## 4. 审核通过的效果（后端已自动，无需前端）

- 车辆档案落 注册日期/保险到期/使用性质/行驶证号/所有人 + 保险/年检/营运证/其他附件。
- 司机档案落 健康证/培训证书/荣誉奖励/从业资格证/其他附件。

## 验证

- 后端全量单测 + 集成测试 **820 绿**；7 维度对抗审查 workflow 14 条确认问题已全部修正。
- 部署测试服双实例 boot 成功（含 Flyway `V20260617_002` 14 列迁移，真库 success=1；JSON 列用 TEXT 避免行宽超限）。
- 审核详情接口过网关 + 真 admin token 实测正常。
- 注：**前端 H5 输入/上传 + 审核抽屉预填接好前**，这些新字段/附件不会有值——请前端配合本期接上。
