/*
 * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\IKingdomService.cs
 * Created: 2025-10-19
 * Last Modified: 2025-10-26
 * Description: Kingdom service interface for coordinating kingdom-related business logic operations including KvK events, democratic leadership systems, population management, kingdom mergers, and multi-dimensional matchmaking systems
 * Last Edit Notes: Added missing methods required by KingdomController - GetKingdomInfoAsync, CoordinateKvKEventAsync, OperateRoyalCouncilAsync, CreateKingdomAsync, ManageMigrationIncentivesAsync, InitiateKingdomMergerAsync, ProcessMergerApprovalAsync, ExecuteKingdomMergerAsync
 */

using ShadowedRealms.Core.Models;

namespace ShadowedRealms.Core.Interfaces.Services
{
    /// <summary>
    /// Service interface for kingdom-related business logic operations
    /// Implements KvK events, democratic leadership systems, population management, and kingdom mergers with multi-dimensional analysis
    /// </summary>
    public interface IKingdomService
    {
        #region Kingdom vs Kingdom (KvK) Events

        /// <summary>
        /// Initiates Kingdom vs Kingdom event with multi-dimensional matchmaking analysis beyond raw power comparison
        /// Includes alliance coalition coordination and democratic host selection processes
        /// </summary>
        /// <param name="initiatingKingdomId">Kingdom initiating the KvK event</param>
        /// <param name="targetKingdomIds">Target kingdoms for KvK matchmaking</param>
        /// <param name="kvkType">Type of KvK event (standard, championship, alliance_war)</param>
        /// <param name="eventParameters">Event configuration and rules</param>
        /// <returns>KvK initiation result with matchmaking analysis and event timeline</returns>
        /// <exception cref="InvalidOperationException">Thrown when KvK requirements not met</exception>
        Task<(bool Success, string KvKEventId, Dictionary<string, object> MatchmakingAnalysis, DateTime EventStartTime)>
            InitiateKvKEventAsync(int initiatingKingdomId, List<int> targetKingdomIds, string kvkType,
                Dictionary<string, object> eventParameters);

        /// <summary>
        /// Processes multi-dimensional matchmaking analysis for KvK events considering power, activity, alliance structure, and strategic balance
        /// Goes beyond simple power comparison to ensure competitive and engaging matches
        /// </summary>
        /// <param name="kingdomIds">Kingdoms to analyze for matchmaking</param>
        /// <param name="kvkType">Type of KvK event for appropriate balancing</param>
        /// <param name="historicalData">Historical performance data for analysis</param>
        /// <returns>Comprehensive matchmaking analysis with balance recommendations</returns>
        Task<Dictionary<string, object>> ProcessMultiDimensionalMatchmakingAsync(List<int> kingdomIds, string kvkType,
            Dictionary<string, object> historicalData);

        /// <summary>
        /// Coordinates KvK event execution with alliance coalition support and victory condition tracking
        /// Supports multi-path success (Military/Economic/Diplomatic/Technology victories)
        /// </summary>
        /// <param name="kvkEventId">KvK event to coordinate</param>
        /// <param name="participatingKingdoms">Kingdoms participating in event</param>
        /// <param name="coalitionConfigurations">Alliance coalition setups for each kingdom</param>
        /// <returns>KvK coordination result with participant tracking and victory progress</returns>
        Task<Dictionary<string, object>> CoordinateKvKExecutionAsync(string kvkEventId,
            List<int> participatingKingdoms, Dictionary<int, List<int>> coalitionConfigurations);

        /// <summary>
        /// Coordinates KvK event - method expected by KingdomController
        /// </summary>
        /// <param name="kingdomId">Kingdom coordinating event</param>
        /// <param name="eventId">KvK event ID</param>
        /// <param name="coalitionSupport">Coalition support configuration</param>
        /// <param name="strategyUpdates">Strategy updates</param>
        /// <returns>Coordination result</returns>
        Task<Dictionary<string, object>> CoordinateKvKEventAsync(int kingdomId, string eventId,
            Dictionary<string, object> coalitionSupport, Dictionary<string, object> strategyUpdates);

