tyapi-server/docs/领域服务层设计.md

领域服务层设计文档

概述

本文档描述了认证域和用户域的领域服务层设计，包括核心业务逻辑、服务接口和职责分工。

认证域领域服务 (CertificationService)

服务职责

认证域领域服务负责管理企业认证流程的核心业务逻辑，包括：

• 认证申请的生命周期管理
• 状态机驱动的流程控制
• 人脸识别验证流程
• 合同申请和审核流程
• 认证完成和失败处理
• 进度跟踪和状态查询

核心方法

1. 认证申请管理

• CreateCertification(ctx, userID) - 创建认证申请
• GetCertificationByUserID(ctx, userID) - 根据用户 ID 获取认证申请
• GetCertificationByID(ctx, certificationID) - 根据 ID 获取认证申请
• GetCertificationWithDetails(ctx, certificationID) - 获取认证申请详细信息（包含关联记录）

2. 企业信息提交

• SubmitEnterpriseInfo(ctx, certificationID) - 提交企业信息，触发状态转换

3. 人脸识别验证

• InitiateFaceVerify(ctx, certificationID, realName, idCardNumber) - 发起人脸识别验证
• CompleteFaceVerify(ctx, faceVerifyID, isSuccess) - 完成人脸识别验证
• RetryFaceVerify(ctx, certificationID) - 重试人脸识别

4. 合同流程管理

• ApplyContract(ctx, certificationID) - 申请合同
• ApproveContract(ctx, certificationID, adminID, signingURL, approvalNotes) - 管理员审核通过
• RejectContract(ctx, certificationID, adminID, rejectReason) - 管理员拒绝
• CompleteContractSign(ctx, certificationID, contractURL) - 完成合同签署

5. 认证完成

• CompleteCertification(ctx, certificationID) - 完成认证流程
• RestartCertification(ctx, certificationID) - 重新开始认证流程

6. 记录查询

• GetFaceVerifyRecords(ctx, certificationID) - 获取人脸识别记录
• GetContractRecords(ctx, certificationID) - 获取合同记录

7. 进度和状态管理

• GetCertificationProgress(ctx, certificationID) - 获取认证进度信息
• UpdateOCRResult(ctx, certificationID, ocrRequestID, confidence) - 更新 OCR 识别结果

状态机集成

认证服务与状态机紧密集成，所有状态转换都通过状态机进行：

• 确保状态转换的合法性
• 自动更新相关时间戳
• 记录状态转换日志
• 支持权限控制（用户/管理员）

认证状态机 (CertificationStateMachine)

状态机职责

认证状态机负责管理认证流程的状态转换，包括：

• 状态转换规则定义
• 转换验证和权限控制
• 时间戳自动更新
• 元数据管理
• 流程完整性验证

核心方法

1. 状态转换管理

• CanTransition(from, to, isUser, isAdmin) - 检查是否可以转换到指定状态
• TransitionTo(ctx, certificationID, targetStatus, isUser, isAdmin, metadata) - 执行状态转换
• GetValidNextStatuses(currentStatus, isUser, isAdmin) - 获取当前状态可以转换到的下一个状态列表

2. 转换规则管理

• GetTransitionAction(from, to) - 获取状态转换对应的操作名称
• initializeTransitions() - 初始化状态转换规则

3. 流程验证和历史

• GetTransitionHistory(ctx, certificationID) - 获取状态转换历史
• ValidateCertificationFlow(ctx, certificationID) - 验证认证流程的完整性

状态转换规则

正常流程转换

• PENDING → INFO_SUBMITTED (用户提交企业信息)
• INFO_SUBMITTED → FACE_VERIFIED (人脸识别成功)
• FACE_VERIFIED → CONTRACT_APPLIED (申请合同)
• CONTRACT_APPLIED → CONTRACT_PENDING (系统处理)
• CONTRACT_PENDING → CONTRACT_APPROVED (管理员审核通过)
• CONTRACT_APPROVED → CONTRACT_SIGNED (用户签署)
• CONTRACT_SIGNED → COMPLETED (系统完成)

