From 941e3453d5c359b882baa8af0fd41c2ba2afdb9e Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 20 Apr 2026 22:42:57 +0800
Subject: [PATCH] =?UTF-8?q?feat(traveler-ocr):=20=E5=B0=8F=E7=A8=8B?=
 =?UTF-8?q?=E5=BA=8F=E5=87=BA=E8=A1=8C=E4=BA=BA=E6=8E=A5=E5=85=A5=E9=98=BF?=
 =?UTF-8?q?=E9=87=8C=E4=BA=91=20OCR=20=E5=A4=9A=E8=AF=81=E4=BB=B6=E8=AF=86?=
 =?UTF-8?q?=E5=88=AB=EF=BC=88PR=20#1039=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 POST /mp/traveler/ocr：支持身份证/护照/港澳通/台湾通行证
- 下线 POST /mp/user/ocr/idcard（微信 OCR 不让用了）
- 前端需替换老接口调用 + 增加证件类型选择
---
 .../2026-04/2026-04-20_traveler-ocr-aliyun.md | 121 ++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 changelogs/2026-04/2026-04-20_traveler-ocr-aliyun.md

diff --git a/changelogs/2026-04/2026-04-20_traveler-ocr-aliyun.md b/changelogs/2026-04/2026-04-20_traveler-ocr-aliyun.md
new file mode 100644
index 0000000..c043c6d
--- /dev/null
+++ b/changelogs/2026-04/2026-04-20_traveler-ocr-aliyun.md
@@ -0,0 +1,121 @@
+# 小程序出行人接入阿里云 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`）仅后端使用，前端不感知