im_server/docs/third/IM-阿里云实名认证接入方案.md

IM 阿里云实名认证接入方案

1. 目标

本文记录当前 IM 实名认证能力的实现情况，以及后续接入阿里云实名认证的后端、前端和数据模型改造方案。接入目标是：用户在客户端提交实名信息后，由 IM Server 统一调用阿里云完成身份核验，客户端只感知认证状态和必要的认证跳转参数，不接触阿里云密钥、AccessKey、服务端回调密钥等敏感配置。

阿里云侧建议优先使用金融级实人认证/ID Verification（Cloudauth）能力。产品选型分两类：

1. 姓名 + 身份证二要素核验：体验最轻，适合只要求姓名和证件号一致性的场景。结果可同步或准同步返回。
2. 增强版实人认证/活体核身：服务端发起认证并获取 CertifyId，客户端通过阿里云 SDK、H5 或认证 URL 完成活体流程，服务端再查询结果或接收回调。适合强实名、风控和合规要求更高的场景。

当前产品原型只有姓名和证件号码输入页，但考虑后续安全要求，后端状态机需要兼容增强版实人认证。

2. 当前已有实现

2.1 前端对接接口

现有前后端文档已定义实名认证页面的三个核心入口：

能力	接口	当前状态
查询实名状态	GET /v1/im/security/realname	已实现
提交实名信息	POST /v1/im/security/realname/submissions	已实现
实名更正申诉	POST /v1/im/security/realname/appeals	已实现

查询接口返回：

{
  "status": "unverified",
  "can_submit": true
}

已提交或已通过时返回 submission_id、masked_name、masked_id_number、verified_at、review_reason 等字段。

提交接口要求：

• 必须携带 Authorization: Bearer <token>。
• 必须携带 Idempotency-Key，服务端根据用户、租户和幂等键生成 submission_id。
• Body 目前为：

{
  "name": "张三",
  "id_type": "cn_id",
  "id_number": "110101199001011234"
}

校验规则：

• name 长度 2-32 个字符。
• id_type 当前只支持 cn_id。
• id_number 当前只支持 18 位中国大陆身份证号，末位允许 X。

2.2 服务端实现

当前代码主要在以下位置：

模块	文件	说明
HTTP 路由	server/main.go	注册 /v1/im/security/realname、/realname/submissions、/realname/appeals
HTTP Handler	server/im_http.go	查询、提交、申诉逻辑
Store 接口	server/store/store.go	GetRealName、CreateRealNameSubmission、CreateRealNameAppeal
MySQL 实现	server/db/mysql/tenant_adapter.go	租户库读写实名表
类型定义	server/store/types/security.go	RealNameVerification、RealNameAppeal
内部后台查询	server/internal_admin_query_resources.go	realname-verifications 查询资源

当前实名提交成功后只落库为 pending，不会调用第三方，也没有自动审核通过。重复提交时，如果最新状态是 pending 或 verified，服务端会直接返回当前状态，避免重复创建申请。

2.3 当前数据表

租户库已有 im_realname_verifications：

字段	说明
id	自增主键
user_id	用户 ID
submission_id	实名提交 ID，幂等唯一
status	当前状态，已有逻辑使用 pending、verified、rejected、unverified
name_cipher	姓名保护存储值
id_type	证件类型
id_number_cipher	证件号保护存储值
id_number_hash	证件号哈希，用于重复身份检测
masked_name	脱敏姓名
masked_id_number	脱敏证件号
review_reason	审核原因或驳回原因
verified_at	通过时间
created_at / updated_at	创建和更新时间

租户库已有 im_realname_appeals：

字段	说明
id	雪花 ID
appeal_id	申诉 ID
user_id	用户 ID
reason	申诉原因
attachments_json	附件列表
status	申诉状态，默认 pending
review_comment	审核备注
created_at / updated_at	创建和更新时间

2.4 已记录的增强项

docs/IM-未实现后续增强项.md 和 docs/IM-需求实现情况审核报告.md 已明确：实名状态查询、提交、申诉已经具备，但缺少后台审核流转、第三方认证结果回写、审核结果通知和完整申诉处理工单。

当前缺口如下：

