/*
 * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Admin\Services\Interfaces\IAdminAnalyticsService.cs
 * Created: 2025-10-30
 * Last Modified: 2025-10-31
 * Description: Interface for admin analytics and dashboard data services - matches controller requirements
 * Last Edit Notes: FIXED - Removed Controllers namespace import that was causing AntiPayToWinMetricsModel ambiguity
 */

using ShadowedRealms.Admin.Controllers;
using ShadowedRealms.Admin.Models;

namespace ShadowedRealms.Admin.Services.Interfaces
{
    /// <summary>
    /// Service interface for administrative analytics and dashboard data
    /// </summary>
    public interface IAdminAnalyticsService
    {
        #region Dashboard Overview Methods

        /// <summary>
        /// Get high-level dashboard statistics
        /// </summary>
        Task<DashboardOverviewStatsModel> GetDashboardOverviewStatsAsync();

        /// <summary>
        /// Get recent activity feed for dashboard
        /// </summary>
        Task<List<AdminActivityModel>> GetRecentActivityFeedAsync(int count = 20);

        /// <summary>
        /// Get system health status indicators
        /// </summary>
        Task<SystemHealthModel> GetSystemHealthStatusAsync();

        /// <summary>
        /// Get critical alerts requiring admin attention
        /// </summary>
        Task<List<AdminAlertModel>> GetCriticalAlertsAsync();

        #endregion

        #region Kingdom Analytics

        /// <summary>
        /// Get kingdom population and health metrics
        /// </summary>
        Task<List<KingdomHealthModel>> GetKingdomHealthMetricsAsync();

        /// <summary>
        /// Get KvK participation and performance data
        /// </summary>
        Task<KvkAnalyticsModel> GetKvkParticipationAnalysisAsync();

        /// <summary>
        /// Get kingdom merger recommendations
        /// </summary>
        Task<List<KingdomMergerRecommendationModel>> GetKingdomMergerRecommendationsAsync();

        #endregion

        #region Combat Analytics

        /// <summary>
        /// Get combat activity trends and outcomes
        /// </summary>
        Task<CombatTrendsModel> GetCombatTrendsAnalysisAsync(TimeSpan period);

        /// <summary>
        /// Get F2P vs spender combat effectiveness analysis
        /// </summary>
        Task<BalanceAnalyticsModel> GetCombatBalanceAnalysisAsync();

        /// <summary>
        /// Get field interception usage and success rates
        /// </summary>
        Task<FieldInterceptionAnalyticsModel> GetFieldInterceptionAnalyticsAsync();

        #endregion

        #region Monetization Analytics

        /// <summary>
        /// Get revenue and spending pattern analysis
        /// </summary>
        Task<RevenueAnalyticsModel> GetRevenueAnalyticsAsync(TimeSpan period);

        /// <summary>
        /// Get player spending health and protection metrics
        /// </summary>
        Task<SpendingHealthModel> GetSpendingHealthAnalysisAsync();

        /// <summary>
        /// Get anti-pay-to-win effectiveness metrics
        /// </summary>
        Task<AntiPayToWinMetricsModel> GetAntiPayToWinMetricsAsync();

        /// <summary>
        /// Get VIP tier distribution and spending analysis
        /// </summary>
        Task<VipAnalyticsModel> GetVipDistributionAnalysisAsync();

        #endregion

        #region System Performance

        /// <summary>
        /// Get database performance metrics
        /// </summary>
        Task<DatabasePerformanceModel> GetDatabasePerformanceAsync();

        /// <summary>
        /// Get API response time and error metrics
        /// </summary>
        Task<ApiPerformanceModel> GetApiPerformanceMetricsAsync();

        /// <summary>
        /// Get server resource utilization
        /// </summary>
        Task<ServerResourcesModel> GetServerResourceUtilizationAsync();

        #endregion
    }
}