dukcapil/internal/contract/analytics_contract.go

package contract

import (
	"time"

	"github.com/google/uuid"
)

// AnalyticsDashboardRequest represents the request for analytics data
type AnalyticsDashboardRequest struct {
	StartDate    string     `form:"start_date" json:"start_date"`
	EndDate      string     `form:"end_date" json:"end_date"`
	DepartmentID *uuid.UUID `form:"department_id" json:"department_id,omitempty"`
	UserID       *uuid.UUID `form:"user_id" json:"user_id,omitempty"`
}

// AnalyticsDashboardResponse represents the complete analytics dashboard
type AnalyticsDashboardResponse struct {
	Summary              LetterSummaryStats           `json:"summary"`
	PriorityDistribution []PriorityDistribution       `json:"priority_distribution"`
	DepartmentStats      []DepartmentStats            `json:"department_stats"`
	MonthlyTrend         []MonthlyTrend               `json:"monthly_trend"`
	DepartmentsStats     []SimpleDepartmentStats      `json:"departments_stats,omitempty"`
	InstitutionStats     []InstitutionStats           `json:"institution_stats"`
	DailyActivity        []DailyActivity              `json:"daily_activity"`
	StatusDistribution   []StatusDistribution         `json:"status_distribution,omitempty"`
	TopSenders           []TopUserStats               `json:"top_senders,omitempty"`
	TopRecipients        []TopUserStats               `json:"top_recipients,omitempty"`
	ApprovalMetrics      *ApprovalMetrics             `json:"approval_metrics,omitempty"`
	ResponseTimeStats    *ResponseTimeStats           `json:"response_time_stats,omitempty"`
}

// LetterSummaryStats represents overall summary statistics
type LetterSummaryStats struct {
	TotalIncoming        int64   `json:"total_incoming"`
	TotalOutgoing        int64   `json:"total_outgoing"`
	WeekOverWeekGrowth   float64 `json:"week_over_week_growth"`
	MonthOverMonthGrowth float64 `json:"month_over_month_growth"`
	TotalPending         int64   `json:"total_pending,omitempty"`
	TotalApproved        int64   `json:"total_approved,omitempty"`
	TotalRejected        int64   `json:"total_rejected,omitempty"`
	TotalArchived        int64   `json:"total_archived,omitempty"`
	AvgProcessingTime    float64 `json:"avg_processing_time_hours,omitempty"`
	CompletionRate       float64 `json:"completion_rate,omitempty"`
}

// StatusDistribution represents letter distribution by status
type StatusDistribution struct {
	Status     string  `json:"status"`
	Count      int64   `json:"count"`
	Percentage float64 `json:"percentage"`
	Type       string  `json:"type"` // incoming or outgoing
}

// PriorityDistribution represents letter distribution by priority
type PriorityDistribution struct {
	PriorityID   string  `json:"priority_id"`
	PriorityName string  `json:"priority_name"`
	Level        int     `json:"level"`
	Count        int64   `json:"count"`
	Percentage   float64 `json:"percentage"`
	AvgResponseTime float64 `json:"avg_response_time_hours"`
}

// DepartmentStats represents statistics per department
type DepartmentStats struct {
	DepartmentID   uuid.UUID `json:"department_id"`
	DepartmentName string    `json:"department_name"`
	DepartmentCode string    `json:"department_code"`
	IncomingCount  int64     `json:"incoming_count"`
	OutgoingCount  int64     `json:"outgoing_count"`
	PendingCount   int64     `json:"pending_count"`
	AvgResponseTime float64  `json:"avg_response_time_hours"`
	CompletionRate float64   `json:"completion_rate"`
}

// MonthlyTrend represents monthly trend data
type MonthlyTrend struct {
	Month         string  `json:"month"`
	Year          int     `json:"year"`
	IncomingCount int64   `json:"incoming_count"`
	OutgoingCount int64   `json:"outgoing_count"`
	TotalCount    int64   `json:"total_count"`
	GrowthRate    float64 `json:"growth_rate"`
}

