# Design Document

## Overview

本设计文档描述了用户企业认证、身份认证和员工CA二维码认证功能的技术实现方案。该功能将在现有的若依系统（Spring Boot 2.5.15 + MyBatis + Vue3）中添加认证能力，并实现基于认证状态的权限控制。

系统采用分层架构设计，包括：
- **Controller层**：处理HTTP请求和响应
- **Service层**：实现业务逻辑
- **Mapper层**：数据访问层
- **Domain层**：实体模型
- **CA接口适配层**：对接外部CA服务

### 企业认证方式

系统采用法人CA认证方式进行企业认证：

- 用户提交企业信息和法人身份信息（法人姓名、法人身份证号）
- 系统验证信息完整性和格式
- 系统通过CA接口适配层调用外部CA服务进行法人身份认证
- CA服务验证法人身份与企业的关联关系
- CA认证成功后自动通过企业认证，认证状态直接变为"已认证"
- 无需人工审核，实现自动化认证

## Architecture

### 企业认证业务流程

```mermaid
graph TD
    A[用户填写企业信息+法人身份信息] --> B[提交法人CA认证申请]
    B --> C[系统验证信息完整性]
    C -->|验证通过| D[调用CA服务进行法人认证]
    C -->|验证失败| E[返回错误信息]
    D --> F{CA认证结果}
    F -->|认证成功| G[自动通过企业认证]
    F -->|认证失败| H[返回CA错误信息]
    G --> I[更新状态为"已认证"]
    I --> J[记录CA认证ID和时间]
```

### 模块划分

```
ruoyi-system (系统模块)
├── domain
│   ├── UserEnterpriseVerification (用户企业认证实体)
│   ├── UserIdentityVerification (用户身份认证实体)
│   └── VerificationAuditLog (认证审核日志实体)
├── mapper
│   ├── UserEnterpriseVerificationMapper
│   ├── UserIdentityVerificationMapper
│   └── VerificationAuditLogMapper
├── service
│   ├── IUserVerificationService (认证服务接口)
│   └── impl
│       └── UserVerificationServiceImpl
└── controller (在ruoyi-admin中)
    └── UserVerificationController

ruoyi-credit (员工管理模块)
├── domain
│   └── EmployeeQRCode (员工实名认证二维码实体)
├── mapper
│   └── EmployeeQRCodeMapper
├── service
│   ├── IEmployeeQRCodeService
│   └── impl
│       └── EmployeeQRCodeServiceImpl
├── ca
│   ├── CAServiceAdapter (CA服务适配器接口)
│   ├── impl
│   │   ├── MockCAServiceAdapter (Mock实现)
│   │   └── RealCAServiceAdapter (真实CA服务实现-预留)
│   └── config
│       └── CAServiceConfig (CA服务配置)
└── controller (在ruoyi-admin中)
    └── EmployeeQRCodeController

ruoyi-common (通用模块)
├── utils
│   ├── IdCardValidator (身份证验证工具)
│   ├── QRCodeGenerator (二维码生成工具)
│   └── EncryptionUtil (加密工具)
└── interceptor
    └── VerificationInterceptor (认证拦截器)
```

### 技术栈

- **后端框架**: Spring Boot 2.5.15
- **持久层**: MyBatis + MySQL
- **安全框架**: Spring Security
- **加密算法**: AES-256-GCM (身份证号), RSA (二维码签名)
- **二维码生成**: ZXing
- **前端框架**: Vue 3 + Element Plus
- **HTTP客户端**: Apache HttpClient (调用CA服务)

## Components and Interfaces

### 1. 权限常量定义

```java
public class VerificationPermissions {
    // 认证查看权限
    public static final String VIEW_ALL_VERIFICATION = "system:verification:view:all";
    public static final String EXPORT_VERIFICATION = "system:verification:export";
}
```

### 2. 用户认证服务 (UserVerificationService)

#### 接口定义

