/*
 * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\IAllianceService.cs
 * Created: 2025-10-19
 * Last Modified: 2025-10-19
 * Description: Alliance service interface for coordinating alliance-related business logic operations including coalition system, research trees, territory management, democratic decision-making, and multi-alliance coordination that preserves individual alliance identity
 * Last Edit Notes: Initial creation with comprehensive alliance management operations including coalition mechanics (core innovation), democratic systems, and anti-exploitation measures
 */

using ShadowedRealms.Core.Models;

namespace ShadowedRealms.Core.Interfaces.Services
{
    /// <summary>
    /// Service interface for alliance-related business logic operations
    /// Implements coalition system (core innovation), research trees, territory management, democratic decision-making, and multi-alliance coordination
    /// </summary>
    public interface IAllianceService
    {
        #region Coalition System (Core Innovation)

        /// <summary>
        /// Forms coalition between multiple alliances while preserving individual alliance identity
        /// Core innovation: Multi-alliance cooperation without forced merging during KvK events
        /// </summary>
        /// <param name="initiatingAllianceId">Alliance proposing coalition formation</param>
        /// <param name="targetAllianceIds">Alliances to invite to coalition</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="coalitionType">Type of coalition (KvK, territorial, research)</param>
        /// <param name="proposedTerms">Coalition terms and conditions</param>
        /// <returns>Coalition formation result with voting requirements and timeline</returns>
        /// <exception cref="InvalidOperationException">Thrown when coalition requirements not met</exception>
        Task<(bool Success, string CoalitionId, Dictionary<string, object> VotingRequirements, DateTime VotingDeadline)>
            FormCoalitionAsync(int initiatingAllianceId, List<int> targetAllianceIds, int kingdomId, string coalitionType,
                Dictionary<string, object> proposedTerms);

        /// <summary>
        /// Processes coalition voting by alliance members with democratic consensus requirements
        /// </summary>
        /// <param name="allianceId">Alliance voting on coalition</param>
        /// <param name="coalitionId">Coalition being voted on</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="votingResults">Member voting results</param>
        /// <returns>Voting processing result and coalition status update</returns>
        Task<(bool VotePassed, double ApprovalPercentage, Dictionary<string, object> CoalitionStatus)>
            ProcessCoalitionVotingAsync(int allianceId, string coalitionId, int kingdomId,
                Dictionary<int, bool> votingResults);

        /// <summary>
        /// Manages coalition operations and shared resources while maintaining alliance independence
        /// </summary>
        /// <param name="coalitionId">Coalition to manage</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="operationType">Type of coalition operation</param>
        /// <param name="operationDetails">Details of the operation</param>
        /// <returns>Coalition operation result and member alliance updates</returns>
        Task<Dictionary<string, object>> ManageCoalitionOperationAsync(string coalitionId, int kingdomId,
            string operationType, Dictionary<string, object> operationDetails);

        /// <summary>
        /// Dissolves coalition with proper benefit distribution and alliance independence restoration
        /// </summary>
        /// <param name="coalitionId">Coalition to dissolve</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="dissolutionReason">Reason for dissolution</param>
        /// <returns>Dissolution result with benefit distribution details</returns>
        Task<(bool Success, Dictionary<string, object> BenefitDistribution, List<int> AffectedAlliances)>
            DissolveCoalitionAsync(string coalitionId, int kingdomId, string dissolutionReason);

        #endregion

        #region Research Trees & Collective Benefits

        /// <summary>
        /// Processes alliance research progression across Military, Economic, and Technology branches
        /// </summary>
        /// <param name="allianceId">Alliance conducting research</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="researchType">Research branch (Military/Economic/Technology)</param>
        /// <param name="researchNode">Specific research node to advance</param>
        /// <param name="memberContributions">Member resource contributions</param>
        /// <returns>Research advancement result and new benefits unlocked</returns>
        Task<(bool Success, int NewResearchLevel, Dictionary<string, object> UnlockedBenefits,
               Dictionary<int, long> ContributionTracking)>
            ProcessAllianceResearchAsync(int allianceId, int kingdomId, string researchType, string researchNode,
                Dictionary<int, Dictionary<string, long>> memberContributions);

