# 认证流程状态管理说明

## 概述

认证流程已简化为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. **向后兼容**：如需添加新状态，注意保持向后兼容性