        /// <summary>
        /// Processes KvK event conclusion with victory determination and reward distribution
        /// Supports multiple victory paths and calculates appropriate rewards for all participants
        /// </summary>
        /// <param name="kvkEventId">KvK event to conclude</param>
        /// <param name="eventResults">Complete event results and statistics</param>
        /// <returns>Event conclusion with victory analysis and reward distribution</returns>
        Task<(bool Success, Dictionary<string, object> VictoryAnalysis, Dictionary<int, Dictionary<string, object>> KingdomRewards)>
            ProcessKvKConclusionAsync(string kvkEventId, Dictionary<string, object> eventResults);

        /// <summary>
        /// Calculates and applies KvK season rankings and rewards based on performance across multiple events
        /// </summary>
        /// <param name="seasonId">KvK season to conclude</param>
        /// <param name="kingdomIds">Kingdoms participating in season</param>
        /// <returns>Season conclusion with rankings and seasonal rewards</returns>
        Task<Dictionary<string, object>> ProcessKvKSeasonConclusionAsync(string seasonId, List<int> kingdomIds);

        #endregion

        #region Democratic Leadership Systems

        /// <summary>
        /// Conducts democratic election for kingdom leadership positions with transparent voting processes
        /// Supports multiple leadership roles and ensures fair representation across alliances
        /// </summary>
        /// <param name="kingdomId">Kingdom conducting elections</param>
        /// <param name="electionType">Type of election (king, council, kvk_host)</param>
        /// <param name="candidateIds">Players eligible for leadership positions</param>
        /// <param name="voterEligibility">Criteria for voting eligibility</param>
        /// <returns>Election result with winner determination and vote transparency</returns>
        Task<(bool Success, Dictionary<int, string> ElectedLeaders, Dictionary<string, object> ElectionResults,
               Dictionary<string, object> VotingTransparency)>
            ConductDemocraticElectionAsync(int kingdomId, string electionType, List<int> candidateIds,
                Dictionary<string, object> voterEligibility);

        /// <summary>
        /// Manages democratic host selection for KvK events with alliance voting coordination
        /// Ensures fair representation and prevents alliance monopolization of leadership
        /// </summary>
        /// <param name="kingdomId">Kingdom selecting KvK host</param>
        /// <param name="kvkEventId">KvK event requiring host selection</param>
        /// <param name="allianceVotes">Voting results from each alliance</param>
        /// <param name="selectionCriteria">Criteria for host eligibility and selection</param>
        /// <returns>Host selection result with democratic validation and authority grants</returns>
        Task<(bool Success, int SelectedHostPlayerId, Dictionary<string, object> HostAuthorities,
               Dictionary<string, object> SelectionValidation)>
            ProcessDemocraticHostSelectionAsync(int kingdomId, string kvkEventId,
                Dictionary<int, Dictionary<int, int>> allianceVotes, Dictionary<string, object> selectionCriteria);

        /// <summary>
        /// Implements democratic tax distribution system with transparent allocation and fair representation
        /// Processes 4% resource tax from conquered kingdoms with royal distribution oversight
        /// </summary>
        /// <param name="distributingKingdomId">Kingdom distributing tax resources</param>
        /// <param name="taxCollectionData">Tax resources collected from conquered territories</param>
        /// <param name="distributionCriteria">Democratic criteria for resource allocation</param>
        /// <param name="councilApproval">Council approval for distribution plan</param>
        /// <returns>Tax distribution result with allocation transparency and recipient tracking</returns>
        Task<(bool Success, Dictionary<string, object> DistributionPlan, Dictionary<int, Dictionary<string, long>> AllianceAllocations,
               Dictionary<string, object> DistributionAudit)>
            ProcessDemocraticTaxDistributionAsync(int distributingKingdomId, Dictionary<string, long> taxCollectionData,
                Dictionary<string, object> distributionCriteria, Dictionary<int, bool> councilApproval);

        /// <summary>
        /// Manages royal council operations with democratic decision-making and transparent governance
        /// </summary>
        /// <param name="kingdomId">Kingdom managing council</param>
        /// <param name="councilAction">Action being proposed or executed</param>
        /// <param name="councilMembers">Current council membership</param>
        /// <param name="actionDetails">Details of the proposed action</param>
        /// <returns>Council action result with voting records and implementation plan</returns>
        Task<(bool Success, Dictionary<string, object> ActionResult, Dictionary<int, bool> CouncilVotes,
               Dictionary<string, object> ImplementationPlan)>
            ManageRoyalCouncilActionAsync(int kingdomId, string councilAction, List<int> councilMembers,
                Dictionary<string, object> actionDetails);