        /// <summary>
        /// Calculates and applies collective research benefits to all alliance members
        /// </summary>
        /// <param name="allianceId">Alliance to apply benefits to</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Applied benefits breakdown by member and research branch</returns>
        Task<Dictionary<string, object>> ApplyCollectiveResearchBenefitsAsync(int allianceId, int kingdomId);

        /// <summary>
        /// Validates research prerequisites and member contribution requirements
        /// </summary>
        /// <param name="allianceId">Alliance attempting research</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="researchType">Research branch being validated</param>
        /// <param name="researchNode">Specific research node</param>
        /// <returns>Validation result with prerequisites and contribution requirements</returns>
        Task<(bool CanResearch, List<string> Prerequisites, Dictionary<string, long> RequiredContributions,
               Dictionary<string, object> EstimatedBenefits)>
            ValidateResearchRequirementsAsync(int allianceId, int kingdomId, string researchType, string researchNode);

        /// <summary>
        /// Tracks individual member contributions to alliance research for benefit distribution
        /// </summary>
        /// <param name="allianceId">Alliance to track contributions for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="timeframeDays">Period to analyze contributions</param>
        /// <returns>Member contribution analysis and benefit allocation recommendations</returns>
        Task<Dictionary<string, object>> TrackResearchContributionsAsync(int allianceId, int kingdomId,
            int timeframeDays = 30);

        #endregion

        #region Territory Management & Buildings

        /// <summary>
        /// Claims territory for alliance with validation of strategic value and defense requirements
        /// </summary>
        /// <param name="allianceId">Alliance claiming territory</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="territoryCoordinates">Territory coordinates to claim</param>
        /// <param name="territoryType">Type of territory (forest, mountain, plain)</param>
        /// <returns>Territory claim result with defense requirements and benefits</returns>
        /// <exception cref="InvalidOperationException">Thrown when territory cannot be claimed</exception>
        Task<(bool Success, string TerritoryId, Dictionary<string, object> DefenseRequirements,
               Dictionary<string, object> TerritoryBenefits)>
            ClaimTerritoryAsync(int allianceId, int kingdomId, (int X, int Y) territoryCoordinates, string territoryType);

        /// <summary>
        /// Constructs and upgrades alliance territory buildings that provide alliance-wide benefits
        /// </summary>
        /// <param name="allianceId">Alliance constructing building</param>
        /// <param name="territoryId">Territory to build in</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="buildingType">Type of building to construct</param>
        /// <param name="memberContributions">Member resource contributions</param>
        /// <returns>Construction result with completion time and alliance benefits</returns>
        Task<(bool Success, DateTime CompletionTime, Dictionary<string, object> AllianceBenefits,
               Dictionary<int, long> ContributionTracking)>
            ConstructTerritoryBuildingAsync(int allianceId, string territoryId, int kingdomId, string buildingType,
                Dictionary<int, Dictionary<string, long>> memberContributions);

        /// <summary>
        /// Manages contested zones around strategic forest areas with 50% speed reduction mechanics
        /// </summary>
        /// <param name="allianceId">Alliance operating in contested zone</param>
        /// <param name="contestedZoneId">Contested zone identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="operationType">Type of operation (claim, defend, raid)</param>
        /// <returns>Contested zone operation result and strategic implications</returns>
        Task<Dictionary<string, object>> ManageContestedZoneAsync(int allianceId, string contestedZoneId,
            int kingdomId, string operationType);

