tyapi-server/docs/Certification域DDD重构规范.md

# Certification域DDD重构规范文档

## 📋 概述

本文档规范了certification域（企业认证域）的DDD架构重构方案，目标是实现清晰的职责划分、完善的状态管理、以及高度可维护的代码结构。

## 🎯 重构目标

### 业务目标
- 企业认证流程通过e签宝API实现
- 异步回调驱动的状态转换机制  
- 简化状态设计，专注核心业务节点
- 已签署合同即代表认证完成

### 技术目标
- 符合DDD架构原则的分层设计
- 清晰的职责边界和依赖关系
- 基于CachedBaseRepositoryImpl的仓储实现
- 完善的事件驱动架构
- 强类型的状态机设计

## 🏗️ 架构设计

### 分层架构图
```
┌─────────────────────────────────────────────────┐
│                 表现层 (API)                      │
│  HTTP Controllers + Handlers                   │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│                 应用服务层                        │
│  用例协调 + DTO转换 + 事务管理                    │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│                 领域服务层                        │
│  工作流编排 + e签宝集成 + 回调处理 + 状态机        │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│                 领域模型层                        │
│  聚合根 + 实体 + 值对象 + 领域规则                │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│                 基础设施层                        │
│  仓储实现 + 外部服务 + 缓存 + 事件发布              │
└─────────────────────────────────────────────────┘
```

## 📊 状态设计

### 状态枚举定义
```go
const (
    // 主流程状态
    StatusPending              = "pending"                // 待认证
    StatusInfoSubmitted        = "info_submitted"         // 已提交企业信息  
    StatusEnterpriseVerified   = "enterprise_verified"    // 已企业认证
    StatusContractApplied      = "contract_applied"       // 已申请签署合同
    StatusContractSigned       = "contract_signed"        // 已签署合同(认证完成)
    
    // 失败状态
    StatusInfoRejected         = "info_rejected"          // 企业信息被拒绝
    StatusContractRejected     = "contract_rejected"      // 合同被拒签  
    StatusContractExpired      = "contract_expired"       // 合同签署超时
)
```

### 状态转换规则
| 当前状态 | 目标状态 | 触发条件 | 操作者 |
|---------|---------|----------|-------|
| Pending | InfoSubmitted | 用户提交企业信息 | USER |
| InfoSubmitted | EnterpriseVerified | e签宝认证成功回调 | SYSTEM |
| InfoSubmitted | InfoRejected | e签宝认证失败回调 | SYSTEM |
| EnterpriseVerified | ContractApplied | 用户申请合同 | USER |
| ContractApplied | ContractSigned | e签宝签署成功回调 | SYSTEM |
| ContractApplied | ContractRejected | e签宝拒签回调 | SYSTEM |
| ContractApplied | ContractExpired | 签署超时 | SYSTEM |
| InfoRejected | InfoSubmitted | 用户重新提交 | USER |
| ContractRejected | EnterpriseVerified | 重置状态 | SYSTEM |
| ContractExpired | EnterpriseVerified | 重置状态 | SYSTEM |

## 📁 文件结构规范

### 目录结构
```
internal/domains/certification/
├── entities/                                    # 实体层
│   ├── certification.go                         # 认证聚合根
│   ├── enterprise_info_submit_record.go         # 企业信息提交记录
│   ├── esign_contract_generate_record.go        # 合同生成记录
│   ├── esign_contract_sign_record.go            # 合同签署记录
│   └── value_objects/                           # 值对象
│       ├── enterprise_info.go                   # 企业信息
│       └── contract_info.go                     # 合同信息
├── enums/                                       # 枚举定义
│   ├── certification_status.go                 # 认证状态
│   ├── failure_reason.go                       # 失败原因
│   └── actor_type.go                           # 操作者类型
├── specifications/                             # 规格模式
│   └── certification_specifications.go         # 认证规格
├── services/                                   # 领域服务
│   ├── certification_aggregate_service.go      # 聚合服务
│   ├── enterprise_verification_service.go      # 企业验证服务
│   ├── contract_management_service.go          # 合同管理服务
│   ├── certification_workflow_orchestrator.go # 工作流编排器
│   ├── state_machine/                         # 状态机
│   │   ├── certification_state_machine.go     # 状态机核心
│   │   ├── state_config.go                    # 状态配置
│   │   └── esign_callback_handler.go          # 回调处理器
│   └── factories/                             # 工厂模式
│       └── certification_factory.go           # 认证工厂
├── repositories/                              # 仓储接口
│   ├── certification_command_repository.go    # 命令仓储
│   ├── certification_query_repository.go      # 查询仓储
│   ├── enterprise_info_repository.go          # 企业信息仓储
│   ├── contract_record_repository.go          # 合同记录仓储
│   └── queries/                              # 查询对象
│       ├── certification_queries.go          # 认证查询
│       └── list_certifications_query.go      # 列表查询
└── events/                                   # 领域事件
    ├── certification_events.go              # 事件定义
    └── event_handlers/                       # 事件处理器
        ├── certification_event_handler.go   # 认证事件处理
        └── notification_event_handler.go    # 通知处理
```

