tyapi-server/internal/domains/certification/repositories/certification_query_repository.go

package repositories

import (
	"context"
	"time"

	"tyapi-server/internal/domains/certification/entities"
	"tyapi-server/internal/domains/certification/enums"
	"tyapi-server/internal/domains/certification/repositories/queries"
)

// CertificationQueryRepository 认证查询仓储接口
// 专门处理认证数据的查询操作，符合CQRS模式
type CertificationQueryRepository interface {
	// 基础查询操作
	GetByID(ctx context.Context, id string) (*entities.Certification, error)
	GetByUserID(ctx context.Context, userID string) (*entities.Certification, error)
	Exists(ctx context.Context, id string) (bool, error)
	ExistsByUserID(ctx context.Context, userID string) (bool, error)

	// 列表查询
	List(ctx context.Context, query *queries.ListCertificationsQuery) ([]*entities.Certification, int64, error)
	ListByUserIDs(ctx context.Context, userIDs []string) ([]*entities.Certification, error)
	ListByStatus(ctx context.Context, status enums.CertificationStatus, limit int) ([]*entities.Certification, error)

	// 业务查询
	FindByAuthFlowID(ctx context.Context, authFlowID string) (*entities.Certification, error)
	FindByEsignFlowID(ctx context.Context, esignFlowID string) (*entities.Certification, error)
	ListPendingRetry(ctx context.Context, maxRetryCount int) ([]*entities.Certification, error)
	GetPendingCertifications(ctx context.Context) ([]*entities.Certification, error)
	GetExpiredContracts(ctx context.Context) ([]*entities.Certification, error)
	GetCertificationsByDateRange(ctx context.Context, startDate, endDate time.Time) ([]*entities.Certification, error)
	GetUserActiveCertification(ctx context.Context, userID string) (*entities.Certification, error)

	CountByFailureReason(ctx context.Context, reason enums.FailureReason) (int64, error)
	GetProgressStatistics(ctx context.Context) (*CertificationProgressStats, error)

	// 搜索查询
	SearchByCompanyName(ctx context.Context, companyName string, limit int) ([]*entities.Certification, error)
	SearchByLegalPerson(ctx context.Context, legalPersonName string, limit int) ([]*entities.Certification, error)

	// 缓存相关
	InvalidateCache(ctx context.Context, keys ...string) error
	RefreshCache(ctx context.Context, certificationID string) error
}

// CertificationTimePeriod 时间周期枚举
type CertificationTimePeriod string

const (
	PeriodDaily   CertificationTimePeriod = "daily"
	PeriodWeekly  CertificationTimePeriod = "weekly"
	PeriodMonthly CertificationTimePeriod = "monthly"
	PeriodYearly  CertificationTimePeriod = "yearly"
)


// CertificationProgressStats 进度统计信息
type CertificationProgressStats struct {
	StatusProgress       map[enums.CertificationStatus]int64 `json:"status_progress"`
	ProgressDistribution map[int]int64                       `json:"progress_distribution"` // key: progress percentage

	// 各阶段耗时统计
	StageTimeStats map[string]*CertificationStageTimeInfo `json:"stage_time_stats"`
}

// CertificationStageTimeInfo 阶段耗时信息
type CertificationStageTimeInfo struct {
	StageName   string        `json:"stage_name"`
	AverageTime time.Duration `json:"average_time"`
	MinTime     time.Duration `json:"min_time"`
	MaxTime     time.Duration `json:"max_time"`
	SampleCount int64         `json:"sample_count"`
}

// CertificationRetryStats 重试统计信息
type CertificationRetryStats struct {
	TotalRetries      int64   `json:"total_retries"`
	SuccessfulRetries int64   `json:"successful_retries"`
	FailedRetries     int64   `json:"failed_retries"`
	RetrySuccessRate  float64 `json:"retry_success_rate"`

	// 各阶段重试统计
	EnterpriseRetries int64 `json:"enterprise_retries"`
	ContractRetries   int64 `json:"contract_retries"`

	// 重试原因分布
	RetryReasonStats map[enums.FailureReason]int64 `json:"retry_reason_stats"`
}