缺口	影响
未接第三方实名供应商	提交后长期停留 pending，无法自动通过或拒绝
缺少 provider 字段	无法区分人工审核、阿里云二要素、阿里云活体等来源
缺少第三方任务 ID	无法通过 CertifyId 或外部 request id 查询认证结果
缺少回调/查询状态机	无法安全处理异步认证完成、重试和重复通知
缺少后台审核动作	人工通过、拒绝、申诉处理还没有完整闭环
缺少结果通知	实名通过或拒绝后，还没有统一系统通知事件

3. 阿里云接入总体方案

3.0 当前联调结论

2026-09-20 已按 docs/third/三方服务依赖信息.md 中的阿里云 AccessKey 做过真实接口联调：

账号	调用接口	结果	结论
子账号 t1@1624085816137202.onaliyun.com	Id2MetaVerify	403 Forbidden.NoPermission，缺少 yundun-cloudauth:Id2MetaVerify	子账号需要 RAM 授权
主账号 AccessKey	Id2MetaVerify	业务码 410，提示“未开通服务”	当前阿里云账号尚未开通身份证二要素/ID_2META 服务

因此代码已接入真实阿里云 API，但生产可用还需要：

1. 在阿里云开通实人认证服务中的身份证二要素核验 ID_2META。
2. 给运行时使用的 RAM 子账号授权 yundun-cloudauth:Id2MetaVerify，或授予对应实人认证服务策略。
3. 在 hotgo.hg_sys_config 的 im_realname 分组写入 realname_provider=aliyun_cloudauth、aliyun_access_key_id、aliyun_access_key_secret、aliyun_region_id、aliyun_endpoint。
4. 租户 hotgo.im_tenant_config.realname_review_policy=1 后，IM Server 才会自动调用阿里云；服务未开通、权限不足或返回不一致时都会进入 manual_review。

3.1 配置来源

实名认证配置分两层：

1. 全局供应商配置：阿里云 AccessKey、Endpoint、回调密钥等服务商级参数放在 HotGo 控制库 hotgo.hg_sys_config，使用独立分组 im_realname。
2. 租户审核策略：审核方式放在 HotGo 控制库的 im_tenant_config。该策略每个租户单独控制，默认 0=不审核。

全局供应商配置：

group	key	建议值	说明
im_realname	realname_provider	aliyun_cloudauth	当前供应商
im_realname	aliyun_region_id	cn-hangzhou	阿里云地域
im_realname	aliyun_endpoint	cloudauth.aliyuncs.com	OpenAPI Endpoint，按实际产品确认
im_realname	aliyun_access_key_id	空	RAM AccessKey ID，禁止下发客户端
im_realname	aliyun_access_key_secret	空	RAM AccessKey Secret，后台脱敏展示
im_realname	aliyun_scene_id	空	实人认证场景 ID，控制台创建
im_realname	aliyun_product_code	空	如产品要求传 product code，则配置
im_realname	callback_secret	空	IM Server 校验阿里云回调的本地密钥
im_realname	result_query_interval_seconds	10	异步查询间隔
im_realname	result_query_max_attempts	30	最大查询次数
im_realname	mock_enabled	0	本地/测试环境 mock 开关

AccessKey 建议使用最小权限 RAM 子账号，只授权实人认证相关 OpenAPI。生产环境如果后续接入 KMS/Secrets Manager，hg_sys_config 中可只保存密钥引用。

租户审核策略建议扩展 hotgo.im_tenant_config：

字段	默认值	说明
realname_review_policy	0	审核方式：0=不审核，1=自动审核；自动审核失败/异常/不确定时进入人工审核
realname_provider_mode	id_card_2factor	第三方核验模式：id_card_2factor 或 smart_verify
realname_required	0	是否强制实名，影响 bootstrap.security.realname.required 和受限写操作
realname_allow_skip	1	未实名提醒是否允许跳过
realname_remind_after	24h	客户端实名提醒间隔

执行规则：

• 租户 realname_review_policy=0 时，不做第三方审核，提交实名后写入 pending，等待后台人工通过或拒绝。
• 租户 realname_review_policy=1 时，IM Server 自动调用阿里云；通过则写 verified，失败、异常或结果不确定则写 manual_review，等待后台人工复核。
• 阿里云全局配置缺失时，即使租户开启自动审核，也不得阻断系统启动；提交时返回稳定错误，或降级写入 manual_review 交给人工审核。

3.2 推荐状态机

本地实名状态建议统一为：

