tyapi-server/docs/认证流程重构说明.md

# 认证流程重构说明

## 概述

本次重构主要针对认证流程中的企业信息管理进行了重大调整，删除了 `CertificationEnterpriseInfo` 实体，改为使用 `EnterpriseInfoSubmitRecord` 来管理认证过程中的企业信息。

## 主要变更

### 1. 实体结构调整

#### 删除的实体
- `CertificationEnterpriseInfo` - 认证过程中的企业信息实体
- `CertificationEnterpriseInfoRepository` - 认证企业信息仓储接口
- `GormCertificationEnterpriseInfoRepository` - 认证企业信息GORM仓储实现

#### 保留的实体
- `EnterpriseInfoSubmitRecord` - 企业信息提交记录（用于认证流程）
- `EnterpriseInfo` - 用户企业信息（认证完成后存储）

### 2. 业务流程调整

#### 企业信息提交流程
```go
// 1. 用户提交企业信息
// 2. 创建 EnterpriseInfoSubmitRecord 记录
// 3. 状态标记为 "submitted"
// 4. 认证申请状态转换为 "info_submitted"
```

#### 企业认证流程
```go
// 1. 获取 EnterpriseInfoSubmitRecord 记录
// 2. 调用e签宝服务生成认证文件
// 3. 更新记录状态为 "verified"
// 4. 认证申请状态转换为 "enterprise_verified"
```

#### 认证完成流程
```go
// 1. 从 EnterpriseInfoSubmitRecord 获取企业信息
// 2. 创建用户的 EnterpriseInfo 记录
// 3. 认证申请状态转换为 "completed"
```

### 3. 应用服务修改

#### 依赖注入调整
```go
type CertificationApplicationServiceImpl struct {
    certManagementService *services.CertificationManagementService
    certWorkflowService   *services.CertificationWorkflowService
    enterpriseService     *user_services.EnterpriseService
    esignService          *esign_service.EQService
    enterpriseRecordRepo  repositories.EnterpriseInfoSubmitRecordRepository  // 新增
    logger                *zap.Logger
}
```

#### 方法实现调整

**SubmitEnterpriseInfo 方法**
```go
func (s *CertificationApplicationServiceImpl) SubmitEnterpriseInfo(ctx context.Context, cmd *commands.SubmitEnterpriseInfoCommand) (*responses.EnterpriseInfoResponse, error) {
    // 1. 验证企业信息
    // 2. 获取或创建认证申请
    // 3. 提交企业信息（状态转换）
    // 4. 创建企业信息提交记录
    enterpriseRecord := entities.NewEnterpriseInfoSubmitRecord(
        certification.ID,
        cmd.UserID,
        cmd.CompanyName,
        cmd.UnifiedSocialCode,
        cmd.LegalPersonName,
        cmd.LegalPersonID,
    )
    _, err = s.enterpriseRecordRepo.Create(ctx, *enterpriseRecord)
    // ...
}
```

**GetEnterpriseAuthURL 方法**
```go
func (s *CertificationApplicationServiceImpl) GetEnterpriseAuthURL(ctx context.Context, userID string) (*responses.EnterpriseAuthURLResponse, error) {
    // 1. 获取认证申请
    // 2. 检查认证状态
    // 3. 获取企业信息提交记录
    enterpriseRecord, err := s.enterpriseRecordRepo.GetLatestByCertificationID(ctx, certification.ID)
    // 4. 生成e签宝认证文件
    // 5. 更新企业信息提交记录状态为已验证
    enterpriseRecord.MarkAsVerified()
    err = s.enterpriseRecordRepo.Update(ctx, *enterpriseRecord)
    // ...
}
```

**CompleteEnterpriseAuth 方法**
```go
func (s *CertificationApplicationServiceImpl) CompleteEnterpriseAuth(ctx context.Context, userID string) (*responses.CertificationResponse, error) {
    // 1. 获取认证申请
    // 2. 获取企业信息提交记录
    enterpriseRecord, err := s.enterpriseRecordRepo.GetLatestByCertificationID(ctx, certification.ID)
    // 3. 检查企业信息是否已验证
    if !enterpriseRecord.IsVerified() {
        return nil, fmt.Errorf("企业信息尚未验证，请先完成e签宝认证")
    }
    // 4. 完成企业认证（状态转换）
    // 5. 转移企业信息到用户账户
    _, err = s.enterpriseService.CreateEnterpriseInfo(ctx, userID, 
        enterpriseRecord.CompanyName, 
        enterpriseRecord.UnifiedSocialCode, 
        enterpriseRecord.LegalPersonName, 
        enterpriseRecord.LegalPersonID)
    // ...
}
```

### 4. 容器配置更新

#### e签宝服务注册
```go
// e签宝服务
func(cfg *config.Config) *esign_service.EQService {
    esignConfig := &esign_service.Config{
        AppID:      cfg.Esign.AppID,
        AppSecret:  cfg.Esign.AppSecret,
        ServerURL:  cfg.Esign.ServerURL,
        TemplateID: cfg.Esign.TemplateID,
    }
    return esign_service.NewEQService(esignConfig)
}
```