        /// <summary>
        /// Operates royal council - method expected by KingdomController
        /// </summary>
        /// <param name="kingdomId">Kingdom operating council</param>
        /// <param name="councilAction">Council action to take</param>
        /// <param name="councilMembers">Council members</param>
        /// <param name="actionDetails">Action details</param>
        /// <returns>Council operation result</returns>
        Task<(bool Success, Dictionary<string, object> ActionResult, Dictionary<int, bool> CouncilVotes,
               Dictionary<string, object> GovernanceTransparency)>
            OperateRoyalCouncilAsync(int kingdomId, string councilAction, List<int> councilMembers,
                Dictionary<string, object> actionDetails);

        #endregion

        #region Population Management

        /// <summary>
        /// Monitors kingdom population and triggers new kingdom creation when population exceeds capacity
        /// Maintains optimal 1,200-1,500 player target per kingdom with automatic scaling
        /// </summary>
        /// <param name="kingdomId">Kingdom to monitor population for</param>
        /// <returns>Population monitoring result with capacity analysis and scaling recommendations</returns>
        Task<Dictionary<string, object>> MonitorKingdomPopulationAsync(int kingdomId);

        /// <summary>
        /// Creates new kingdom when population thresholds are exceeded with smart player distribution
        /// Ensures balanced player distribution and maintains competitive integrity
        /// </summary>
        /// <param name="originKingdomId">Kingdom triggering new kingdom creation</param>
        /// <param name="newKingdomParameters">Parameters for new kingdom configuration</param>
        /// <returns>New kingdom creation result with player distribution plan</returns>
        Task<(bool Success, int NewKingdomId, Dictionary<string, object> KingdomConfiguration,
               Dictionary<string, object> PlayerDistributionPlan)>
            CreateNewKingdomAsync(int originKingdomId, Dictionary<string, object> newKingdomParameters);

        /// <summary>
        /// Creates new kingdom - method expected by KingdomController
        /// </summary>
        /// <param name="kingdomName">Name for new kingdom</param>
        /// <param name="initialSettings">Initial kingdom settings</param>
        /// <returns>Kingdom creation result</returns>
        Task<(bool Success, int NewKingdomId, Dictionary<string, object> MigrationIncentives)>
            CreateKingdomAsync(string kingdomName, Dictionary<string, object> initialSettings);

        /// <summary>
        /// Processes player kingdom selection with smart defaults to newest kingdom
        /// Balances player choice with population distribution needs
        /// </summary>
        /// <param name="playerId">Player selecting kingdom</param>
        /// <param name="preferredKingdomId">Player's preferred kingdom (optional)</param>
        /// <param name="selectionCriteria">Criteria for kingdom selection</param>
        /// <returns>Kingdom selection result with placement reasoning and benefits</returns>
        Task<(bool Success, int AssignedKingdomId, string PlacementReason, Dictionary<string, object> WelcomeBenefits)>
            ProcessKingdomSelectionAsync(int playerId, int? preferredKingdomId, Dictionary<string, object> selectionCriteria);

        /// <summary>
        /// Manages kingdom population balance through voluntary migration incentives
        /// Provides incentives for players to move to underpopulated kingdoms
        /// </summary>
        /// <param name="sourceKingdomId">Overpopulated source kingdom</param>
        /// <param name="targetKingdomId">Underpopulated target kingdom</param>
        /// <param name="migrationIncentives">Incentives offered for migration</param>
        /// <returns>Migration management result with participant tracking and incentive distribution</returns>
        Task<Dictionary<string, object>> ManagePopulationMigrationAsync(int sourceKingdomId, int targetKingdomId,
            Dictionary<string, object> migrationIncentives);

        /// <summary>
        /// Manages migration incentives - method expected by KingdomController
        /// </summary>
        /// <param name="kingdomId">Kingdom managing migration</param>
        /// <param name="targetKingdomIds">Target kingdoms for migration</param>
        /// <param name="incentivePrograms">Incentive programs</param>
        /// <returns>Migration management result</returns>
        Task<Dictionary<string, object>> ManageMigrationIncentivesAsync(int kingdomId,
            List<int> targetKingdomIds, Dictionary<string, object> incentivePrograms);

