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

## 功能概述

本项目已成功集成阿里云身份认证服务（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 配置

```yaml
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使用示例

### 提交实名认证

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

### 查询认证状态

```bash
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日*