```java
public interface IUserVerificationService {
    // 企业认证 - 法人CA认证方式
    AjaxResult submitEnterpriseVerificationWithLegalPersonCA(EnterpriseCAVerificationRequest request);
    
    AjaxResult getEnterpriseVerificationStatus(Long userId);
    
    // 身份认证
    AjaxResult submitIdentityVerification(UserIdentityVerification verification);
    AjaxResult getIdentityVerificationStatus(Long userId);
    
    // 认证状态查询
    boolean isUserFullyVerified(Long userId);
    VerificationStatusDTO getUserVerificationStatus(Long userId);
    
    // 企业认证管理
    @PreAuthorize("hasAuthority('system:verification:view:all')")
    List<UserEnterpriseVerification> listEnterpriseVerifications(VerificationQuery query);
    
    @PreAuthorize("hasAuthority('system:verification:export')")
    byte[] exportEnterpriseVerifications(VerificationQuery query);
}
```

#### 法人CA认证请求对象

```java
public class EnterpriseCAVerificationRequest {
    private Long userId;                // 用户ID
    private String enterpriseName;      // 企业名称
    private String enterpriseCode;      // 企业统一社会信用代码
    private String legalPersonName;     // 法人姓名
    private String legalPersonIdCard;   // 法人身份证号
    private String businessLicense;     // 营业执照URL（可选）
}
```

### 4. CA服务适配器 (CAServiceAdapter)

#### 接口定义

```java
public interface IEmployeeQRCodeService {
    // 二维码生成
    AjaxResult generateQRCode(Long employeeId);
    byte[] getQRCodeImage(String qrCodeId);
    
    // 二维码验证（调用CA服务）
    QRCodeVerificationResult verifyQRCodeWithCA(String qrCodeData);
    boolean isQRCodeValid(String qrCodeId);
}
```

#### 二维码数据格式

```java
public class EmployeeQRCodeData {
    private Long employeeId;        // 员工ID
    private String realName;        // 真实姓名
    private String idCardNumber;    // 身份证号（明文）
    private Long timestamp;         // 时间戳
}
```

### 4. CA服务适配器 (CAServiceAdapter)

#### 接口定义

```java
public interface CAServiceAdapter {
    // 身份认证操作
    IdentityVerificationResponse verifyIdentity(IdentityVerificationRequest request);
    
    // 健康检查
    boolean isServiceAvailable();
}
```

#### CA服务请求/响应格式

```java
// 身份认证请求对象
public class IdentityVerificationRequest {
    private String userId;          // 用户ID或员工ID
    private String realName;        // 真实姓名
    private String idCardNumber;    // 身份证号
    private String verificationType; // IDENTITY-身份认证, EMPLOYEE-员工认证, LEGAL_PERSON-法人认证
    private String enterpriseName;   // 企业名称（法人认证时使用）
    private String enterpriseCode;   // 企业统一社会信用代码（法人认证时使用）
}

// 身份认证响应对象
public class IdentityVerificationResponse {
    private boolean success;
    private String verificationId; // CA服务返回的认证ID
    private String verificationStatus; // APPROVED-通过, REJECTED-拒绝
    private String rejectReason; // 拒绝原因
    private Date verificationTime;
    private String errorCode;
    private String errorMessage;
    private Map<String, Object> additionalData; // 额外数据（如法人认证返回的企业信息）
}
```

### 5. 认证拦截器 (VerificationInterceptor)

```java
@Component
public class VerificationInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        // 检查当前用户的认证状态
        // 如果访问需要认证的菜单但用户未认证，则拦截
        // 超级管理员例外
    }
}
```

## Data Models

### 1. 用户企业认证表 (sys_user_enterprise_verification)