失败和重试转换

• INFO_SUBMITTED → FACE_FAILED (人脸识别失败)
• FACE_FAILED → FACE_VERIFIED (重试人脸识别)
• CONTRACT_PENDING → REJECTED (管理员拒绝)
• REJECTED → INFO_SUBMITTED (重新开始流程)
• CONTRACT_APPROVED → SIGN_FAILED (签署失败)
• SIGN_FAILED → CONTRACT_SIGNED (重试签署)

用户域领域服务

用户基础服务 (UserService)

服务职责

用户基础服务负责用户核心信息的管理，包括：

• 用户基础信息的 CRUD 操作
• 用户密码管理
• 用户状态验证
• 用户统计信息

核心方法

• IsPhoneRegistered(ctx, phone) - 检查手机号是否已注册
• GetUserByID(ctx, userID) - 根据 ID 获取用户信息
• GetUserByPhone(ctx, phone) - 根据手机号获取用户信息
• GetUserWithEnterpriseInfo(ctx, userID) - 获取用户信息（包含企业信息）
• UpdateUser(ctx, user) - 更新用户信息
• ChangePassword(ctx, userID, oldPassword, newPassword) - 修改用户密码
• ValidateUser(ctx, userID) - 验证用户信息
• GetUserStats(ctx) - 获取用户统计信息

企业信息服务 (EnterpriseService)

服务职责

企业信息服务专门负责企业信息的管理，包括：

• 企业信息的创建、更新和查询
• 企业认证状态管理
• 数据验证和业务规则检查
• 认证状态跟踪

核心方法

1. 企业信息管理

• CreateEnterpriseInfo(ctx, userID, companyName, unifiedSocialCode, legalPersonName, legalPersonID) - 创建企业信息
• GetEnterpriseInfo(ctx, userID) - 获取企业信息
• UpdateEnterpriseInfo(ctx, userID, companyName, unifiedSocialCode, legalPersonName, legalPersonID) - 更新企业信息
• GetEnterpriseInfoByUnifiedSocialCode(ctx, unifiedSocialCode) - 根据统一社会信用代码获取企业信息

2. 认证状态管理

• UpdateOCRVerification(ctx, userID, isVerified, rawData, confidence) - 更新 OCR 验证状态
• UpdateFaceVerification(ctx, userID, isVerified) - 更新人脸识别验证状态
• CompleteEnterpriseCertification(ctx, userID) - 完成企业认证

3. 数据验证和查询

• CheckUnifiedSocialCodeExists(ctx, unifiedSocialCode, excludeUserID) - 检查统一社会信用代码唯一性
• ValidateEnterpriseInfo(ctx, userID) - 验证企业信息完整性
• IsEnterpriseCertified(ctx, userID) - 检查用户是否已完成企业认证
• GetEnterpriseCertificationStatus(ctx, userID) - 获取企业认证状态

4. 用户信息集成

• GetUserWithEnterpriseInfo(ctx, userID) - 获取用户信息（包含企业信息）

短信验证码服务 (SMSCodeService)

服务职责

短信验证码服务负责短信验证码的完整生命周期管理，包括：

• 验证码生成和发送
• 验证码验证
• 频率限制控制
• 安全策略执行

核心方法

• SendCode(ctx, phone, scene, clientIP, userAgent) - 发送验证码
• VerifyCode(ctx, phone, code, scene) - 验证验证码
• CanResendCode(ctx, phone, scene) - 检查是否可以重新发送
• GetCodeStatus(ctx, phone, scene) - 获取验证码状态
• CheckRateLimit(ctx, phone, scene) - 检查发送频率限制

服务协作模式

服务依赖关系