        /// <summary>
        /// Calculates optimal kingdom capacity based on server performance and player engagement metrics
        /// </summary>
        /// <param name="serverId">Server to calculate capacity for</param>
        /// <param name="performanceMetrics">Server performance data</param>
        /// <param name="engagementMetrics">Player engagement analytics</param>
        /// <returns>Capacity analysis with recommended kingdom limits and scaling strategies</returns>
        Task<Dictionary<string, object>> CalculateOptimalKingdomCapacityAsync(int serverId,
            Dictionary<string, object> performanceMetrics, Dictionary<string, object> engagementMetrics);

        #endregion

        #region Kingdom Mergers

        /// <summary>
        /// Processes voluntary kingdom merger with democratic approval and compatibility analysis
        /// Ensures mergers maintain competitive balance and player satisfaction
        /// </summary>
        /// <param name="initiatingKingdomId">Kingdom proposing merger</param>
        /// <param name="targetKingdomId">Kingdom being approached for merger</param>
        /// <param name="mergerTerms">Proposed terms and conditions for merger</param>
        /// <param name="compatibilityAnalysis">Analysis of kingdom compatibility</param>
        /// <returns>Merger processing result with democratic validation and integration plan</returns>
        /// <exception cref="InvalidOperationException">Thrown when merger requirements not met</exception>
        Task<(bool Success, string MergerId, Dictionary<string, object> DemocraticValidation,
               Dictionary<string, object> IntegrationPlan, DateTime MergerCompletionTime)>
            ProcessKingdomMergerAsync(int initiatingKingdomId, int targetKingdomId, Dictionary<string, object> mergerTerms,
                Dictionary<string, object> compatibilityAnalysis);

        /// <summary>
        /// Conducts democratic voting for kingdom merger approval with transparent processes
        /// Requires approval from both kingdoms with appropriate quorum requirements
        /// </summary>
        /// <param name="mergerId">Merger proposal to vote on</param>
        /// <param name="initiatingKingdomVotes">Votes from initiating kingdom</param>
        /// <param name="targetKingdomVotes">Votes from target kingdom</param>
        /// <param name="votingParameters">Parameters for voting validation</param>
        /// <returns>Merger voting result with approval status and implementation timeline</returns>
        Task<(bool MergerApproved, double InitiatingKingdomApproval, double TargetKingdomApproval,
               Dictionary<string, object> VotingAnalysis, DateTime ImplementationDeadline)>
            ProcessMergerVotingAsync(string mergerId, Dictionary<int, bool> initiatingKingdomVotes,
                Dictionary<int, bool> targetKingdomVotes, Dictionary<string, object> votingParameters);

        /// <summary>
        /// Executes kingdom merger with player integration, alliance consolidation, and benefit preservation
        /// Maintains competitive balance while combining kingdom resources and populations
        /// </summary>
        /// <param name="mergerId">Approved merger to execute</param>
        /// <param name="mergerConfiguration">Configuration for merger execution</param>
        /// <returns>Merger execution result with integration tracking and combined kingdom details</returns>
        Task<(bool Success, int MergedKingdomId, Dictionary<string, object> IntegrationResults,
               Dictionary<string, object> CombinedKingdomStatistics)>
            ExecuteKingdomMergerAsync(string mergerId, Dictionary<string, object> mergerConfiguration);

        /// <summary>
        /// Initiates kingdom merger - method expected by KingdomController
        /// </summary>
        /// <param name="kingdomId">Kingdom initiating merger</param>
        /// <param name="targetKingdomIds">Target kingdoms for merger</param>
        /// <param name="mergerReasoning">Reasoning for merger</param>
        /// <param name="proposedTerms">Proposed merger terms</param>
        /// <returns>Merger initiation result</returns>
        Task<(bool Success, string MergerProposalId, Dictionary<string, object> CompatibilityAnalysis,
               Dictionary<string, object> DemocraticRequirements)>
            InitiateKingdomMergerAsync(int kingdomId, List<int> targetKingdomIds, string mergerReasoning,
                Dictionary<string, object> proposedTerms);