```sql
CREATE TABLE sys_user_enterprise_verification (
    verification_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '认证ID',
    user_id BIGINT NOT NULL COMMENT '用户ID',
    enterprise_name VARCHAR(200) NOT NULL COMMENT '企业名称',
    enterprise_code VARCHAR(100) NOT NULL COMMENT '企业统一社会信用代码',
    legal_person VARCHAR(100) COMMENT '法人代表',
    legal_person_id_card VARCHAR(200) COMMENT '法人身份证号(加密)',
    business_license VARCHAR(500) COMMENT '营业执照URL',
    verification_status VARCHAR(20) NOT NULL DEFAULT 'PENDING' COMMENT '认证状态: PENDING-未认证, APPROVED-已认证, REJECTED-认证失败',
    ca_verification_id VARCHAR(100) COMMENT 'CA服务返回的认证ID',
    ca_verification_time DATETIME COMMENT 'CA认证时间',
    audit_remark VARCHAR(500) COMMENT '备注',
    create_by VARCHAR(64) COMMENT '创建者',
    create_time DATETIME COMMENT '创建时间',
    update_by VARCHAR(64) COMMENT '更新者',
    update_time DATETIME COMMENT '更新时间',
    INDEX idx_user_id (user_id),
    INDEX idx_status (verification_status),
    INDEX idx_enterprise_code (enterprise_code),
    INDEX idx_ca_verification_id (ca_verification_id)
) COMMENT='用户企业认证表';
```

### 2. 用户身份认证表 (sys_user_identity_verification)

```sql
CREATE TABLE sys_user_identity_verification (
    verification_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '认证ID',
    user_id BIGINT NOT NULL COMMENT '用户ID',
    real_name VARCHAR(100) NOT NULL COMMENT '真实姓名',
    id_card_number VARCHAR(200) NOT NULL COMMENT '身份证号(加密)',
    verification_status VARCHAR(20) NOT NULL DEFAULT 'PENDING' COMMENT '认证状态: PENDING-未认证, APPROVED-已认证, REJECTED-认证失败',
    ca_verification_id VARCHAR(100) COMMENT 'CA服务返回的认证ID',
    reject_reason VARCHAR(500) COMMENT 'CA服务拒绝原因',
    verification_time DATETIME COMMENT 'CA认证时间',
    create_by VARCHAR(64) COMMENT '创建者',
    create_time DATETIME COMMENT '创建时间',
    update_by VARCHAR(64) COMMENT '更新者',
    update_time DATETIME COMMENT '更新时间',
    INDEX idx_user_id (user_id),
    INDEX idx_status (verification_status),
    INDEX idx_ca_verification_id (ca_verification_id)
) COMMENT='用户身份认证表';
```

### 3. 认证审核日志表 (sys_verification_audit_log)

```sql
CREATE TABLE sys_verification_audit_log (
    log_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '日志ID',
    verification_type VARCHAR(20) NOT NULL COMMENT '认证类型: ENTERPRISE-企业认证, IDENTITY-身份认证',
    verification_id BIGINT NOT NULL COMMENT '认证记录ID',
    user_id BIGINT NOT NULL COMMENT '用户ID',
    old_status VARCHAR(20) COMMENT '原状态',
    new_status VARCHAR(20) NOT NULL COMMENT '新状态',
    audit_remark VARCHAR(500) COMMENT '审核备注',
    operator_id BIGINT NOT NULL COMMENT '操作人ID',
    operator_name VARCHAR(100) COMMENT '操作人姓名',
    operator_roles VARCHAR(200) COMMENT '操作人角色列表（逗号分隔）',
    operation_time DATETIME NOT NULL COMMENT '操作时间',
    INDEX idx_verification (verification_type, verification_id),
    INDEX idx_user_id (user_id),
    INDEX idx_operation_time (operation_time),
    INDEX idx_operator_id (operator_id)
) COMMENT='认证审核日志表';
```

### 4. 员工实名认证二维码表 (dc_employee_qr_code)

```sql
CREATE TABLE dc_employee_qr_code (
    qr_code_id VARCHAR(64) PRIMARY KEY COMMENT '二维码ID(UUID)',
    employee_id BIGINT NOT NULL COMMENT '员工ID',
    real_name VARCHAR(100) NOT NULL COMMENT '真实姓名',
    id_card_number VARCHAR(18) NOT NULL COMMENT '身份证号',
    generate_time DATETIME NOT NULL COMMENT '生成时间',
    expiry_time DATETIME NOT NULL COMMENT '过期时间',
    qr_code_status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE' COMMENT '二维码状态: ACTIVE-有效, EXPIRED-已过期, USED-已使用',
    verification_status VARCHAR(20) COMMENT '认证状态: PENDING-待认证, APPROVED-已认证, REJECTED-认证失败',
    ca_verification_id VARCHAR(100) COMMENT 'CA服务返回的认证ID',
    verification_time DATETIME COMMENT '认证时间',
    INDEX idx_employee_id (employee_id),
    INDEX idx_status (qr_code_status),
    INDEX idx_expiry_time (expiry_time)
) COMMENT='员工实名认证二维码表';
```

