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)

	// 列表查询
	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)

	// 统计查询
	GetStatistics(ctx context.Context, period CertificationTimePeriod) (*CertificationStatistics, error)
	CountByStatus(ctx context.Context, status enums.CertificationStatus) (int64, 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"
)

// CertificationStatistics 认证统计信息
type CertificationStatistics struct {
	Period    CertificationTimePeriod `json:"period"`
	StartDate time.Time               `json:"start_date"`
	EndDate   time.Time               `json:"end_date"`

	// 总体统计
	TotalCertifications int64 `json:"total_certifications"`
	CompletedCount      int64 `json:"completed_count"`
	FailedCount         int64 `json:"failed_count"`
	InProgressCount     int64 `json:"in_progress_count"`

	// 状态分布
	StatusDistribution map[enums.CertificationStatus]int64 `json:"status_distribution"`

	// 失败原因分布
	FailureDistribution map[enums.FailureReason]int64 `json:"failure_distribution"`

	// 成功率统计
	SuccessRate          float64 `json:"success_rate"`
	EnterpriseVerifyRate float64 `json:"enterprise_verify_rate"`
	ContractSignRate     float64 `json:"contract_sign_rate"`

	// 时间统计
	AvgProcessingTime   time.Duration `json:"avg_processing_time"`
	AvgVerificationTime time.Duration `json:"avg_verification_time"`
	AvgSigningTime      time.Duration `json:"avg_signing_time"`

	// 重试统计
	RetryStats *CertificationRetryStats `json:"retry_stats"`
}

// 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"`
}