CertificationService
├── 依赖 CertificationRepository
├── 依赖 FaceVerifyRecordRepository
├── 依赖 ContractRecordRepository
├── 依赖 LicenseUploadRecordRepository
├── 依赖 CertificationStateMachine
└── 提供认证流程管理功能

CertificationStateMachine
├── 依赖 CertificationRepository
├── 管理状态转换规则
└── 提供流程验证功能

UserService
├── 依赖 EnterpriseService (用于获取包含企业信息的用户数据)
└── 依赖 UserRepository

EnterpriseService
├── 依赖 UserRepository (用于验证用户存在性)
├── 依赖 EnterpriseInfoRepository
└── 提供企业信息相关功能

SMSCodeService
├── 依赖 SMSCodeRepository
├── 依赖 AliSMSService
├── 依赖 CacheService
└── 独立运行，不依赖其他领域服务

跨域调用

1. 认证域调用用户域

   • 认证服务在需要企业信息时调用企业服务
   • 通过依赖注入获取企业服务实例
   • 保持领域边界清晰

2. 应用服务层协调

   • 应用服务层负责协调不同领域服务
   • 处理跨域事务和一致性
   • 发布领域事件

事件驱动

1. 领域事件发布

   • 认证状态变更时发布事件
   • 企业信息创建/更新时发布事件
   • 用户注册/更新时发布事件
   • 支持异步处理和集成

2. 事件处理

   • 事件处理器响应领域事件
   • 执行副作用操作（如通知、日志）
   • 维护数据一致性

业务规则

企业信息只读规则

• 认证完成后企业信息不可修改
• 通过 IsReadOnly() 方法检查
• 在更新操作中强制执行

统一社会信用代码唯一性

• 每个统一社会信用代码只能对应一个用户
• 更新时排除当前用户 ID
• 支持并发检查

认证完成条件

• OCR 验证必须通过
• 人脸识别验证必须通过
• 两个条件都满足才能完成认证

状态转换规则

• 严格按照状态机定义的转换规则执行
• 支持用户和管理员权限控制
• 自动记录转换历史和时间戳

短信验证码规则

• 支持多种场景（注册、登录、修改密码等）
• 频率限制（最小间隔、每小时限制、每日限制）
• 开发模式跳过验证
• 自动过期和清理

错误处理

业务错误

• 使用有意义的错误消息
• 包含业务上下文信息
• 支持错误分类和处理

日志记录

• 记录关键业务操作
• 包含操作上下文（用户 ID、操作类型等）
• 支持问题排查和审计

性能考虑

数据库查询优化

• 合理使用索引
• 避免 N+1 查询问题
• 支持分页和缓存

并发控制

• 使用乐观锁或悲观锁
• 防止数据竞争条件
• 保证数据一致性

扩展性设计

新功能扩展

• 通过接口扩展新功能
• 保持向后兼容性
• 支持插件化架构

多租户支持

• 预留租户字段
• 支持数据隔离
• 便于未来扩展

测试策略

单元测试

• 测试核心业务逻辑
• 模拟外部依赖
• 覆盖边界条件

集成测试

• 测试服务间协作
• 验证数据一致性
• 测试完整业务流程

总结

领域服务层设计遵循 DDD 原则，实现了：

1. 职责分离:

   • 认证域负责流程管理和状态控制
   • 用户域分为基础服务和企业服务，各司其职
   • 短信服务独立运行

2. 业务封装: 核心业务逻辑封装在相应的领域服务中

3. 状态管理: 通过状态机管理复杂流程，支持历史追踪和流程验证

4. 数据一致性: 通过业务规则保证数据完整性

5. 可扩展性: 支持未来功能扩展和架构演进

6. 服务协作: 通过依赖注入实现服务间的松耦合协作

7. 流程完整性: 通过状态机验证和流程完整性检查确保业务逻辑正确性

这种设计为应用服务层提供了清晰的接口，便于实现复杂的业务流程协调，同时保持了良好的可维护性和可测试性。