Tasks/frontend/src/app/core/models/admin.model.ts

/**
 * Admin Statistics Models
 * Type definitions for admin statistics and analytics
 */

/**
 * User growth data point for chart
 */
export interface UserGrowthData {
  date: string;
  count: number;
}

/**
 * Category popularity data for chart
 */
export interface CategoryPopularity {
  categoryId: string;
  categoryName: string;
  quizCount: number;
  percentage: number;
}

/**
 * System-wide statistics response
 */
export interface AdminStatistics {
  totalUsers: number;
  activeUsers: number; // Last 7 days
  totalQuizSessions: number;
  totalQuestions: number;
  averageQuizScore: number;
  userGrowth: UserGrowthData[];
  popularCategories: CategoryPopularity[];
  stats: {
    newUsersToday: number;
    newUsersThisWeek: number;
    newUsersThisMonth: number;
    quizzesToday: number;
    quizzesThisWeek: number;
    quizzesThisMonth: number;
  };
}

/**
 * API response wrapper for statistics
 */
export interface AdminStatisticsResponse {
  success: boolean;
  data: AdminStatistics;
  message?: string;
}

/**
 * Date range filter for statistics
 */
export interface DateRangeFilter {
  startDate: Date | null;
  endDate: Date | null;
}

/**
 * Cache entry for admin data
 */
export interface AdminCacheEntry<T> {
  data: T;
  timestamp: number;
  expiresAt: number;
}

/**
 * Guest session timeline data point
 */
export interface GuestSessionTimelineData {
  date: string;
  activeSessions: number;
  newSessions: number;
  convertedSessions: number;
}

/**
 * Conversion funnel stage
 */
export interface ConversionFunnelStage {
  stage: string;
  count: number;
  percentage: number;
  dropoff?: number;
}

/**
 * Guest analytics data
 */
export interface GuestAnalytics {
  totalGuestSessions: number;
  activeGuestSessions: number;
  conversionRate: number; // Percentage
  averageQuizzesPerGuest: number;
  totalConversions: number;
  timeline: GuestSessionTimelineData[];
  conversionFunnel: ConversionFunnelStage[];
  stats: {
    sessionsToday: number;
    sessionsThisWeek: number;
    sessionsThisMonth: number;
    conversionsToday: number;
    conversionsThisWeek: number;
    conversionsThisMonth: number;
  };
}

/**
 * API response wrapper for guest analytics
 */
export interface GuestAnalyticsResponse {
  success: boolean;
  data: GuestAnalytics;
  message?: string;
}

/**
 * Guest access settings
 */
export interface GuestSettings {
  guestAccessEnabled: boolean;
  maxQuizzesPerDay: number;
  maxQuestionsPerQuiz: number;
  sessionExpiryHours: number;
  upgradePromptMessage: string;
  allowedCategories?: string[];
  features?: {
    canBookmark: boolean;
    canViewHistory: boolean;
    canExportResults: boolean;
  };
}

/**
 * API response wrapper for guest settings
 */
export interface GuestSettingsResponse {
  success: boolean;
  data: GuestSettings;
  message?: string;
}

/**
 * Admin user data
 */
export interface AdminUser {
  id: string;
  username: string;
  email: string;
  role: 'user' | 'admin';
  isActive: boolean;
  createdAt: string;
  lastLoginAt?: string;
  profilePicture?: string | null;
  quizzesTaken?: number;
  averageScore?: number;
}

/**
 * User list query parameters
 */
export interface UserListParams {
  page?: number;
  limit?: number;
  role?: 'all' | 'user' | 'admin';
  isActive?: 'all' | 'active' | 'inactive';
  sortBy?: 'username' | 'email' | 'createdAt' | 'lastLoginAt';
  sortOrder?: 'asc' | 'desc';
  search?: string;
}

/**
 * Paginated user list response
 */
export interface AdminUserListResponse {
  success: boolean;
  data: {
    users: AdminUser[];
    pagination: {
      currentPage: number;
      totalPages: number;
      totalUsers: number;
      limit: number;
      hasNext: boolean;
      hasPrev: boolean;
    };
  };
  message?: string;
}

/**
 * User activity entry
 */
export interface UserActivity {
  id: string;
  type: 'login' | 'quiz_start' | 'quiz_complete' | 'bookmark' | 'profile_update' | 'role_change';
  description: string;
  timestamp: string;
  metadata?: {
    categoryName?: string;
    score?: number;
    questionCount?: number;
    oldRole?: string;
    newRole?: string;
  };
}

/**
 * Quiz history entry for user detail
 */
export interface UserQuizHistoryEntry {
  id: string;
  categoryId: string;
  categoryName: string;
  score: number;
  totalQuestions: number;
  percentage: number;
  timeTaken: number; // seconds
  completedAt: string;
}

/**
 * User statistics for detail view
 */
export interface UserStatistics {
  totalQuizzes: number;
  averageScore: number;
  totalQuestionsAnswered: number;
  correctAnswers: number;
  accuracy: number;
  currentStreak: number;
  longestStreak: number;
  totalTimeSpent: number; // seconds
  favoriteCategory?: {
    id: string;
    name: string;
    quizCount: number;
  };
  recentActivity: {
    lastQuizDate?: string;
    lastLoginDate?: string;
    quizzesThisWeek: number;
    quizzesThisMonth: number;
  };
}

/**
 * Detailed user profile
 */
export interface AdminUserDetail {
  id: string;
  username: string;
  email: string;
  role: 'user' | 'admin';
  isActive: boolean;
  createdAt: string;
  lastLoginAt?: string;
  statistics: UserStatistics;
  quizHistory: UserQuizHistoryEntry[];
  activityTimeline: UserActivity[];
  metadata?: {
    ipAddress?: string;
    userAgent?: string;
    registrationMethod?: 'direct' | 'guest_conversion';
    guestSessionId?: string;
  };
}

/**
 * API response wrapper for user detail
 */
export interface AdminUserDetailResponse {
  success: boolean;
  data: AdminUserDetail;
  message?: string;
}