# 小程序出行人接入阿里云 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`）仅后端使用，前端不感知