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