状态	含义	前端展示
unverified	未提交或无有效记录	可提交
pending	已创建本地申请，等待第三方或人工结果	审核中
processing	第三方认证流程已开始，等待客户端完成或服务端查询	认证中
verified	第三方或人工审核通过	已实名
rejected	第三方或人工审核拒绝	未通过，可重新提交或申诉
manual_review	第三方结果不确定，需要后台人工处理	审核中
expired	客户端未在有效期完成认证	可重新提交
failed	第三方调用失败或系统异常	可重试

对外接口可以继续兼容现有 unverified|pending|verified|rejected，把 processing/manual_review 展示为 pending，把 expired/failed 视租户策略映射为 rejected 或允许重新提交。

4. 两种接入流程

4.1 二要素核验流程

适合当前页面只提交姓名和身份证号的产品形态。

1. 客户端调用 POST /v1/im/security/realname/submissions，提交姓名、证件类型、证件号。
2. IM Server 完成本地格式校验、幂等校验、重复 pending/verified 校验。
3. IM Server 创建本地 im_realname_verifications，状态为 pending。
4. 如果租户 realname_review_policy=0，流程到此结束，等待后台人工审核。
5. 如果租户 realname_review_policy=1，IM Server 调用阿里云二要素核验 API。
6. 阿里云返回一致/不一致/无法验证。
7. IM Server 将本地状态更新为：
   • 一致：verified，写入 verified_at。
   • 不一致：进入 manual_review，由后台人工复核。
   • 无法验证或供应商异常：进入 manual_review，由后台人工复核。
8. 客户端继续调用 GET /v1/im/security/realname 获取最终状态。
9. 如接入系统通知，服务端投递 security.realname.updated。

这个模式对前端改动最小，但实名强度只覆盖姓名和证件号一致性。

4.2 增强版实人认证流程

适合要求活体、人脸和证件一致性校验的场景。

1. 客户端调用 POST /v1/im/security/realname/submissions，提交姓名、证件类型、证件号，并附带阿里云客户端 SDK 要求的 meta_info。
2. IM Server 创建本地申请，状态为 pending。
3. IM Server 调用阿里云发起认证接口，例如 InitSmartVerify 或当前产品对应的初始化接口。
4. 阿里云返回 CertifyId、认证 URL、认证 Token 或 SDK 所需参数。
5. IM Server 保存 provider_task_id=CertifyId，并把客户端需要的非敏感参数返回给前端。
6. 客户端调起阿里云 SDK、H5 或认证 URL 完成活体核身。
7. IM Server 通过以下任一方式拿最终结果：
   • 阿里云回调 IM Server。
   • IM Server 定时调用结果查询接口，例如 DescribeSmartVerify 或当前产品对应的查询接口。
8. IM Server 根据结果更新本地状态为 verified、rejected、manual_review、expired 或 failed。
9. 客户端轮询 GET /v1/im/security/realname 或接收系统通知刷新页面。

增强版模式下，客户端仍然不需要知道 AccessKey、AccessKeySecret、回调密钥等服务端凭据。客户端只使用后端返回的 certify_id、certify_url、token、expires_at 等短期认证参数。

5. 前后端接口建议

5.1 提交实名信息

保持现有接口不变：

POST /v1/im/security/realname/submissions

二要素模式请求：

{
  "name": "张三",
  "id_type": "cn_id",
  "id_number": "110101199001011234"
}

增强版模式请求可扩展：

{
  "name": "张三",
  "id_type": "cn_id",
  "id_number": "110101199001011234",
  "meta_info": "{\"zimVer\":\"...\"}",
  "return_url": "meetingim://realname/callback"
}

二要素模式响应：

{
  "submission_id": "rn_xxx",
  "status": "verified",
  "can_submit": false
}

增强版模式响应：

{
  "submission_id": "rn_xxx",
  "status": "processing",
  "provider": "aliyun_cloudauth",
  "mode": "smart_verify",
  "certify_id": "xxx",
  "certify_url": "https://...",
  "token": "短期认证参数，如产品返回",
  "expires_at": "2026-09-20T10:00:00Z"
}

5.2 查询实名状态

继续使用：

GET /v1/im/security/realname

建议扩展字段：

