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. **流程完整性**: 通过状态机验证和流程完整性检查确保业务逻辑正确性

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