941e3453d5
- 新增 POST /mp/traveler/ocr：支持身份证/护照/港澳通/台湾通行证 - 下线 POST /mp/user/ocr/idcard（微信 OCR 不让用了） - 前端需替换老接口调用 + 增加证件类型选择
122 行
4.1 KiB
Markdown
122 行
4.1 KiB
Markdown
# 小程序出行人接入阿里云 OCR 多证件识别，下线微信 OCR
|
||
|
||
**日期**：2026-04-20
|
||
**PR**：#1039
|
||
**Issue**：#1036
|
||
**影响**：小程序端「出行人录入」模块
|
||
|
||
---
|
||
|
||
## 业务变化
|
||
|
||
微信官方 OCR 接口不再允许使用。出行人证件 OCR 后端切换到阿里云「个人证照识别」SDK，并扩展支持**4 种证件**：
|
||
|
||
| 证件 | idCardType | 后端走的 SDK |
|
||
|---|---|---|
|
||
| 身份证 | `ID_CARD` | RecognizeIdcard |
|
||
| 护照 | `PASSPORT` | RecognizePassport |
|
||
| 港澳通行证 | `HK_MACAU_PASS` | RecognizeExitEntryPermitToHK |
|
||
| 台湾通行证 | `TAIWAN_PASS` | RecognizeExitEntryPermitToHK（同接口，签发格式一致） |
|
||
|
||
军官证 / 其他证件类型直接返回 400「不支持的证件类型」，前端做好容错。
|
||
|
||
---
|
||
|
||
## ❌ 下线接口
|
||
|
||
### `POST /mp/user/ocr/idcard`（微信 OCR 老接口）
|
||
|
||
**下线原因**：微信 OCR 接口权限被关闭。
|
||
|
||
**前端必须在本次同步内去掉该接口调用**。
|
||
|
||
---
|
||
|
||
## ✅ 新增接口
|
||
|
||
### `POST /mp/traveler/ocr` —— 多证件 OCR 识别
|
||
|
||
**用途**：小程序出行人录入页，用户上传证件照到 OSS 后，用 OSS URL 调此接口识别，返回结构化字段**供用户确认后再手动调** `POST /user/traveler` **保存**（OCR 不直接落库）。
|
||
|
||
**请求** `Content-Type: application/json`：
|
||
|
||
```json
|
||
{
|
||
"idCardType": "ID_CARD",
|
||
"ossUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/xxx/id-front.jpg"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| idCardType | string | 是 | 证件类型。仅支持 `ID_CARD` / `PASSPORT` / `HK_MACAU_PASS` / `TAIWAN_PASS`，其余直接返回 400 |
|
||
| ossUrl | string | 是 | 证件图 OSS 公开地址（走现有 `POST /mp/file/upload` 拿） |
|
||
|
||
**响应**（`TravelerOcrRespVO`，所有字段均为字符串/日期，**按证件类型可能为 null**）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"name": "张三",
|
||
"gender": "男",
|
||
"nationality": "汉",
|
||
"nationalityText": "中国 / CHN",
|
||
"birthday": "1990-01-01",
|
||
"idCardNo": "110101199001011234",
|
||
"address": "北京市朝阳区...",
|
||
"validityStart": "2020-01-01",
|
||
"validityEnd": "2040-01-01",
|
||
"issueAuthority": "北京市公安局朝阳分局",
|
||
"issuePlace": null
|
||
}
|
||
}
|
||
```
|
||
|
||
字段适用表：
|
||
|
||
| 字段 | 身份证 | 护照 | 港澳通 | 台湾通 |
|
||
|---|---|---|---|---|
|
||
| name | ✔️ | ✔️ | ✔️ | ✔️ |
|
||
| gender | ✔️ | ✔️ | ✔️ | ✔️ |
|
||
| nationality | 民族（汉） | 国籍英文（CHN） | — | — |
|
||
| nationalityText | — | 国籍中文（中国） | — | — |
|
||
| birthday | ✔️ | ✔️ | ✔️ | ✔️ |
|
||
| idCardNo | 身份证号 | 护照号 | 通行证号 | 通行证号 |
|
||
| address | ✔️（身份证住址） | — | — | — |
|
||
| validityStart / validityEnd | ✔️ | ✔️ | ✔️ | ✔️ |
|
||
| issueAuthority | — | ✔️ | ✔️ | ✔️ |
|
||
| issuePlace | — | ✔️ | — | — |
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| HTTP | code | message | 原因 |
|
||
|---|---|---|---|
|
||
| 200 | 200 | success | 识别成功 |
|
||
| 200 | 400 | 不支持的证件类型 | idCardType 不在上面 4 种之内 |
|
||
| 200 | 400 | 参数校验失败 | ossUrl 不是 http/https 或 idCardType 空 |
|
||
| 200 | 500 | 身份证识别失败，请重试 | 阿里云 SDK 异常（图片质量/网络/额度等），失败已记审计 |
|
||
|
||
**建议前端**：调用前做**图片压缩**（建议 ≤ 3MB）；失败后提示用户"重新拍照"，不要自动重试（会多扣配额）。
|
||
|
||
---
|
||
|
||
## 前端改造 checklist
|
||
|
||
- [ ] 出行人录入页 OCR 入口替换为 `POST /mp/traveler/ocr`
|
||
- [ ] 增加证件类型选择（4 个），默认 `ID_CARD`
|
||
- [ ] 老接口 `/mp/user/ocr/idcard` 调用代码全部删除
|
||
- [ ] OCR 返回字段渲染到表单输入框里，**让用户确认/编辑后**再提交，不要直接调保存
|
||
- [ ] 根据 `idCardType` 决定展示哪些字段（护照多个 `nationalityText`，身份证多个 `address`）
|
||
|
||
---
|
||
|
||
## 其它
|
||
|
||
- 免费额度：每类证件 200 次/月，超出按量付费（阿里云账单）
|
||
- QPS：默认 10
|
||
- 审计日志（`traveler_ocr_log`）仅后端使用，前端不感知
|