### 5. CA服务配置表 (sys_ca_service_config)

```sql
CREATE TABLE sys_ca_service_config (
    config_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '配置ID',
    config_key VARCHAR(100) NOT NULL UNIQUE COMMENT '配置键',
    config_value VARCHAR(500) NOT NULL COMMENT '配置值',
    config_desc VARCHAR(200) COMMENT '配置描述',
    is_encrypted TINYINT(1) DEFAULT 0 COMMENT '是否加密存储',
    create_time DATETIME COMMENT '创建时间',
    update_time DATETIME COMMENT '更新时间'
) COMMENT='CA服务配置表';

-- 初始化配置数据
INSERT INTO sys_ca_service_config (config_key, config_value, config_desc) VALUES
('ca.service.url', 'http://localhost:8080/mock-ca', 'CA服务接口地址'),
('ca.service.timeout', '30000', 'CA服务超时时间(毫秒)'),
('ca.service.app_id', 'ruoyi-system', 'CA服务应用ID'),
('ca.service.app_secret', 'mock-secret-key', 'CA服务应用密钥'),
('ca.service.enabled', 'true', 'CA服务是否启用'),
('ca.qrcode.validity_hours', '24', '二维码默认有效期(小时)');
```

### 7. 角色和权限初始化

```sql
-- 插入认证审核员角色
INSERT INTO sys_role (role_name, role_key, role_sort, status, del_flag, create_time, remark) VALUES
('认证审核员', 'verification_auditor', 3, '0', '0', NOW(), '负责审核企业认证申请');

-- 插入认证管理员角色
INSERT INTO sys_role (role_name, role_key, role_sort, status, del_flag, create_time, remark) VALUES
('认证管理员', 'verification_manager', 2, '0', '0', NOW(), '负责管理所有认证信息');

-- 插入认证相关菜单权限
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, is_frame, menu_type, visible, status, perms, icon, create_time, remark) VALUES
('认证管理', 0, 5, 'verification', NULL, 1, 'M', '0', '0', NULL, 'shield', NOW(), '认证管理目录'),
('企业认证审核', (SELECT menu_id FROM sys_menu WHERE menu_name='认证管理'), 1, 'enterprise', 'system/verification/enterprise', 1, 'C', '0', '0', 'system:verification:audit:enterprise', 'building', NOW(), '企业认证审核菜单'),
('认证信息管理', (SELECT menu_id FROM sys_menu WHERE menu_name='认证管理'), 2, 'manage', 'system/verification/manage', 1, 'C', '0', '0', 'system:verification:manage', 'list', NOW(), '认证信息管理菜单');

-- 为认证审核员角色分配权限
INSERT INTO sys_role_menu (role_id, menu_id) 
SELECT r.role_id, m.menu_id 
FROM sys_role r, sys_menu m 
WHERE r.role_key = 'verification_auditor' 
AND m.perms IN ('system:verification:audit:enterprise', 'system:verification:view:all');

-- 为认证管理员角色分配权限
INSERT INTO sys_role_menu (role_id, menu_id) 
SELECT r.role_id, m.menu_id 
FROM sys_role r, sys_menu m 
WHERE r.role_key = 'verification_manager' 
AND m.perms IN ('system:verification:audit:enterprise', 'system:verification:manage', 'system:verification:view:all', 'system:verification:export');
```

## Correctness Properties

*属性是一个特征或行为，应该在系统的所有有效执行中保持为真——本质上是关于系统应该做什么的正式陈述。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*


