docs(changelog): 司机入职H5 OCR换真阿里云识别 (PR #3854)

changelogs-v2/2026-06/16_司机入职H5-OCR从桩换真阿里云识别-身份证驾驶证行驶证-小程序H5.md

@@ -0,0 +1,36 @@
+# 【行为打通·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 ✅
+- 身份证识别同样可用 ✅
+
+> 注：测试环境阿里云「车辆物流识别」已开通（含驾驶证+行驶证识别）。正式环境上线前需在正式阿里云账号同样开通并配置，否则会回退到桩。