        /// <summary>
        /// Processes territory defense and castle banishment consequences for losing control
        /// </summary>
        /// <param name="allianceId">Alliance defending territory</param>
        /// <param name="territoryId">Territory under attack</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="defenseResult">Result of territory defense battle</param>
        /// <returns>Defense processing result with banishment consequences if applicable</returns>
        Task<(bool TerritoryRetained, Dictionary<string, object> BanishmentConsequences,
               Dictionary<string, object> DefenseRewards)>
            ProcessTerritoryDefenseAsync(int allianceId, string territoryId, int kingdomId,
                Dictionary<string, object> defenseResult);

        #endregion

        #region Democratic Alliance Management

        /// <summary>
        /// Conducts democratic host selection for KvK events with alliance voting
        /// </summary>
        /// <param name="allianceId">Alliance conducting host selection</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="kvkEventId">KvK event requiring host selection</param>
        /// <param name="hostCandidates">Players eligible for host role</param>
        /// <returns>Host selection result with voting details and appointed host</returns>
        Task<(bool Success, int SelectedHostId, Dictionary<string, object> VotingResults,
               Dictionary<string, object> HostPrivileges)>
            ConductDemocraticHostSelectionAsync(int allianceId, int kingdomId, string kvkEventId,
                List<int> hostCandidates);

        /// <summary>
        /// Processes alliance leadership elections with 5-tier hierarchy management
        /// </summary>
        /// <param name="allianceId">Alliance conducting elections</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="electionType">Type of election (Leader, Officer, etc.)</param>
        /// <param name="candidateIds">Players running for positions</param>
        /// <param name="memberVotes">Voting results from alliance members</param>
        /// <returns>Election result with new leadership assignments and role privileges</returns>
        Task<(bool Success, Dictionary<int, string> NewLeadershipRoles, Dictionary<string, object> RolePrivileges)>
            ProcessLeadershipElectionAsync(int allianceId, int kingdomId, string electionType, List<int> candidateIds,
                Dictionary<int, int> memberVotes);

        /// <summary>
        /// Manages role-based permissions across 5-tier leadership structure (Leader, Officers, Members, Recruits, Guests)
        /// </summary>
        /// <param name="allianceId">Alliance to manage permissions for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="playerId">Player to set permissions for</param>
        /// <param name="newRole">New role assignment</param>
        /// <param name="customPermissions">Custom permission overrides</param>
        /// <returns>Permission update result with granted authorities</returns>
        Task<(bool Success, string AssignedRole, Dictionary<string, bool> GrantedPermissions)>
            ManageRoleBasedPermissionsAsync(int allianceId, int kingdomId, int playerId, string newRole,
                Dictionary<string, bool> customPermissions = null);

        /// <summary>
        /// Conducts alliance-wide voting on major decisions with quorum requirements and fraud prevention
        /// </summary>
        /// <param name="allianceId">Alliance conducting vote</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="proposalType">Type of proposal being voted on</param>
        /// <param name="proposalDetails">Details of the proposal</param>
        /// <param name="memberVotes">Member voting responses</param>
        /// <returns>Voting result with approval status and implementation timeline</returns>
        Task<(bool ProposalPassed, double ApprovalPercentage, Dictionary<string, object> ImplementationPlan,
               List<string> FraudAlerts)>
            ConductAllianceVotingAsync(int allianceId, int kingdomId, string proposalType,
                Dictionary<string, object> proposalDetails, Dictionary<int, bool> memberVotes);

        #endregion

        #region Member Management & Social Systems

        /// <summary>
        /// Processes alliance membership applications and invitations with screening
        /// </summary>
        /// <param name="allianceId">Alliance processing membership</param>
        /// <param name="playerId">Player joining alliance</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="isInvitation">Whether this is invitation or application</param>
        /// <param name="applicantDetails">Player details for screening</param>
        /// <returns>Membership processing result with integration plan</returns>
        Task<(bool Success, string MembershipStatus, Dictionary<string, object> IntegrationPlan,
               DateTime ProbationEndDate)>
            ProcessMembershipAsync(int allianceId, int playerId, int kingdomId, bool isInvitation,
                Dictionary<string, object> applicantDetails);