### 企业认证属性

Property 1: 企业认证信息验证
*For any* 企业认证申请，如果企业信息和法人身份信息完整且格式正确，则系统应该接受申请并返回成功
**Validates: Requirements 1.2**

Property 2: 法人CA认证调用
*For any* 有效的法人CA认证申请，系统应该通过CA接口适配层调用外部CA服务进行法人身份认证
**Validates: Requirements 1.3**

Property 3: 法人CA认证成功处理
*For any* CA服务返回法人认证成功的响应，系统应该自动通过企业认证并更新认证状态为"已认证"
**Validates: Requirements 1.4**

Property 4: 法人CA认证失败处理
*For any* CA服务返回法人认证失败的响应，系统应该返回具体错误信息并保持认证状态为"未认证"
**Validates: Requirements 1.5**

Property 5: 法人CA认证记录
*For any* 法人CA认证通过，系统应该记录CA认证ID、认证时间和法人身份信息
**Validates: Requirements 1.6**

Property 6: 企业认证重新申请
*For any* 被拒绝的企业认证，用户应该能够重新提交申请
**Validates: Requirements 1.7**

### 身份认证属性

Property 7: 身份证号格式验证
*For any* 18位身份证号，系统应该验证其格式和校验位的正确性
**Validates: Requirements 2.4**

Property 8: 身份证号加密存储
*For any* 有效的身份证号，存储后应该是加密的，且解密后应该等于原始值（round-trip property）
**Validates: Requirements 2.6, 7.1**

Property 9: CA服务身份认证调用
*For any* 有效的身份认证申请，系统应该通过CA接口适配层调用外部CA服务进行身份认证
**Validates: Requirements 2.5**

Property 10: CA身份认证成功处理
*For any* CA服务返回认证成功的响应，系统应该更新认证状态为"已认证"并记录CA认证ID和时间
**Validates: Requirements 2.6**

Property 11: CA身份认证失败处理
*For any* CA服务返回认证失败的响应，系统应该更新认证状态为"认证失败"并记录拒绝原因
**Validates: Requirements 2.7**

### 员工实名认证二维码属性

Property 12: 二维码内容完整性
*For any* 员工，生成的实名认证二维码应该包含员工ID、真实姓名、身份证号和时间戳
**Validates: Requirements 3.1**

Property 13: 二维码CA认证调用
*For any* 有效的二维码，扫描后系统应该调用CA服务进行身份认证
**Validates: Requirements 3.3**

Property 14: 二维码认证成功处理
*For any* CA服务返回认证成功的响应，系统应该更新员工认证状态为"已认证"并记录认证时间
**Validates: Requirements 3.4**

Property 15: 二维码认证失败处理
*For any* CA服务返回认证失败的响应，系统应该返回具体失败原因并保持认证状态为"未认证"
**Validates: Requirements 3.5**

Property 16: 二维码过期验证
*For any* 超过有效期的二维码，系统应该拒绝认证并提示重新生成
**Validates: Requirements 3.6, 4.6**

### CA服务接口属性

Property 17: CA服务配置读取
*For any* CA服务调用，系统应该从配置文件读取接口地址和认证信息
**Validates: Requirements 4.2**

Property 18: CA服务错误处理
*For any* CA服务不可用的情况，系统应该返回友好的错误信息并记录日志
**Validates: Requirements 4.3**

Property 19: CA服务超时处理
*For any* CA服务调用，如果30秒内未响应，系统应该超时并返回错误信息
**Validates: Requirements 4.6**

Property 20: CA服务调用日志
*For any* CA服务调用，系统应该记录请求参数、响应结果和调用时间
**Validates: Requirements 4.7**

### 权限控制属性

Property 21: 未认证用户访问拦截
*For any* 未完成双认证的普通用户，访问需要认证的功能时应该被拦截并显示认证提示
**Validates: Requirements 5.1, 5.3**

Property 22: 双认证完成解除限制
*For any* 完成企业认证和身份认证的用户，应该能够访问所有需要认证的功能
**Validates: Requirements 5.4**