## 🔧 各层接口规范

### 1. 聚合根接口 (certification.go)
```go
type Certification struct {
    // 聚合根必须实现的核心方法
    
    // 状态转换
    CanTransitionTo(targetStatus CertificationStatus, actor ActorType) bool
    TransitionTo(targetStatus CertificationStatus, actor ActorType, reason string) error
    
    // 业务操作  
    SubmitEnterpriseInfo(info EnterpriseInfo) error
    ApplyContract() error
    HandleEsignCallback(callbackType string, success bool, data map[string]interface{}) error
    
    // 业务规则验证
    ValidateBusinessRules() error
    ValidateInvariance() error
    
    // 查询方法
    GetProgress() int
    IsUserActionRequired() bool
    GetAvailableActions() []string
}
```

### 2. 领域服务接口规范

#### 聚合服务
```go
type CertificationAggregateService interface {
    // 聚合管理
    CreateCertification(ctx context.Context, userID string) (*entities.Certification, error)
    LoadCertification(ctx context.Context, id string) (*entities.Certification, error)
    SaveCertification(ctx context.Context, cert *entities.Certification) error
    
    // 状态管理
    TransitionState(ctx context.Context, cert *entities.Certification, targetStatus enums.CertificationStatus, actor enums.ActorType, metadata map[string]interface{}) error
}
```

#### 工作流编排器
```go
type CertificationWorkflowOrchestrator interface {
    // 用户操作用例
    SubmitEnterpriseInfo(ctx context.Context, cmd *SubmitEnterpriseInfoCommand) (*WorkflowResult, error)
    ApplyContract(ctx context.Context, cmd *ApplyContractCommand) (*WorkflowResult, error)
    
    // e签宝回调处理
    HandleEnterpriseVerificationCallback(ctx context.Context, cmd *EsignCallbackCommand) error
    HandleContractSignCallback(ctx context.Context, cmd *EsignCallbackCommand) error
    
    // 异常处理
    HandleFailure(ctx context.Context, certificationID string, failureType string, reason string) error
    RetryOperation(ctx context.Context, certificationID string, operation string) error
}
```

### 3. 仓储接口规范

#### 命令仓储
```go
type CertificationCommandRepository interface {
    Create(ctx context.Context, cert entities.Certification) error
    Update(ctx context.Context, cert entities.Certification) error
    UpdateStatus(ctx context.Context, id string, status enums.CertificationStatus) error
    Delete(ctx context.Context, id string) error
    
    // 事务支持
    WithTx(tx interfaces.Transaction) CertificationCommandRepository
}
```

#### 查询仓储
```go
type CertificationQueryRepository interface {
    GetByID(ctx context.Context, id string) (*entities.Certification, error)
    GetByUserID(ctx context.Context, userID string) (*entities.Certification, error)
    List(ctx context.Context, query *queries.ListCertificationsQuery) ([]*entities.Certification, int64, error)
    
    // 业务查询
    GetPendingCertifications(ctx context.Context) ([]*entities.Certification, error)
    GetExpiredContracts(ctx context.Context) ([]*entities.Certification, error)
    GetStatistics(ctx context.Context, period TimePeriod) (*CertificationStats, error)
}
```

