1818web-hoduan/docs/identity-verification-integration.md

阿里云身份认证服务集成说明

功能概述

本项目已成功集成阿里云身份认证服务（CloudAuth）的身份证二要素核验功能，实现用户实名认证。

✅ 当前状态：已启用真实的阿里云身份认证API调用（新版SDK）

🔧 最新更新： 已修复 MissingFaceImageUrl 错误，更新为官方推荐的新版SDK和正确的API接口。

实现的功能

1. 实名认证接口

• 端点: POST /user/identity/verify
• 功能: 用户提交身份证号码和真实姓名进行实名认证
• 认证流程:
  • 验证身份证号码和姓名格式
  • 调用阿里云身份认证服务验证信息匹配性
  • 验证通过后更新用户认证状态

2. 认证状态查询

• 端点: GET /user/identity/status
• 功能: 查询当前用户的实名认证状态和相关信息（脱敏后）

3. 认证状态检查

• 端点: GET /user/identity/check
• 功能: 简单检查当前用户是否已完成实名认证

数据库字段说明

用户表（user）中实名认证相关字段：

字段名	类型	说明
real_username	varchar(64)	真实用户名
id_number	varchar(18)	身份证号码
is_verified	tinyint	是否实名认证 (0-未认证, 1-已认证)

配置信息

application.yml 配置

aliyun:
  cloudauth:
    region: cn-hangzhou
    endpoint: cloudauth.aliyuncs.com
    # 直接从配置文件读取认证信息
    access-key-id: LTAI5t68do3qVXx5Rufugt3X
    access-key-secret: 2vD9ToIff49Vph4JQXsn0Cy8nXQfzA
    connection-timeout: 10000
    response-timeout: 10000
    # 身份认证配置
    biz-type: ID_2META
    param-type: normal

配置说明

直接配置文件读取方式：

• ✅ 所有配置直接在application.yml中管理
• ✅ 无需设置环境变量
• ✅ 配置集中统一，便于管理

当前实现状态

已实现

✅ 配置文件集成
✅ 数据库字段支持
✅ API接口完整实现
✅ DTO类和响应封装
✅ 用户认证状态管理
✅ 输入验证和异常处理
✅ 日志记录和监控
✅ 真实阿里云CloudAuth SDK集成
✅ 真实身份证二要素验证
✅ 完整的错误处理和权限检查

当前实现状态

✅ 已完成真实阿里云API集成:

1. ✅ 已启用阿里云SDK: pom.xml中的阿里云CloudAuth依赖已启用
2. ✅ 已实现真实API调用: IdentityVerifyServiceImpl中已集成真实的阿里云身份认证API
3. ✅ 已配置访问凭证: 支持环境变量和配置文件两种方式配置AccessKey

重要提醒

⚠️ 生产环境部署前请确认：

1. 配置有效的阿里云AccessKey: 确保具有CloudAuth服务权限
2. 验证网络连接: 确保服务器能够访问阿里云API
3. 监控API调用: 关注API调用成功率和响应时间

API使用示例

提交实名认证

curl -X POST http://localhost:8081/user/identity/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "realName": "张三",
    "idNumber": "110101199003077777"
  }'

查询认证状态

curl -X GET http://localhost:8081/user/identity/status \
  -H "Authorization: Bearer your_jwt_token"

安全特性

1. JWT认证: 所有接口都需要有效的JWT令牌
2. 数据脱敏: 查询接口返回脱敏后的用户信息
3. 输入验证: 严格的身份证号码和姓名格式验证
4. 异常处理: 完善的错误处理和日志记录
5. 事务保证: 认证过程使用数据库事务保证数据一致性

业务逻辑保护

• 已实名认证的用户不能重复认证
• 完整的输入参数验证
• 用户状态检查和权限控制
• 不破坏现有的用户管理和业务逻辑

扩展计划

1. 集成真实的阿里云CloudAuth SDK
2. 添加认证历史记录
3. 支持企业用户认证
4. 添加认证失败重试机制
5. 集成短信/邮件通知功能

---

文档最后更新: 2024年8月31日