Property 23: 超级管理员特殊权限
*For any* 超级管理员用户（userId=1），即使未认证也应该能够访问所有功能
**Validates: Requirements 5.5**

Property 24: 权限检查双认证状态
*For any* 权限检查操作，系统应该验证用户的企业认证和身份认证状态都为"已认证"
**Validates: Requirements 5.8**

Property 25: 认证菜单配置化
*For any* 配置为需要认证的菜单，系统应该根据配置文件进行权限控制
**Validates: Requirements 5.9**

### 数据安全属性

Property 26: 认证数据访问权限
*For any* 认证数据访问操作，系统应该验证用户权限并记录访问日志
**Validates: Requirements 7.3**

Property 27: 法人身份证号加密存储
*For any* 有效的法人身份证号，存储后应该是加密的，且解密后应该等于原始值（round-trip property）
**Validates: Requirements 7.1**

## Error Handling

### 1. 输入验证错误

- **企业信息不完整**: 返回缺失字段列表
- **企业统一社会信用代码格式错误**: 返回格式说明
- **身份证号格式错误**: 返回格式说明和校验位错误提示
- **身份证号校验位错误**: 返回校验位计算说明

### 2. 业务逻辑错误

- **重复提交认证申请**: 提示已有待审核的申请
- **认证状态不允许操作**: 提示当前状态和允许的操作
- **二维码已过期**: 提示二维码已过期，需要重新生成
- **二维码签名验证失败**: 提示二维码无效

### 3. 外部服务错误

- **CA服务不可用**: 返回友好提示，建议稍后重试，记录详细错误日志
- **CA服务超时**: 返回超时提示，记录超时日志
- **CA服务返回错误**: 解析错误码，返回对应的中文提示

### 4. 系统错误

- **加密/解密失败**: 记录错误日志，返回通用错误提示
- **数据库操作失败**: 记录错误日志，返回通用错误提示
- **二维码生成失败**: 记录错误日志，返回生成失败提示

### 错误码设计

```java
public enum VerificationErrorCode {
    // 输入验证错误 (1000-1999)
    INVALID_ENTERPRISE_INFO(1001, "企业信息不完整或格式错误"),
    INVALID_ID_CARD_FORMAT(1002, "身份证号格式错误"),
    INVALID_ID_CARD_CHECKSUM(1003, "身份证号校验位错误"),
    
    // 业务逻辑错误 (2000-2999)
    DUPLICATE_VERIFICATION(2001, "已有待审核的认证申请"),
    INVALID_VERIFICATION_STATUS(2002, "当前认证状态不允许此操作"),
    QRCODE_EXPIRED(2006, "二维码已过期"),
    QRCODE_INVALID_SIGNATURE(2007, "二维码签名验证失败"),
    
    // 外部服务错误 (3000-3999)
    CA_SERVICE_UNAVAILABLE(3001, "CA服务暂时不可用，请稍后重试"),
    CA_SERVICE_TIMEOUT(3002, "CA服务响应超时"),
    CA_SERVICE_ERROR(3003, "CA服务返回错误"),
    
    // 系统错误 (9000-9999)
    ENCRYPTION_ERROR(9001, "数据加密失败"),
    DECRYPTION_ERROR(9002, "数据解密失败"),
    DATABASE_ERROR(9003, "数据库操作失败"),
    QRCODE_GENERATION_ERROR(9004, "二维码生成失败");
    
    private final int code;
    private final String message;
    
    VerificationErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }
}
```

## Testing Strategy

### 单元测试

使用JUnit 5进行单元测试，覆盖以下内容：

1. **工具类测试**
   - IdCardValidator: 测试身份证号验证逻辑
   - EncryptionUtil: 测试加密解密功能
   - QRCodeGenerator: 测试二维码生成功能

2. **Service层测试**
   - UserVerificationService: 测试认证业务逻辑
   - EmployeeCACertificateService: 测试CA证书管理逻辑
   - EmployeeQRCodeService: 测试二维码生成和验证逻辑

3. **CA适配器测试**
   - MockCAServiceAdapter: 测试Mock实现
   - CAServiceConfig: 测试配置读取