### 4. 应用服务接口规范
```go
type CertificationApplicationService interface {
    // 用户操作用例
    CreateCertification(ctx context.Context, cmd *commands.CreateCertificationCommand) (*responses.CertificationResponse, error)
    SubmitEnterpriseInfo(ctx context.Context, cmd *commands.SubmitEnterpriseInfoCommand) (*responses.CertificationResponse, error)
    ApplyContract(ctx context.Context, cmd *commands.ApplyContractCommand) (*responses.ContractSignUrlResponse, error)
    
    // 查询用例  
    GetCertification(ctx context.Context, query *queries.GetCertificationQuery) (*responses.CertificationResponse, error)
    ListCertifications(ctx context.Context, query *queries.ListCertificationsQuery) (*responses.CertificationListResponse, error)
    
    // e签宝回调处理
    HandleEsignCallback(ctx context.Context, cmd *commands.EsignCallbackCommand) error
}
```

## 🔄 业务流程规范

### 主要业务流程

#### 流程1：用户提交企业信息
```
HTTP Request → Application Service → Workflow Orchestrator → Aggregate Service → Domain Entity → State Machine → Repository → Event Publishing
```

#### 流程2：e签宝企业认证回调
```  
HTTP Callback → Application Service → Workflow Orchestrator → Esign Callback Handler → Aggregate Service → State Machine → Repository → Event Publishing
```

#### 流程3：用户申请合同签署
```
HTTP Request → Application Service → Workflow Orchestrator → Contract Management Service → Aggregate Service → State Machine → Repository → Return Sign URL
```

#### 流程4：e签宝合同签署回调
```
HTTP Callback → Application Service → Workflow Orchestrator → Esign Callback Handler → Aggregate Service → State Machine → Repository → Event Publishing
```

## 📝 编码规范

### 命名规范
- **接口**: 以`Interface`或不带后缀结尾，如`CertificationRepository`
- **实现类**: 以`Impl`结尾，如`CertificationRepositoryImpl`  
- **领域服务**: 以`Service`结尾，如`CertificationAggregateService`
- **DTO**: 以`Command`、`Query`、`Response`结尾
- **事件**: 以`Event`结尾，如`CertificationCreatedEvent`

### 错误处理规范
- 使用领域特定的错误类型
- 错误消息必须使用中文
- 包含足够的上下文信息
- 支持错误链追踪

### 日志规范
- 关键业务操作必须记录日志
- 日志消息使用中文
- 包含关键业务标识符（用户ID、认证ID等）
- 使用结构化日志格式

### 缓存规范
- 查询仓储使用CachedBaseRepositoryImpl
- 根据查询频率选择合适的缓存策略
- 写操作自动失效相关缓存
- 支持手动缓存刷新

## 🧪 测试规范

### 单元测试
- 每个领域服务必须有单元测试
- 状态机转换逻辑必须全覆盖测试
- 业务规则验证必须有测试
- Mock外部依赖

### 集成测试  
- e签宝回调处理的集成测试
- 完整业务流程的端到端测试
- 数据库操作的集成测试

## 📊 监控规范

### 业务指标
- 认证申请创建数量
- 企业认证成功/失败率
- 合同签署成功/失败率
- 各状态的停留时间

### 技术指标
- 缓存命中率
- API响应时间
- 数据库查询性能
- 错误率和类型分布

## 🚀 部署规范

### 配置管理
- 环境相关配置外部化
- e签宝API配置独立管理
- 缓存配置可调整
- 日志级别可配置

### 数据迁移
- 状态枚举的兼容性迁移
- 历史数据的清理策略
- 缓存预热脚本

## 📋 验收标准

### 功能验收
- [ ] 完整的企业认证流程正常运行
- [ ] e签宝回调正确处理
- [ ] 状态转换严格按照规则执行
- [ ] 异常情况正确处理和恢复

### 技术验收  
- [ ] 各层职责清晰，无逻辑泄漏
- [ ] 代码符合DDD架构原则
- [ ] 缓存策略有效，性能提升明显
- [ ] 事件驱动架构正常工作

### 质量验收
- [ ] 单元测试覆盖率 > 80%
- [ ] 集成测试通过
- [ ] 代码质量检查通过
- [ ] 性能指标达标

---

本规范文档将指导整个certification域的重构实施，确保重构后的代码具有良好的可维护性、可扩展性和健壮性。