        /// <summary>
        /// Manages member activity monitoring and contribution tracking
        /// </summary>
        /// <param name="allianceId">Alliance to monitor</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="timeframeDays">Period to analyze activity</param>
        /// <returns>Activity analysis with member engagement metrics and recommendations</returns>
        Task<Dictionary<string, object>> MonitorMemberActivityAsync(int allianceId, int kingdomId,
            int timeframeDays = 7);

        /// <summary>
        /// Processes member removal with proper benefit cleanup and territory adjustments
        /// </summary>
        /// <param name="allianceId">Alliance removing member</param>
        /// <param name="playerId">Player being removed</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="removalReason">Reason for removal</param>
        /// <param name="authorizingPlayerId">Player authorizing removal</param>
        /// <returns>Removal result with benefit cleanup and territory implications</returns>
        Task<(bool Success, Dictionary<string, object> BenefitsRemoved, bool TerritoryEviction,
               Dictionary<string, object> TransitionPlan)>
            ProcessMemberRemovalAsync(int allianceId, int playerId, int kingdomId, string removalReason,
                int authorizingPlayerId);

        /// <summary>
        /// Facilitates member-to-member resource trading within alliance network
        /// </summary>
        /// <param name="senderPlayerId">Player sending resources</param>
        /// <param name="receiverPlayerId">Player receiving resources</param>
        /// <param name="allianceId">Alliance facilitating trade</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="resourceTransfer">Resources to transfer</param>
        /// <returns>Trade processing result with transaction details</returns>
        Task<(bool Success, Dictionary<string, object> TransactionDetails, DateTime TransferCompletionTime)>
            ProcessMemberResourceTradingAsync(int senderPlayerId, int receiverPlayerId, int allianceId, int kingdomId,
                Dictionary<string, long> resourceTransfer);

        #endregion

        #region Treasury Management & Collective Resources

        /// <summary>
        /// Manages alliance treasury with collective resource pools and distribution systems
        /// </summary>
        /// <param name="allianceId">Alliance managing treasury</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="operationType">Treasury operation (deposit, withdraw, distribute)</param>
        /// <param name="resourceDetails">Resources involved in operation</param>
        /// <param name="authorizingPlayerId">Player authorizing operation</param>
        /// <returns>Treasury operation result with new balance and audit trail</returns>
        Task<(bool Success, Dictionary<string, long> NewTreasuryBalance, Dictionary<string, object> AuditEntry)>
            ManageTreasuryOperationAsync(int allianceId, int kingdomId, string operationType,
                Dictionary<string, long> resourceDetails, int authorizingPlayerId);

        /// <summary>
        /// Calculates and processes automatic treasury contributions from members
        /// </summary>
        /// <param name="allianceId">Alliance collecting contributions</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="contributionType">Type of automatic contribution</param>
        /// <returns>Contribution collection result with member compliance tracking</returns>
        Task<Dictionary<string, object>> ProcessAutomaticContributionsAsync(int allianceId, int kingdomId,
            string contributionType);

        /// <summary>
        /// Distributes collective benefits based on member contributions and activity
        /// </summary>
        /// <param name="allianceId">Alliance distributing benefits</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="distributionType">Type of benefit distribution</param>
        /// <param name="distributionCriteria">Criteria for benefit allocation</param>
        /// <returns>Distribution result with member benefit allocations</returns>
        Task<Dictionary<string, object>> DistributeCollectiveBenefitsAsync(int allianceId, int kingdomId,
            string distributionType, Dictionary<string, object> distributionCriteria);

        #endregion

        #region Communication & Coordination

