tyapi-server/docs/认证流程状态管理说明.md

认证流程状态管理说明

概述

认证流程已简化为6个主要状态，移除了失败和拒绝状态，使流程更加简洁和直观。

状态定义

主要状态

状态	状态码	中文名称	进度	说明
pending	待认证	0%	等待用户提交企业信息
info_submitted	已提交企业信息	20%	用户已提交企业信息
enterprise_verified	已企业认证	40%	企业认证已完成
contract_applied	已申请合同	60%	合同已申请
contract_signed	已签署合同	80%	合同已签署
completed	认证完成	100%	认证流程已完成

状态转换规则

转换流程

待认证 → 已提交企业信息 → 已企业认证 → 已申请合同 → 已签署合同 → 认证完成

特殊规则

• 重新提交企业信息：在"已提交企业信息"状态时，用户可以重新提交企业信息（状态不变，但更新时间戳）
• 单向流程：除了重新提交企业信息外，其他步骤都不能回头
• 无失败状态：简化后的流程不包含失败和拒绝状态

代码结构

1. 状态枚举 (enums/certification_status.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. 创建状态机

stateMachine := NewCertificationStateMachine(certRepo, logger)

2. 执行状态转换

err := stateMachine.TransitionTo(
    ctx,
    certificationID,
    enums.StatusInfoSubmitted,
    true,  // isUser
    false, // isAdmin
    metadata,
)

3. 检查状态转换权限

canTransition, reason := stateMachine.CanTransition(
    currentStatus,
    targetStatus,
    isUser,
    isAdmin,
)

4. 获取进度信息

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. 向后兼容：如需添加新状态，注意保持向后兼容性