### 属性测试

使用jqwik进行属性测试，每个测试至少运行100次迭代：

1. **认证属性测试**
   - 测试Property 1-8: 企业认证和身份认证的各种属性
   - 生成随机的认证数据，验证系统行为

2. **CA证书属性测试**
   - 测试Property 9-13: CA证书管理的各种属性
   - 生成随机的员工和证书数据，验证证书生命周期

3. **二维码属性测试**
   - 测试Property 14-18: 二维码生成和验证的各种属性
   - 生成随机的二维码数据，验证签名和验证逻辑

4. **权限控制属性测试**
   - 测试Property 23-27: 权限控制的各种属性
   - 生成随机的用户和认证状态，验证权限拦截逻辑

5. **加密属性测试**
   - 测试Property 7, 15, 28: 加密和签名的round-trip属性
   - 生成随机的数据，验证加密解密和签名验证的正确性

### 集成测试

1. **Controller层集成测试**
   - 使用MockMvc测试API接口
   - 测试请求参数验证、响应格式、错误处理

2. **数据库集成测试**
   - 使用H2内存数据库进行测试
   - 测试Mapper层的CRUD操作

3. **CA服务集成测试**
   - 使用MockCAServiceAdapter进行测试
   - 测试CA服务调用、超时处理、错误处理

### 前端测试

1. **组件测试**
   - 使用Vitest测试Vue组件
   - 测试认证表单、认证状态显示、二维码显示

2. **E2E测试**
   - 使用Playwright测试完整的认证流程
   - 测试用户提交认证、管理员审核、权限控制

### 测试覆盖率目标

- 单元测试代码覆盖率: ≥ 80%
- 属性测试: 覆盖所有定义的正确性属性
- 集成测试: 覆盖所有API接口
- E2E测试: 覆盖主要业务流程

## Implementation Notes

### 1. 加密实现

使用BouncyCastle库实现AES-256-GCM加密：

```java
public class EncryptionUtil {
    private static final String ALGORITHM = "AES/GCM/NoPadding";
    private static final int GCM_TAG_LENGTH = 128;
    private static final int GCM_IV_LENGTH = 12;
    
    public static String encrypt(String plaintext, SecretKey key) {
        // 实现AES-256-GCM加密
    }
    
    public static String decrypt(String ciphertext, SecretKey key) {
        // 实现AES-256-GCM解密
    }
}
```

### 2. 身份证号验证

实现GB 11643-1999标准的身份证号验证：

```java
public class IdCardValidator {
    private static final int[] WEIGHT = {7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2};
    private static final char[] CHECK_CODE = {'1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'};
    
    public static boolean validate(String idCard) {
        // 验证长度、格式、校验位
    }
}
```

### 3. 二维码生成

使用ZXing库生成二维码：

```java
public class QRCodeGenerator {
    public static byte[] generateQRCode(String content, int width, int height) {
        // 使用ZXing生成二维码图片
    }
}
```

### 4. CA服务适配器配置

在application.yml中配置CA服务：

```yaml
ca:
  service:
    enabled: true
    adapter: mock  # mock 或 real
    url: http://localhost:8080/mock-ca
    timeout: 30000
    app-id: ruoyi-system
    app-secret: ${CA_APP_SECRET:mock-secret-key}
  certificate:
    validity-days: 365
  qrcode:
    validity-hours: 24
```

### 5. 权限拦截器配置

在WebMvcConfigurer中注册拦截器：

```java
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Autowired
    private VerificationInterceptor verificationInterceptor;
    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(verificationInterceptor)
                .addPathPatterns("/credit/contract/**")  // 需要认证的路径
                .excludePathPatterns("/system/user/verification/**");  // 排除认证接口本身
    }
}
```

### 6. 定时任务

使用Spring的@Scheduled注解实现CA证书过期提醒：

```java
@Component
public class CertificateExpiryTask {
    @Scheduled(cron = "0 0 9 * * ?")  // 每天早上9点执行
    public void checkExpiringCertificates() {
        // 查询30天内过期的证书
        // 发送过期提醒通知
    }
}
```