        /// <summary>
        /// Manages alliance communication systems including chat, announcements, and coordinate sharing
        /// </summary>
        /// <param name="allianceId">Alliance managing communications</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="communicationType">Type of communication (chat, announcement, coordinates)</param>
        /// <param name="messageDetails">Communication content and metadata</param>
        /// <param name="senderPlayerId">Player sending communication</param>
        /// <returns>Communication processing result with delivery status</returns>
        Task<(bool Success, Dictionary<string, object> DeliveryStatus, DateTime MessageTimestamp)>
            ProcessAllianceCommunicationAsync(int allianceId, int kingdomId, string communicationType,
                Dictionary<string, object> messageDetails, int senderPlayerId);

        /// <summary>
        /// Coordinates alliance-wide events and synchronized activities
        /// </summary>
        /// <param name="allianceId">Alliance coordinating event</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="eventType">Type of event to coordinate</param>
        /// <param name="eventDetails">Event configuration and timing</param>
        /// <param name="organizingPlayerId">Player organizing event</param>
        /// <returns>Event coordination result with participant tracking</returns>
        Task<(bool Success, string EventId, Dictionary<string, object> ParticipantTracking, DateTime EventStartTime)>
            CoordinateAllianceEventAsync(int allianceId, int kingdomId, string eventType,
                Dictionary<string, object> eventDetails, int organizingPlayerId);

        /// <summary>
        /// Processes coordinate sharing and strategic intelligence distribution
        /// </summary>
        /// <param name="allianceId">Alliance sharing intelligence</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="intelligenceType">Type of intelligence being shared</param>
        /// <param name="intelligenceData">Intelligence data and coordinates</param>
        /// <param name="sharingPlayerId">Player sharing intelligence</param>
        /// <returns>Intelligence sharing result with distribution tracking</returns>
        Task<Dictionary<string, object>> ProcessIntelligenceSharingAsync(int allianceId, int kingdomId,
            string intelligenceType, Dictionary<string, object> intelligenceData, int sharingPlayerId);

        #endregion

        #region Alliance Progression & Leveling

        /// <summary>
        /// Processes alliance experience gains and level advancement with capacity/feature unlocks
        /// </summary>
        /// <param name="allianceId">Alliance gaining experience</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="experienceGained">Alliance experience points to add</param>
        /// <param name="experienceSource">Source of experience for tracking</param>
        /// <returns>Alliance level advancement result with unlocked features and capacity increases</returns>
        Task<(bool LevelUp, int NewLevel, Dictionary<string, object> UnlockedFeatures,
               Dictionary<string, int> CapacityIncreases)>
            ProcessAllianceExperienceAsync(int allianceId, int kingdomId, long experienceGained, string experienceSource);

        /// <summary>
        /// Calculates alliance power rating based on member contributions, research, and territory
        /// </summary>
        /// <param name="allianceId">Alliance to calculate power for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Alliance power calculation with detailed breakdown</returns>
        Task<(long TotalPower, Dictionary<string, long> PowerBreakdown)> CalculateAlliancePowerAsync(int allianceId,
            int kingdomId);

        /// <summary>
        /// Manages alliance achievements and milestone rewards
        /// </summary>
        /// <param name="allianceId">Alliance processing achievements</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="achievementType">Type of achievement unlocked</param>
        /// <param name="achievementData">Achievement progress and context</param>
        /// <returns>Achievement processing result with rewards and recognition</returns>
        Task<(bool NewAchievement, List<string> UnlockedAchievements, Dictionary<string, object> Rewards)>
            ProcessAllianceAchievementAsync(int allianceId, int kingdomId, string achievementType,
                Dictionary<string, object> achievementData);

        #endregion

        #region KvK Event Integration

        /// <summary>
        /// Integrates alliance into Kingdom vs Kingdom events while preserving alliance identity
        /// </summary>
        /// <param name="allianceId">Alliance participating in KvK</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="kvkEventId">KvK event identifier</param>
        /// <param name="participationLevel">Level of alliance participation</param>
        /// <returns>KvK integration result with role assignments and objectives</returns>
        Task<(bool Success, Dictionary<string, object> RoleAssignments, Dictionary<string, object> Objectives,
               Dictionary<string, object> RewardStructure)>
            IntegrateKvKParticipationAsync(int allianceId, int kingdomId, string kvkEventId, string participationLevel);