// TopUserStats represents top users by letter activity
type TopUserStats struct {
	UserID       uuid.UUID `json:"user_id"`
	UserName     string    `json:"user_name"`
	UserEmail    string    `json:"user_email"`
	Department   string    `json:"department"`
	LetterCount  int64     `json:"letter_count"`
	AvgResponseTime float64 `json:"avg_response_time_hours"`
}

// InstitutionStats represents statistics per institution
type InstitutionStats struct {
	InstitutionID   uuid.UUID `json:"institution_id"`
	InstitutionName string    `json:"institution_name"`
	InstitutionType string    `json:"institution_type"`
	IncomingCount   int64     `json:"incoming_count"`
	OutgoingCount   int64     `json:"outgoing_count"`
	TotalCount      int64     `json:"total_count"`
	LastActivity    time.Time `json:"last_activity"`
}

// ApprovalMetrics represents approval-related metrics
type ApprovalMetrics struct {
	TotalSubmitted       int64   `json:"total_submitted"`
	TotalApproved        int64   `json:"total_approved"`
	TotalRejected        int64   `json:"total_rejected"`
	TotalPending         int64   `json:"total_pending"`
	ApprovalRate         float64 `json:"approval_rate"`
	RejectionRate        float64 `json:"rejection_rate"`
	AvgApprovalTime      float64 `json:"avg_approval_time_hours"`
	AvgApprovalSteps     float64 `json:"avg_approval_steps"`
	BottleneckSteps      []BottleneckStep `json:"bottleneck_steps"`
}

// BottleneckStep represents approval steps that cause delays
type BottleneckStep struct {
	StepOrder       int     `json:"step_order"`
	ApproverName    string  `json:"approver_name"`
	AvgProcessTime  float64 `json:"avg_process_time_hours"`
	PendingCount    int64   `json:"pending_count"`
}

// ResponseTimeStats represents response time statistics
type ResponseTimeStats struct {
	MinResponseTime float64 `json:"min_response_time_hours"`
	MaxResponseTime float64 `json:"max_response_time_hours"`
	AvgResponseTime float64 `json:"avg_response_time_hours"`
	MedianResponseTime float64 `json:"median_response_time_hours"`
	P95ResponseTime float64 `json:"p95_response_time_hours"`
	P99ResponseTime float64 `json:"p99_response_time_hours"`
}

// SimpleDepartmentStats represents simplified department statistics
type SimpleDepartmentStats struct {
	DepartmentID   uuid.UUID `json:"department_id"`
	Department     string    `json:"department"`
	LetterCount    int64     `json:"letter_count"`
}

// DailyActivity represents daily activity data
type DailyActivity struct {
	Date          string `json:"date"`
	DayOfWeek     string `json:"day_of_week"`
	IncomingCount int64  `json:"incoming_count"`
	OutgoingCount int64  `json:"outgoing_count"`
	ApprovedCount int64  `json:"approved_count,omitempty"`
	RejectedCount int64  `json:"rejected_count,omitempty"`
	HourlyDistribution []HourlyActivity `json:"hourly_distribution,omitempty"`
}

// HourlyActivity represents hourly activity within a day
type HourlyActivity struct {
	Hour  int   `json:"hour"`
	Count int64 `json:"count"`
}

// LetterVolumeByTypeResponse represents letter volume grouped by type
type LetterVolumeByTypeResponse struct {
	Incoming IncomingLetterVolume `json:"incoming"`
	Outgoing OutgoingLetterVolume `json:"outgoing"`
}

// IncomingLetterVolume represents incoming letter statistics
type IncomingLetterVolume struct {
	Today     int64 `json:"today"`
	ThisWeek  int64 `json:"this_week"`
	ThisMonth int64 `json:"this_month"`
	ThisYear  int64 `json:"this_year"`
	Total     int64 `json:"total"`
}

// OutgoingLetterVolume represents outgoing letter statistics
type OutgoingLetterVolume struct {
	Today     int64 `json:"today"`
	ThisWeek  int64 `json:"this_week"`
	ThisMonth int64 `json:"this_month"`
	ThisYear  int64 `json:"this_year"`
	Total     int64 `json:"total"`
}