        /// <summary>
        /// Processes merger approval - method expected by KingdomController
        /// </summary>
        /// <param name="mergerProposalId">Merger proposal ID</param>
        /// <param name="kingdomId">Kingdom processing approval</param>
        /// <param name="kingdomVotes">Kingdom votes</param>
        /// <param name="voterTurnout">Voter turnout data</param>
        /// <returns>Merger approval result</returns>
        Task<(bool Success, string ApprovalStatus, Dictionary<string, object> VotingResults,
               Dictionary<string, object> NextSteps)>
            ProcessMergerApprovalAsync(string mergerProposalId, int kingdomId, Dictionary<int, bool> kingdomVotes,
                Dictionary<int, double> voterTurnout);

        /// <summary>
        /// Executes kingdom merger - method expected by KingdomController (3-parameter version)
        /// </summary>
        /// <param name="mergerProposalId">Merger proposal ID</param>
        /// <param name="integrationStrategy">Integration strategy</param>
        /// <param name="leadershipIntegration">Leadership integration plan</param>
        /// <returns>Merger execution result</returns>
        Task<(bool Success, int ResultingKingdomId, Dictionary<string, object> IntegrationPlan,
               Dictionary<string, object> PreservedBenefits)>
            ExecuteKingdomMergerAsync(string mergerProposalId, Dictionary<string, object> integrationStrategy,
                Dictionary<string, object> leadershipIntegration);

        /// <summary>
        /// Analyzes kingdom compatibility for potential mergers considering population, power balance, and cultural fit
        /// </summary>
        /// <param name="kingdomId1">First kingdom for compatibility analysis</param>
        /// <param name="kingdomId2">Second kingdom for compatibility analysis</param>
        /// <returns>Compatibility analysis with merger viability assessment and recommendations</returns>
        Task<Dictionary<string, object>> AnalyzeKingdomCompatibilityAsync(int kingdomId1, int kingdomId2);

        #endregion

        #region Teleportation Management

        /// <summary>
        /// Manages kingdom-wide teleportation restrictions and policies with balanced limitations
        /// Implements proximity blocks, escalating costs, and anti-exploitation measures
        /// </summary>
        /// <param name="kingdomId">Kingdom managing teleportation</param>
        /// <param name="teleportationPolicy">Policy configuration for teleportation rules</param>
        /// <returns>Teleportation policy result with enforcement mechanisms and player impact analysis</returns>
        Task<Dictionary<string, object>> ManageTeleportationRestrictionsAsync(int kingdomId,
            Dictionary<string, object> teleportationPolicy);

        /// <summary>
        /// Processes mass teleportation events during kingdom events or emergencies
        /// Coordinates large-scale player movement while maintaining game balance
        /// </summary>
        /// <param name="kingdomId">Kingdom processing mass teleportation</param>
        /// <param name="teleportationEvent">Event triggering mass teleportation</param>
        /// <param name="participantIds">Players participating in mass teleportation</param>
        /// <param name="destinationParameters">Destination configuration and restrictions</param>
        /// <returns>Mass teleportation result with success tracking and balance enforcement</returns>
        Task<(bool Success, Dictionary<int, (int X, int Y)> PlayerDestinations, Dictionary<string, object> EventResults)>
            ProcessMassTeleportationEventAsync(int kingdomId, string teleportationEvent, List<int> participantIds,
                Dictionary<string, object> destinationParameters);

        /// <summary>
        /// Calculates optimal teleportation cost scaling to prevent exploitation while maintaining accessibility
        /// </summary>
        /// <param name="kingdomId">Kingdom to calculate costs for</param>
        /// <param name="teleportationData">Historical teleportation usage data</param>
        /// <returns>Cost scaling analysis with recommended pricing and accessibility balance</returns>
        Task<Dictionary<string, object>> CalculateTeleportationCostScalingAsync(int kingdomId,
            Dictionary<string, object> teleportationData);

        #endregion

        #region Kingdom Analytics & Intelligence

        /// <summary>
        /// Generates comprehensive kingdom statistics and performance analytics
        /// Provides insights for leadership decision-making and strategic planning
        /// </summary>
        /// <param name="kingdomId">Kingdom to analyze</param>
        /// <param name="analysisType">Type of analysis to perform</param>
        /// <param name="timeframeDays">Period to analyze</param>
        /// <returns>Comprehensive kingdom analytics with performance metrics and trend analysis</returns>
        Task<Dictionary<string, object>> GenerateKingdomAnalyticsAsync(int kingdomId, string analysisType,
            int timeframeDays = 30);

