team/tyapi-server

Fork 0

Files

liangzai b03129667a temp

2025-07-21 15:13:26 +08:00

14 KiB

Raw Blame History

Certification域DDD重构规范文档

📋 概述

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

🎯 重构目标

业务目标

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

技术目标

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

🏗️ 架构设计

分层架构图

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

📊 状态设计

状态枚举定义

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)

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. 领域服务接口规范

聚合服务

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
}

工作流编排器

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. 仓储接口规范

命令仓储

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
}

查询仓储

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. 应用服务接口规范

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域的重构实施，确保重构后的代码具有良好的可维护性、可扩展性和健壮性。

14 KiB Raw Blame History Unescape Escape

Certification域DDD重构规范文档

📋 概述

🎯 重构目标

业务目标

技术目标

🏗️ 架构设计

分层架构图

📊 状态设计

状态枚举定义

状态转换规则

📁 文件结构规范

目录结构

🔧 各层接口规范

1. 聚合根接口 (certification.go)

2. 领域服务接口规范

聚合服务

工作流编排器

3. 仓储接口规范

命令仓储

查询仓储

4. 应用服务接口规范

🔄 业务流程规范

主要业务流程

流程1：用户提交企业信息

流程2：e签宝企业认证回调

流程3：用户申请合同签署

流程4：e签宝合同签署回调

📝 编码规范

命名规范

错误处理规范

日志规范

缓存规范

🧪 测试规范

单元测试

集成测试

📊 监控规范

业务指标

技术指标

🚀 部署规范

配置管理

数据迁移

📋 验收标准

功能验收

技术验收

质量验收

14 KiB

Raw Blame History