tyapi-server/internal/domains/certification/entities/certification.go

package entities

import (
	"time"

	"tyapi-server/internal/domains/certification/enums"

	"github.com/google/uuid"

	"gorm.io/gorm"
)

// Certification 认证申请实体
// 这是企业认证流程的核心实体，负责管理整个认证申请的生命周期
type Certification struct {
	// 基础信息
	ID     string                    `gorm:"primaryKey;type:varchar(36)" json:"id" comment:"认证申请唯一标识"`
	UserID string                    `gorm:"type:varchar(36);not null;index" json:"user_id" comment:"申请用户ID"`
	Status enums.CertificationStatus `gorm:"type:varchar(50);not null;index" json:"status" comment:"当前认证状态"`

	// 流程节点时间戳 - 记录每个关键步骤的完成时间
	InfoSubmittedAt      *time.Time `json:"info_submitted_at,omitempty" comment:"企业信息提交时间"`
	EnterpriseVerifiedAt *time.Time `json:"enterprise_verified_at,omitempty" comment:"企业认证完成时间"`
	ContractAppliedAt    *time.Time `json:"contract_applied_at,omitempty" comment:"合同申请时间"`
	ContractSignedAt     *time.Time `json:"contract_signed_at,omitempty" comment:"合同签署完成时间"`
	CompletedAt          *time.Time `json:"completed_at,omitempty" comment:"认证完成时间"`

	// 合同信息 - 电子合同相关链接
	ContractFileID  string `gorm:"type:varchar(500)" json:"contract_file_id,omitempty" comment:"合同文件ID"`
	EsignFlowID     string `gorm:"type:varchar(500)" json:"esign_flow_id,omitempty" comment:"签署流程ID"`
	ContractURL     string `gorm:"type:varchar(500)" json:"contract_url,omitempty" comment:"合同文件访问链接"`
	ContractSignURL string `gorm:"type:varchar(500)" json:"contract_sign_url,omitempty" comment:"合同签署链接"`

	// 认证信息
	AuthFlowID string `gorm:"type:varchar(500)" json:"auth_flow_id,omitempty" comment:"认证流程ID"`

	// 时间戳字段
	CreatedAt time.Time      `gorm:"autoCreateTime" json:"created_at" comment:"创建时间"`
	UpdatedAt time.Time      `gorm:"autoUpdateTime" json:"updated_at" comment:"更新时间"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"-" comment:"软删除时间"`
}

// TableName 指定数据库表名
func (Certification) TableName() string {
	return "certifications"
}

// BeforeCreate GORM钩子：创建前自动生成UUID
func (c *Certification) BeforeCreate(tx *gorm.DB) error {
	if c.ID == "" {
		c.ID = uuid.New().String()
	}
	return nil
}

// IsStatusChangeable 检查状态是否可以变更
func (c *Certification) IsStatusChangeable() bool {
	return !enums.IsFinalStatus(c.Status)
}

// GetStatusName 获取状态名称
func (c *Certification) GetStatusName() string {
	return enums.GetStatusName(c.Status)
}

// IsFinalStatus 判断是否为最终状态
func (c *Certification) IsFinalStatus() bool {
	return enums.IsFinalStatus(c.Status)
}

// GetStatusCategory 获取状态分类
func (c *Certification) GetStatusCategory() string {
	return enums.GetStatusCategory(c.Status)
}

// GetStatusPriority 获取状态优先级
func (c *Certification) GetStatusPriority() int {
	return enums.GetStatusPriority(c.Status)
}

// GetProgressPercentage 获取进度百分比
func (c *Certification) GetProgressPercentage() int {
	progressMap := map[enums.CertificationStatus]int{
		enums.StatusPending:            0,
		enums.StatusInfoSubmitted:      20,
		enums.StatusEnterpriseVerified: 40,
		enums.StatusContractApplied:    60,
		enums.StatusContractSigned:     80,
		enums.StatusCompleted:          100,
	}

	if progress, exists := progressMap[c.Status]; exists {
		return progress
	}
	return 0
}

// IsUserActionRequired 检查是否需要用户操作
func (c *Certification) IsUserActionRequired() bool {
	userActionRequired := map[enums.CertificationStatus]bool{
		enums.StatusPending:            true,
		enums.StatusInfoSubmitted:      true,
		enums.StatusEnterpriseVerified: true,
		enums.StatusContractApplied:    true,
		enums.StatusContractSigned:     false,
		enums.StatusCompleted:          false,
	}

	if required, exists := userActionRequired[c.Status]; exists {
		return required
	}
	return false
}

// GetNextValidStatuses 获取下一个有效状态
func (c *Certification) GetNextValidStatuses() []enums.CertificationStatus {
	nextStatusMap := map[enums.CertificationStatus][]enums.CertificationStatus{
		enums.StatusPending:            {enums.StatusInfoSubmitted},
		enums.StatusInfoSubmitted:      {enums.StatusEnterpriseVerified, enums.StatusInfoSubmitted}, // 可以重新提交
		enums.StatusEnterpriseVerified: {enums.StatusContractApplied},
		enums.StatusContractApplied:    {enums.StatusContractSigned},
		enums.StatusContractSigned:     {enums.StatusCompleted},
		enums.StatusCompleted:          {},
	}

	if nextStatuses, exists := nextStatusMap[c.Status]; exists {
		return nextStatuses
	}
	return []enums.CertificationStatus{}
}

// CanTransitionTo 检查是否可以转换到指定状态
func (c *Certification) CanTransitionTo(targetStatus enums.CertificationStatus, isUser bool) (bool, string) {
	nextStatuses := c.GetNextValidStatuses()

	for _, nextStatus := range nextStatuses {
		if nextStatus == targetStatus {
			// 检查权限
			if isUser && !c.IsUserActionRequired() {
				return false, "当前状态不需要用户操作"
			}
			return true, ""
		}
	}

	return false, "不支持的状态转换"
}