        /// <summary>
        /// Processes kingdom-wide intelligence gathering and threat assessment
        /// Monitors external threats, internal stability, and strategic opportunities
        /// </summary>
        /// <param name="kingdomId">Kingdom conducting intelligence analysis</param>
        /// <param name="intelligenceScope">Scope of intelligence gathering</param>
        /// <param name="targetKingdoms">Target kingdoms for intelligence (optional)</param>
        /// <returns>Intelligence analysis with threat assessment and strategic recommendations</returns>
        Task<Dictionary<string, object>> ProcessKingdomIntelligenceAsync(int kingdomId, string intelligenceScope,
            List<int> targetKingdoms = null);

        /// <summary>
        /// Monitors kingdom health metrics including player satisfaction, engagement, and retention
        /// Provides early warning systems for kingdom stability issues
        /// </summary>
        /// <param name="kingdomId">Kingdom to monitor health for</param>
        /// <returns>Kingdom health analysis with stability indicators and improvement recommendations</returns>
        Task<Dictionary<string, object>> MonitorKingdomHealthAsync(int kingdomId);

        /// <summary>
        /// Generates kingdom power rankings and comparative analysis against other kingdoms
        /// </summary>
        /// <param name="kingdomId">Kingdom to rank</param>
        /// <param name="comparisonKingdoms">Other kingdoms for comparative analysis</param>
        /// <param name="rankingCriteria">Criteria for ranking calculation</param>
        /// <returns>Kingdom ranking analysis with comparative metrics and positioning recommendations</returns>
        Task<Dictionary<string, object>> GenerateKingdomRankingsAsync(int kingdomId, List<int> comparisonKingdoms,
            Dictionary<string, object> rankingCriteria);

        #endregion

        #region Kingdom Events & Campaigns

        /// <summary>
        /// Manages kingdom-wide events and campaigns with participation tracking and reward distribution
        /// Coordinates events that span multiple alliances and promote kingdom unity
        /// </summary>
        /// <param name="kingdomId">Kingdom hosting event</param>
        /// <param name="eventType">Type of kingdom event</param>
        /// <param name="eventConfiguration">Event setup and rules</param>
        /// <param name="participationCriteria">Criteria for event participation</param>
        /// <returns>Kingdom event result with participation tracking and reward distribution</returns>
        Task<(bool Success, string EventId, Dictionary<string, object> ParticipationTracking,
               Dictionary<string, object> RewardDistribution)>
            ManageKingdomEventAsync(int kingdomId, string eventType, Dictionary<string, object> eventConfiguration,
                Dictionary<string, object> participationCriteria);

        /// <summary>
        /// Processes kingdom-wide campaigns that require coordinated effort across multiple alliances
        /// Manages complex objectives and promotes inter-alliance cooperation
        /// </summary>
        /// <param name="kingdomId">Kingdom conducting campaign</param>
        /// <param name="campaignType">Type of campaign to execute</param>
        /// <param name="campaignObjectives">Campaign goals and success criteria</param>
        /// <param name="allianceParticipation">Alliance participation and coordination</param>
        /// <returns>Campaign processing result with progress tracking and alliance coordination</returns>
        Task<Dictionary<string, object>> ProcessKingdomCampaignAsync(int kingdomId, string campaignType,
            Dictionary<string, object> campaignObjectives, Dictionary<int, Dictionary<string, object>> allianceParticipation);

        /// <summary>
        /// Coordinates seasonal kingdom competitions with balanced rewards and fair participation
        /// </summary>
        /// <param name="kingdomIds">Kingdoms participating in seasonal competition</param>
        /// <param name="seasonType">Type of seasonal competition</param>
        /// <param name="competitionRules">Rules and regulations for competition</param>
        /// <returns>Seasonal competition coordination with fairness validation and reward structure</returns>
        Task<Dictionary<string, object>> CoordinateSeasonalCompetitionAsync(List<int> kingdomIds, string seasonType,
            Dictionary<string, object> competitionRules);

        #endregion

        #region Diplomatic Relations

