team/tyapi-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

temp

Browse Source
This commit is contained in:
liangzai
2025-07-21 15:13:26 +08:00
parent 8ad1d7288e
commit b03129667a
41 changed files with 8497 additions and 3968 deletions
Download Patch File Download Diff File Expand all files Collapse all files

348
docs/Certification域DDD重构规范.md Normal file
View File

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