# 【行为打通·H5】司机入职「AI 自动识别」从假数据桩换成真阿里云 OCR（身份证/驾驶证/行驶证）

> 端：hl-ui H5（司机自助入职 → 拍证件 AI 识别）| 服务：hl-fleet-service h5 | PR #3854 / 工单 #2797 | 已合并 dev-v3 + 部署测试服 + 真图实测 | 2026-06-16

## ⚠️ 关键说明

司机入职 H5 的「拍证件 · AI 自动识别」`POST /app/h5/driver-onboard/ocr/{step}` 原来是**桩**——无论上传什么图，永远返回固定假数据（蒙A-12345 / 丰田汉兰达 / 150102199001011234）。现已接**真阿里云 OCR**，按上传的真实证件图识别。

**接口路径 / 入参 / 出参结构（OcrResultVO）完全不变**，前端无需改调用方式。变化只在「返回的是真识别值」。

## 1. 各步骤现在能识别到的字段（真图实测）

| step | 识别字段 | 实测（真图） |
|---|---|---|
| `id-card` 身份证 | name / idCard / gender / nation / issuedBy | 姓名/身份证号/性别(1男2女)/民族/签发机关 |
| `license` 驾驶证 | licenseNo / licenseClass / licenseExpire | 证号 / 准驾车型(如 C1D) / 有效期至 |
| `reg-cert` 行驶证 | plate / model | 车牌(京N99FF7) / 品牌型号(吉利美日牌MR7002BEV03) |

## 2. 识别不到、需用户手填的字段（前端注意）

- **行驶证 `annualInspectDate`（年检到期日）= null**：年检/检验记录在**行驶证副页**，正页识别接口不含此字段 → 该输入框请保持**可手填**，不要因 OCR 返 null 就当失败。
- **行驶证 `seats`（核定载客）= null**：行驶证正页不含核定载客（在副页），同样需手填。
- 其余识别到的字段建议**回填后仍允许用户修改**（OCR 偶有误差）。

## 3. 识别失败的表现（前端容错）

- 真识别失败（图太糊/非对应证件/服务波动）返回**业务错误码**：身份证 `600305` / 驾驶证 `600306` / 行驶证 `600312`，message=「xx识别失败，请重拍或手动填写」。
- 前端遇这些码：提示用户**重拍或手动填写**即可，**不要再用旧的假数据兜底**。

## 验证（测试服真图实测）

- 驾驶证真图 → `C1D` / 有效期 2021-01-12 ✅
- 行驶证真图 → 京N99FF7 / 吉利美日牌MR7002BEV03 ✅
- 身份证识别同样可用 ✅

> 注：测试环境阿里云「车辆物流识别」已开通（含驾驶证+行驶证识别）。正式环境上线前需在正式阿里云账号同样开通并配置，否则会回退到桩。