### 7. 前端界面实现

#### 企业认证提交

```vue
<template>
  <el-dialog title="企业认证" v-model="dialogVisible">
    <!-- 法人CA认证表单 -->
    <el-form :model="caForm" ref="caFormRef">
      <el-form-item label="企业名称" prop="enterpriseName" required>
        <el-input v-model="caForm.enterpriseName" />
      </el-form-item>
      <el-form-item label="统一社会信用代码" prop="enterpriseCode" required>
        <el-input v-model="caForm.enterpriseCode" />
      </el-form-item>
      <el-form-item label="法人姓名" prop="legalPersonName" required>
        <el-input v-model="caForm.legalPersonName" />
      </el-form-item>
      <el-form-item label="法人身份证号" prop="legalPersonIdCard" required>
        <el-input v-model="caForm.legalPersonIdCard" maxlength="18" />
      </el-form-item>
      <el-form-item label="营业执照" prop="businessLicense">
        <el-upload action="/api/upload" :on-success="handleUploadSuccess">
          <el-button>上传营业执照（可选）</el-button>
        </el-upload>
      </el-form-item>
      <el-alert 
        title="法人CA认证说明" 
        type="info" 
        :closable="false"
        description="系统将通过CA服务验证法人身份与企业的关联关系，认证成功后自动完成企业认证。"
      />
    </el-form>

    <template #footer>
      <el-button @click="dialogVisible = false">取消</el-button>
      <el-button type="primary" @click="submitVerification" :loading="submitting">
        提交认证
      </el-button>
    </template>
  </el-dialog>
</template>

<script setup>
import { ref } from 'vue';
import { submitEnterpriseVerificationWithCA } from '@/api/verification';

const caForm = ref({
  enterpriseName: '',
  enterpriseCode: '',
  legalPersonName: '',
  legalPersonIdCard: '',
  businessLicense: ''
});

const submitVerification = async () => {
  await submitEnterpriseVerificationWithCA(caForm.value);
};
</script>
```

在Vue Router中添加路由守卫：

```javascript
router.beforeEach(async (to, from, next) => {
  if (to.meta.requiresVerification) {
    const verificationStatus = await getVerificationStatus();
    if (!verificationStatus.isFullyVerified && !verificationStatus.isSuperAdmin) {
      // 显示认证提示横幅
      showVerificationBanner();
      // 阻止访问
      next(false);
    } else {
      next();
    }
  } else {
    next();
  }
});
```

### 8. 前端路由守卫

在Vue Router中添加路由守卫：

```javascript
router.beforeEach(async (to, from, next) => {
  if (to.meta.requiresVerification) {
    const verificationStatus = await getVerificationStatus();
    if (!verificationStatus.isFullyVerified && !verificationStatus.isSuperAdmin) {
      // 显示认证提示横幅
      showVerificationBanner();
      // 阻止访问
      next(false);
    } else {
      next();
    }
  } else {
    next();
  }
});
```

## Deployment Considerations

### 1. 数据库迁移

使用Flyway或Liquibase管理数据库版本：

- V1__create_verification_tables.sql: 创建认证相关表
- V2__create_ca_certificate_tables.sql: 创建CA证书相关表
- V3__init_ca_service_config.sql: 初始化CA服务配置

### 2. 密钥管理

- AES加密密钥: 使用环境变量或密钥管理服务（如AWS KMS）
- RSA密钥对: 生成后安全存储，定期轮换
- CA服务密钥: 加密存储在配置表中

### 3. 性能优化

- 认证状态缓存: 使用Redis缓存用户认证状态，减少数据库查询
- 二维码图片缓存: 缓存生成的二维码图片
- CA服务调用: 实现重试机制和熔断器

### 4. 监控和告警

- CA服务可用性监控
- 证书过期监控
- 认证申请量监控
- 错误率监控

### 5. 安全加固

- 限制认证申请频率（防止滥用）
- 审核操作需要二次确认
- 敏感操作记录审计日志
- 定期备份认证数据