## 数据库结构

### 企业信息提交记录表 (enterprise_info_submit_records)
```sql
CREATE TABLE enterprise_info_submit_records (
    id VARCHAR(36) PRIMARY KEY,
    certification_id VARCHAR(36) NOT NULL,
    user_id VARCHAR(36) NOT NULL,
    
    -- 企业信息
    company_name VARCHAR(200) NOT NULL,
    unified_social_code VARCHAR(50) NOT NULL,
    legal_person_name VARCHAR(50) NOT NULL,
    legal_person_id VARCHAR(50) NOT NULL,
    
    -- 提交状态
    status VARCHAR(20) NOT NULL DEFAULT 'submitted',
    submit_at TIMESTAMP NOT NULL,
    verified_at TIMESTAMP NULL,
    failed_at TIMESTAMP NULL,
    failure_reason TEXT,
    
    -- 系统字段
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    deleted_at TIMESTAMP NULL,
    
    INDEX idx_certification_id (certification_id),
    INDEX idx_user_id (user_id),
    INDEX idx_unified_social_code (unified_social_code)
);
```

### 用户企业信息表 (enterprise_infos)
```sql
CREATE TABLE enterprise_infos (
    id VARCHAR(36) PRIMARY KEY,
    user_id VARCHAR(36) NOT NULL UNIQUE,
    
    -- 企业四要素
    company_name VARCHAR(255) NOT NULL,
    unified_social_code VARCHAR(50) NOT NULL,
    legal_person_name VARCHAR(100) NOT NULL,
    legal_person_id VARCHAR(50) NOT NULL,
    
    -- 认证状态
    is_ocr_verified BOOLEAN DEFAULT FALSE,
    is_face_verified BOOLEAN DEFAULT FALSE,
    is_certified BOOLEAN DEFAULT FALSE,
    verification_data TEXT,
    
    -- 认证完成时间
    certified_at TIMESTAMP NULL,
    
    -- 系统字段
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    deleted_at TIMESTAMP NULL,
    
    INDEX idx_user_id (user_id),
    INDEX idx_unified_social_code (unified_social_code)
);
```

## API接口变更

### 企业信息提交接口
**POST /api/certification/submit-enterprise-info**
- 功能：提交企业信息，创建企业信息提交记录
- 响应：返回企业信息提交记录ID和基本信息

### 获取企业认证链接接口
**GET /api/certification/enterprise-auth-url**
- 功能：获取e签宝企业认证链接
- 前置条件：企业信息已提交且状态为 "info_submitted"
- 响应：返回认证链接和过期时间

### 完成企业认证接口
**POST /api/certification/complete-enterprise-auth**
- 功能：完成企业认证，转移企业信息到用户账户
- 前置条件：企业信息已通过e签宝认证
- 响应：返回更新后的认证状态

## 重构优势

### 1. 数据模型简化
- 删除了冗余的 `CertificationEnterpriseInfo` 实体
- 使用现有的 `EnterpriseInfoSubmitRecord` 管理认证流程
- 减少了数据库表的数量和维护成本

### 2. 业务流程清晰
- 认证流程中的企业信息通过提交记录管理
- 认证完成后企业信息转移到用户账户
- 状态转换更加明确和可追踪

### 3. 代码维护性提升
- 减少了重复的仓储接口和实现
- 统一了企业信息的管理方式
- 简化了应用服务的依赖注入

### 4. 数据一致性保证
- 企业信息提交记录作为认证流程的中间状态
- 认证完成后才创建用户企业信息
- 避免了数据不一致的问题

## 迁移说明

### 数据迁移
如果系统中存在旧的 `certification_enterprise_infos` 表数据，需要进行数据迁移：

```sql
-- 迁移认证过程中的企业信息到提交记录表
INSERT INTO enterprise_info_submit_records (
    id, certification_id, user_id, company_name, unified_social_code, 
    legal_person_name, legal_person_id, status, submit_at, 
    verified_at, created_at, updated_at
)
SELECT 
    id, certification_id, user_id, company_name, unified_social_code,
    legal_person_name, legal_person_id, 
    CASE WHEN is_verified THEN 'verified' ELSE 'submitted' END,
    created_at, verified_at, created_at, updated_at
FROM certification_enterprise_infos
WHERE deleted_at IS NULL;
```

### 代码迁移
1. 删除所有对 `CertificationEnterpriseInfo` 的引用
2. 更新应用服务使用 `EnterpriseInfoSubmitRecord`
3. 更新容器配置移除相关仓储注册
4. 更新API文档和测试用例

## 总结

本次重构通过删除冗余的 `CertificationEnterpriseInfo` 实体，简化了认证流程的数据模型，提高了代码的可维护性和数据一致性。新的架构更加清晰，业务流程更加明确，为后续的功能扩展奠定了良好的基础。