temp

2025-07-20 20:53:26 +08:00
parent 83bf9aea7d
commit 8ad1d7288e
158 changed files with 18156 additions and 13188 deletions
--- a/docs/认证流程重构说明.md
+++ b/docs/认证流程重构说明.md
@@ -0,0 +1,267 @@
+# 认证流程重构说明
+
+## 概述
+
+本次重构主要针对认证流程中的企业信息管理进行了重大调整，删除了 `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` 实体，简化了认证流程的数据模型，提高了代码的可维护性和数据一致性。新的架构更加清晰，业务流程更加明确，为后续的功能扩展奠定了良好的基础。