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