139 lines
4.2 KiB
Markdown
139 lines
4.2 KiB
Markdown
# 认证流程状态管理说明
|
||
|
||
## 概述
|
||
|
||
认证流程已简化为6个主要状态，移除了失败和拒绝状态，使流程更加简洁和直观。
|
||
|
||
## 状态定义
|
||
|
||
### 主要状态
|
||
|
||
| 状态 | 状态码 | 中文名称 | 进度 | 说明 |
|
||
|------|--------|----------|------|------|
|
||
| `pending` | 待认证 | 0% | 等待用户提交企业信息 |
|
||
| `info_submitted` | 已提交企业信息 | 20% | 用户已提交企业信息 |
|
||
| `enterprise_verified` | 已企业认证 | 40% | 企业认证已完成 |
|
||
| `contract_applied` | 已申请合同 | 60% | 合同已申请 |
|
||
| `contract_signed` | 已签署合同 | 80% | 合同已签署 |
|
||
| `completed` | 认证完成 | 100% | 认证流程已完成 |
|
||
|
||
## 状态转换规则
|
||
|
||
### 转换流程
|
||
```
|
||
待认证 → 已提交企业信息 → 已企业认证 → 已申请合同 → 已签署合同 → 认证完成
|
||
```
|
||
|
||
### 特殊规则
|
||
- **重新提交企业信息**：在"已提交企业信息"状态时，用户可以重新提交企业信息（状态不变，但更新时间戳）
|
||
- **单向流程**：除了重新提交企业信息外，其他步骤都不能回头
|
||
- **无失败状态**：简化后的流程不包含失败和拒绝状态
|
||
|
||
## 代码结构
|
||
|
||
### 1. 状态枚举 (`enums/certification_status.go`)
|
||
```go
|
||
// 主要状态
|
||
StatusPending // 待认证
|
||
StatusInfoSubmitted // 已提交企业信息
|
||
StatusEnterpriseVerified // 已企业认证
|
||
StatusContractApplied // 已申请合同
|
||
StatusContractSigned // 已签署合同
|
||
StatusCompleted // 认证完成
|
||
```
|
||
|
||
### 2. 状态管理器 (`services/state_config.go`)
|
||
- `CertificationStateManager`：管理状态配置和转换规则
|
||
- 配置直接写在Go代码中，无需外部配置文件
|
||
- 提供状态查询、转换验证、进度计算等功能
|
||
|
||
### 3. 状态机 (`services/state_machine.go`)
|
||
- `CertificationStateMachine`：执行状态转换的核心组件
|
||
- 处理状态转换的权限验证和时间戳更新
|
||
- 提供状态转换历史记录
|
||
|
||
### 4. 认证实体 (`entities/certification.go`)
|
||
- 包含状态相关的便捷方法
|
||
- 提供状态查询和验证功能
|
||
- 与状态机配合使用
|
||
|
||
## 使用方法
|
||
|
||
### 1. 创建状态机
|
||
```go
|
||
stateMachine := NewCertificationStateMachine(certRepo, logger)
|
||
```
|
||
|
||
### 2. 执行状态转换
|
||
```go
|
||
err := stateMachine.TransitionTo(
|
||
ctx,
|
||
certificationID,
|
||
enums.StatusInfoSubmitted,
|
||
true, // isUser
|
||
false, // isAdmin
|
||
metadata,
|
||
)
|
||
```
|
||
|
||
### 3. 检查状态转换权限
|
||
```go
|
||
canTransition, reason := stateMachine.CanTransition(
|
||
currentStatus,
|
||
targetStatus,
|
||
isUser,
|
||
isAdmin,
|
||
)
|
||
```
|
||
|
||
### 4. 获取进度信息
|
||
```go
|
||
progress := stateMachine.GetProgressPercentage(currentStatus)
|
||
nextStatuses := stateMachine.GetValidNextStatuses(currentStatus, isUser, isAdmin)
|
||
```
|
||
|
||
## 权限控制
|
||
|
||
### 用户权限
|
||
- 可以执行：提交企业信息、企业认证、申请合同、签署合同
|
||
- 不能执行：完成认证（系统自动执行）
|
||
|
||
### 管理员权限
|
||
- 简化后的流程不需要管理员操作
|
||
|
||
### 系统权限
|
||
- 可以执行：完成认证（自动执行）
|
||
|
||
## 时间戳管理
|
||
|
||
状态转换时会自动更新对应的时间戳字段：
|
||
|
||
| 状态 | 时间戳字段 |
|
||
|------|------------|
|
||
| `info_submitted` | `InfoSubmittedAt` |
|
||
| `enterprise_verified` | `FaceVerifiedAt` (复用) |
|
||
| `contract_applied` | `ContractAppliedAt` |
|
||
| `contract_signed` | `ContractSignedAt` |
|
||
| `completed` | `CompletedAt` |
|
||
|
||
## 扩展说明
|
||
|
||
### 添加新状态
|
||
1. 在 `enums/certification_status.go` 中添加新状态常量
|
||
2. 在 `services/state_config.go` 中添加状态配置
|
||
3. 在 `entities/certification.go` 中更新相关方法
|
||
|
||
### 修改转换规则
|
||
1. 在 `services/state_config.go` 的 `initStateConfigs()` 方法中修改转换配置
|
||
2. 更新 `NextValidStatuses` 和转换规则
|
||
|
||
### 自定义验证
|
||
在应用服务层添加业务逻辑验证，状态机只负责状态转换的权限控制。
|
||
|
||
## 注意事项
|
||
|
||
1. **状态一致性**：确保数据库中的状态与代码中的状态枚举一致
|
||
2. **权限验证**：在应用服务层进行详细的业务逻辑验证
|
||
3. **事务处理**：状态转换应在数据库事务中执行
|
||
4. **日志记录**：状态转换会自动记录日志，便于问题排查
|
||
5. **向后兼容**：如需添加新状态，注意保持向后兼容性 |