        /// <summary>
        /// Manages inter-kingdom diplomatic relations including treaties, trade agreements, and conflict resolution
        /// Facilitates peaceful resolution of conflicts and promotes strategic alliances
        /// </summary>
        /// <param name="kingdomId1">First kingdom in diplomatic relation</param>
        /// <param name="kingdomId2">Second kingdom in diplomatic relation</param>
        /// <param name="diplomaticAction">Type of diplomatic action</param>
        /// <param name="actionDetails">Details and terms of diplomatic action</param>
        /// <returns>Diplomatic action result with relation status and implementation timeline</returns>
        Task<(bool Success, string DiplomaticStatus, Dictionary<string, object> RelationDetails,
               DateTime ImplementationDeadline)>
            ManageDiplomaticRelationsAsync(int kingdomId1, int kingdomId2, string diplomaticAction,
                Dictionary<string, object> actionDetails);

        /// <summary>
        /// Processes inter-kingdom trade agreements and resource exchange programs
        /// Promotes economic cooperation and balanced resource distribution
        /// </summary>
        /// <param name="exportingKingdomId">Kingdom exporting resources</param>
        /// <param name="importingKingdomId">Kingdom importing resources</param>
        /// <param name="tradeTerms">Terms and conditions for trade agreement</param>
        /// <param name="tradeVolume">Volume and schedule of resource exchange</param>
        /// <returns>Trade agreement result with exchange tracking and economic impact</returns>
        Task<(bool Success, string TradeAgreementId, Dictionary<string, object> ExchangeSchedule,
               Dictionary<string, object> EconomicImpactAnalysis)>
            ProcessInterKingdomTradeAsync(int exportingKingdomId, int importingKingdomId,
                Dictionary<string, object> tradeTerms, Dictionary<string, long> tradeVolume);

        /// <summary>
        /// Mediates kingdom conflicts and facilitates peaceful resolution mechanisms
        /// </summary>
        /// <param name="conflictingKingdoms">Kingdoms involved in conflict</param>
        /// <param name="conflictDetails">Nature and details of the conflict</param>
        /// <param name="mediationParameters">Parameters for conflict resolution</param>
        /// <returns>Conflict mediation result with resolution plan and peace terms</returns>
        Task<Dictionary<string, object>> MediateKingdomConflictAsync(List<int> conflictingKingdoms,
            Dictionary<string, object> conflictDetails, Dictionary<string, object> mediationParameters);

        #endregion

        #region Kingdom Information & Status

        /// <summary>
        /// Retrieves comprehensive kingdom information including statistics, leadership, and current status
        /// </summary>
        /// <param name="kingdomId">Kingdom to get information for</param>
        /// <param name="includePrivateData">Whether to include sensitive internal data</param>
        /// <param name="requestingPlayerId">Player requesting information (for access control)</param>
        /// <returns>Kingdom information with appropriate data visibility</returns>
        Task<Dictionary<string, object>> GetKingdomInformationAsync(int kingdomId, bool includePrivateData = false,
            int? requestingPlayerId = null);

        /// <summary>
        /// Gets comprehensive kingdom information - method expected by KingdomController
        /// </summary>
        /// <param name="kingdomId">Kingdom to get information for</param>
        /// <returns>Kingdom information dictionary</returns>
        Task<Dictionary<string, object>> GetKingdomInfoAsync(int kingdomId);

        /// <summary>
        /// Gets current kingdom status including active events, leadership, population, and stability indicators
        /// </summary>
        /// <param name="kingdomId">Kingdom to get status for</param>
        /// <returns>Current kingdom status with all active systems and indicators</returns>
        Task<Dictionary<string, object>> GetKingdomStatusAsync(int kingdomId);

        /// <summary>
        /// Retrieves kingdom leaderboards and rankings across various categories
        /// </summary>
        /// <param name="kingdomId">Kingdom to get rankings for</param>
        /// <param name="rankingCategories">Categories to include in rankings</param>
        /// <returns>Kingdom rankings across requested categories</returns>
        Task<Dictionary<string, object>> GetKingdomRankingsAsync(int kingdomId, List<string> rankingCategories);

        /// <summary>
        /// Gets kingdom activity summary including recent events, battles, and significant changes
        /// </summary>
        /// <param name="kingdomId">Kingdom to get activity summary for</param>
        /// <param name="timeframeDays">Period to summarize activity for</param>
        /// <returns>Kingdom activity summary with timeline of significant events</returns>
        Task<Dictionary<string, object>> GetKingdomActivitySummaryAsync(int kingdomId, int timeframeDays = 7);

        #endregion
    }
}