{
  "status": "pending",
  "display_status": "pending",
  "provider": "aliyun_cloudauth",
  "mode": "smart_verify",
  "submission_id": "rn_xxx",
  "masked_name": "张*",
  "masked_id_number": "110***********1234",
  "can_submit": false,
  "review_reason": "",
  "verified_at": null,
  "next_action": "wait"
}

next_action 建议值：

值	含义
submit	可提交
continue_provider_verify	需要继续完成阿里云认证
wait	等待结果
appeal	可申诉
none	无需操作

5.3 阿里云回调接口

建议新增：

POST /v1/im/security/realname/providers/aliyun/callback

要求：

• 只接收阿里云回调。
• 校验签名、时间戳、nonce 或本地 callback_secret。
• 根据 CertifyId/provider_task_id 幂等更新状态。
• 原始 payload 写入事件表，敏感字段脱敏或加密。

这个接口不直接暴露给客户端。

6. 数据库改造建议

6.1 扩展实名主表

建议在 im_realname_verifications 增加第三方状态字段：

ALTER TABLE im_realname_verifications
  ADD COLUMN provider VARCHAR(32) NOT NULL DEFAULT '' AFTER status,
  ADD COLUMN provider_mode VARCHAR(32) NOT NULL DEFAULT '' AFTER provider,
  ADD COLUMN provider_scene_id VARCHAR(64) NOT NULL DEFAULT '' AFTER provider_mode,
  ADD COLUMN provider_task_id VARCHAR(128) NOT NULL DEFAULT '' AFTER provider_scene_id,
  ADD COLUMN provider_request_id VARCHAR(128) NOT NULL DEFAULT '' AFTER provider_task_id,
  ADD COLUMN provider_status VARCHAR(32) NOT NULL DEFAULT '' AFTER provider_request_id,
  ADD COLUMN provider_error_code VARCHAR(64) NOT NULL DEFAULT '' AFTER provider_status,
  ADD COLUMN provider_error_message VARCHAR(256) NOT NULL DEFAULT '' AFTER provider_error_code,
  ADD COLUMN provider_result_json JSON NULL AFTER provider_error_message,
  ADD COLUMN submitted_at DATETIME(3) NULL AFTER provider_result_json,
  ADD COLUMN callback_at DATETIME(3) NULL AFTER submitted_at,
  ADD COLUMN expires_at DATETIME(3) NULL AFTER callback_at,
  ADD COLUMN manual_review_required TINYINT(1) NOT NULL DEFAULT 0 AFTER expires_at,
  ADD COLUMN version BIGINT NOT NULL DEFAULT 1 AFTER manual_review_required,
  ADD INDEX idx_im_realname_provider_task (provider, provider_task_id),
  ADD INDEX idx_im_realname_status_updated (status, updated_at);

注意：当前项目已经改为“一个租户一个库”，租户业务表中不再新增 tenant_id 字段。

6.2 新增第三方事件表

建议新增 im_realname_provider_events，用于记录回调、查询结果和异常响应，便于排查和审计：

CREATE TABLE IF NOT EXISTS im_realname_provider_events (
  id BIGINT NOT NULL AUTO_INCREMENT,
  submission_id VARCHAR(64) NOT NULL,
  user_id BIGINT NOT NULL,
  provider VARCHAR(32) NOT NULL,
  provider_task_id VARCHAR(128) NOT NULL DEFAULT '',
  event_type VARCHAR(32) NOT NULL,
  provider_status VARCHAR(32) NOT NULL DEFAULT '',
  request_id VARCHAR(128) NOT NULL DEFAULT '',
  signature_valid TINYINT(1) NOT NULL DEFAULT 0,
  payload_json JSON NULL,
  error_code VARCHAR(64) NOT NULL DEFAULT '',
  error_message VARCHAR(256) NOT NULL DEFAULT '',
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  PRIMARY KEY (id),
  INDEX idx_im_realname_events_submission (submission_id, created_at),
  INDEX idx_im_realname_events_provider_task (provider, provider_task_id, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

6.3 配置 SQL 建议

HotGo 控制库增加全局供应商配置项：

INSERT INTO hg_sys_config
  (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `remark`, `status`, `created_by`, `created_at`, `updated_at`)
SELECT 'im_realname', '实名认证 Provider', 'string', 'realname_provider', 'aliyun_cloudauth', 'aliyun_cloudauth', 11, '当前实名认证供应商', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group`='im_realname' AND `key`='realname_provider');

INSERT INTO hg_sys_config
  (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `remark`, `status`, `created_by`, `created_at`, `updated_at`)
SELECT 'im_realname', '阿里云 RegionId', 'string', 'aliyun_region_id', 'cn-hangzhou', 'cn-hangzhou', 20, '阿里云实人认证地域', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group`='im_realname' AND `key`='aliyun_region_id');

INSERT INTO hg_sys_config
  (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `remark`, `status`, `created_by`, `created_at`, `updated_at`)
SELECT 'im_realname', '阿里云 Endpoint', 'string', 'aliyun_endpoint', 'cloudauth.aliyuncs.com', 'cloudauth.aliyuncs.com', 21, '阿里云实人认证 OpenAPI Endpoint，按开通产品确认', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group`='im_realname' AND `key`='aliyun_endpoint');

INSERT INTO hg_sys_config
  (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `remark`, `status`, `created_by`, `created_at`, `updated_at`)
SELECT 'im_realname', '阿里云 AccessKey ID', 'string', 'aliyun_access_key_id', '', '', 22, '敏感配置，禁止下发客户端', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group`='im_realname' AND `key`='aliyun_access_key_id');