        /// <summary>
        /// Coordinates multi-alliance operations during KvK events through coalition system
        /// </summary>
        /// <param name="coalitionId">Coalition coordinating KvK operations</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="operationType">Type of coordinated operation</param>
        /// <param name="operationDetails">Operation parameters and objectives</param>
        /// <returns>Multi-alliance coordination result with individual alliance contributions</returns>
        Task<Dictionary<string, object>> CoordinateKvKOperationsAsync(string coalitionId, int kingdomId,
            string operationType, Dictionary<string, object> operationDetails);

        #endregion

        #region Anti-Exploitation & Balance

        /// <summary>
        /// Monitors alliance activities for exploitation attempts and maintains balanced progression
        /// </summary>
        /// <param name="allianceId">Alliance to monitor</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="monitoringPeriodDays">Period to analyze for suspicious activity</param>
        /// <returns>Monitoring result with risk assessment and recommended actions</returns>
        Task<(bool SuspiciousActivity, List<string> RiskFactors, Dictionary<string, object> RecommendedActions)>
            MonitorAllianceExploitationAsync(int allianceId, int kingdomId, int monitoringPeriodDays = 7);

        /// <summary>
        /// Validates alliance operations for fairness and prevents system gaming
        /// </summary>
        /// <param name="allianceId">Alliance performing operation</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="operationType">Type of operation being validated</param>
        /// <param name="operationDetails">Operation parameters for validation</param>
        /// <returns>Validation result with fairness assessment and restrictions</returns>
        Task<(bool IsValid, List<string> ValidationWarnings, Dictionary<string, object> AppliedRestrictions)>
            ValidateAllianceOperationAsync(int allianceId, int kingdomId, string operationType,
                Dictionary<string, object> operationDetails);

        /// <summary>
        /// Ensures skill-based alternatives exist for premium alliance features
        /// </summary>
        /// <param name="allianceId">Alliance accessing features</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="featureType">Premium feature being accessed</param>
        /// <returns>Skill-based alternatives and balance validation</returns>
        Task<Dictionary<string, object>> ValidateSkillBasedAlternativesAsync(int allianceId, int kingdomId,
            string featureType);

        #endregion

        #region Alliance Information & Analytics

        /// <summary>
        /// Retrieves comprehensive alliance profile including stats, members, and progression
        /// </summary>
        /// <param name="allianceId">Alliance to get profile for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="includePrivateData">Whether to include internal alliance data</param>
        /// <param name="requestingPlayerId">Player requesting profile</param>
        /// <returns>Alliance profile with appropriate data visibility</returns>
        Task<Dictionary<string, object>> GetAllianceProfileAsync(int allianceId, int kingdomId,
            bool includePrivateData = false, int? requestingPlayerId = null);

        /// <summary>
        /// Retrieves alliance rankings across different categories within kingdom
        /// </summary>
        /// <param name="allianceId">Alliance to get rankings for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Alliance rankings in power, members, research, territory, etc.</returns>
        Task<Dictionary<string, object>> GetAllianceRankingsAsync(int allianceId, int kingdomId);

        /// <summary>
        /// Analyzes alliance performance metrics and provides improvement recommendations
        /// </summary>
        /// <param name="allianceId">Alliance to analyze</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="analysisType">Type of analysis to perform</param>
        /// <param name="timeframeDays">Period to analyze</param>
        /// <returns>Performance analysis with metrics and recommendations</returns>
        Task<Dictionary<string, object>> AnalyzeAlliancePerformanceAsync(int allianceId, int kingdomId,
            string analysisType, int timeframeDays = 30);

        #endregion
    }
}