INSERT INTO hg_sys_config
  (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `remark`, `status`, `created_by`, `created_at`, `updated_at`)
SELECT 'im_realname', '阿里云 AccessKey Secret', 'string', 'aliyun_access_key_secret', '', '', 23, '敏感配置，后台脱敏展示，禁止下发客户端', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group`='im_realname' AND `key`='aliyun_access_key_secret');

INSERT INTO hg_sys_config
  (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `remark`, `status`, `created_by`, `created_at`, `updated_at`)
SELECT 'im_realname', '阿里云认证场景 ID', 'string', 'aliyun_scene_id', '', '', 24, '增强版实人认证场景 ID', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group`='im_realname' AND `key`='aliyun_scene_id');

INSERT INTO hg_sys_config
  (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `remark`, `status`, `created_by`, `created_at`, `updated_at`)
SELECT 'im_realname', '实名认证回调密钥', 'string', 'callback_secret', '', '', 30, 'IM Server 校验回调使用，禁止下发客户端', 1, 1, NOW(), NOW()
WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group`='im_realname' AND `key`='callback_secret');

HotGo 控制库增加租户级审核策略。以下写法用于现有库变更，正式发布时可合并到 im_tenant_config 建表 SQL：

ALTER TABLE hotgo.im_tenant_config
  ADD COLUMN realname_review_policy TINYINT(1) NOT NULL DEFAULT 0 COMMENT '实名审核策略：0不审核，1自动审核且失败转人工' AFTER max_group_members,
  ADD COLUMN realname_provider_mode VARCHAR(32) NOT NULL DEFAULT 'id_card_2factor' COMMENT 'id_card_2factor 或 smart_verify' AFTER realname_review_policy,
  ADD COLUMN realname_required TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否强制实名' AFTER realname_provider_mode,
  ADD COLUMN realname_allow_skip TINYINT(1) NOT NULL DEFAULT 1 COMMENT '未实名提醒是否允许跳过' AFTER realname_required,
  ADD COLUMN realname_remind_after VARCHAR(32) NOT NULL DEFAULT '24h' COMMENT '实名提醒间隔' AFTER realname_allow_skip;

默认值要求：

• realname_review_policy=0，新租户默认不调用阿里云，也不自动通过；提交后进入 pending，等待后台人工审核。
• realname_review_policy=1，自动调用阿里云；通过写 verified，失败、异常、不确定全部进入 manual_review。
• 审核策略只影响当前租户，不影响其他租户。

7. 后端开发拆分

7.1 第一阶段：配置和状态机

1. 新增 server/realname 或 server/identity 包，封装实名服务。
2. 从 HotGo hg_sys_config 读取 im_realname 分组供应商配置，并从 im_tenant_config 读取当前租户的审核策略。
3. 扩展 RealNameVerification 类型和 MySQL adapter 字段。
4. 新增状态更新方法，例如 TenantRealNameUpdateProviderResult。
5. 新增 provider 事件表写入方法。
6. 保持现有接口兼容，未配置第三方时仍可创建 pending 申请，不影响系统启动。

7.2 第二阶段：阿里云 Client

1. 封装 AliyunRealNameClient，支持 mock client 和真实 client。
2. 二要素模式实现：提交姓名、证件号，返回通过/拒绝/人工审核。
3. 增强版模式实现：
   • 发起认证：调用 InitSmartVerify、InitFaceVerify 或开通产品对应的初始化 API。
   • 查询结果：调用 DescribeSmartVerify、DescribeFaceVerify 或开通产品对应的查询 API。
4. 记录阿里云 RequestId、CertifyId、错误码和错误消息。

7.3 第三阶段：回调和异步查询

1. 新增阿里云回调 Handler。
2. 校验回调签名和时间窗口。
3. 以 provider_task_id 幂等更新实名状态。
4. 对没有回调或回调失败的任务，后台 worker 定时查询结果。
5. 查询超过最大次数后进入 manual_review 或 failed。

7.4 第四阶段：后台审核和通知

1. 完善后台审核接口：通过、拒绝、申诉处理、审核备注。
2. 实名通过/拒绝后发送系统通知。
3. GET /v1/im/bootstrap 和 GET /v1/im/me 统一读取真实实名状态。
4. 接入审计日志，记录管理员和第三方状态变更。

8. 安全与合规要求

1. 客户端不接触阿里云 AccessKey、AccessKeySecret、回调密钥。
2. IM Server 普通日志不得打印姓名、身份证号、阿里云完整返回 payload。
3. 身份证号只保存哈希、脱敏值和必要保护存储值；如必须保存原文，应使用 KMS 或应用层加密，并设置严格读取权限。
4. provider_result_json 和事件表 payload 需要脱敏或加密，禁止存储身份证原文、人脸图片、活体照片。
5. 回调接口必须校验签名、时间戳和幂等，避免伪造通过。
6. AccessKey 使用最小权限 RAM 子账号，建议按环境隔离。
7. 后台查询接口需要按 security_auditor 等角色授权，敏感字段默认脱敏。
8. 实名通过后的状态变更需要写审计日志，便于追踪。

9. 异常处理策略

场景	建议处理
阿里云配置缺失	接口返回稳定错误 REALNAME_PROVIDER_NOT_CONFIGURED，或按配置退回人工 pending
阿里云超时	本地状态保持 pending/processing，后台 worker 重试
阿里云明确不一致	状态改为 rejected，返回脱敏驳回原因
阿里云结果不确定	状态改为 manual_review
用户重复提交	如果已有 pending/processing/verified，直接返回最新申请
用户认证中断	到期后改为 expired，允许重新提交
回调重复到达	根据 provider_task_id + provider_status 幂等忽略

10. 客户端改动点

1. 继续使用当前实名提交和查询接口。
2. 如果提交响应包含 certify_url 或 token，客户端调起阿里云 SDK/H5 认证流程。
3. 认证完成后回到 IM 页面，调用 GET /v1/im/security/realname 刷新状态。
4. 客户端不缓存原始姓名和证件号，只展示后端返回的脱敏值。
5. 对 processing/pending/manual_review 统一展示“审核中/认证中”。
6. 对 rejected/expired/failed 根据 can_submit 和 next_action 决定是否允许重新提交或申诉。

11. 建议验收点

1. 未配置阿里云时，IM Server 能正常启动，现有实名提交仍可落 pending。
2. 配置 mock provider 后，提交实名可以覆盖通过、拒绝、异常和超时场景。
3. 二要素模式下，提交后能自动更新为 verified/rejected。
4. 增强版模式下，提交后返回 certify_id/certify_url，完成认证后状态能回写。
5. 重复 Idempotency-Key 不产生重复申请。
6. 阿里云回调重复投递不重复更新、不重复通知。
7. 日志、系统通知、Push、搜索索引中均不出现身份证原文。
8. 后台能按状态查看实名申请，并能人工处理 manual_review 和申诉。

12. 参考文档

• 阿里云 OpenAPI 开发者门户：https://api.aliyun.com/
• 阿里云实人认证服务 API：https://api.aliyun.com/product/Cloudauth
• InitSmartVerify：发起增强版认证请求，返回认证请求 ID。
• DescribeSmartVerify：查询增强版认证结果。
• InitFaceVerify / DescribeFaceVerify：按开通产品和接入形态选择的实人认证初始化与结果查询接口。

最终使用哪个 API 名称和参数，以实际开通的阿里云产品、地域、控制台场景配置和 API 门户为准。