/*
 * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/IPlayerRepository.cs
 * Created: 2025-10-19
 * Last Modified: 2025-10-19
 * Description: Player repository interface defining player-specific data access operations.
 *              Handles castle progression, troop management, resource systems, VIP mechanics,
 *              teleportation, research, equipment, and all core gameplay features for individual players.
 *              All operations are kingdom-scoped to prevent cross-kingdom data access.
 * Last Edit Notes: Initial implementation with comprehensive player mechanics, VIP system, teleportation, and gameplay features.
 */

using ShadowedRealms.Core.Models;
using ShadowedRealms.Core.Models.Player;
using System.Linq.Expressions;

namespace ShadowedRealms.Core.Interfaces.Repositories
{
    /// <summary>
    /// Repository interface for Player entity operations, providing comprehensive player lifecycle management,
    /// castle progression, troop systems, resource management, VIP mechanics, and all core gameplay features.
    /// All operations maintain kingdom-scoped security to prevent cross-kingdom data access.
    /// </summary>
    public interface IPlayerRepository : IRepository<Player, int>
    {
        #region Player Lifecycle and Authentication

        /// <summary>
        /// Creates a new player account within the specified kingdom with initial starting resources and configuration.
        /// Automatically assigns starting position, beginner protection, and tutorial progress tracking.
        /// </summary>
        /// <param name="username">The player's chosen username (must be unique within kingdom)</param>
        /// <param name="kingdomId">The kingdom where the player will be created</param>
        /// <param name="startingConfiguration">Initial player setup including position and resources</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>The newly created player with starting configuration applied</returns>
        /// <exception cref="ArgumentException">Thrown when username is invalid, taken, or kingdom is full</exception>
        /// <exception cref="InvalidOperationException">Thrown when player creation fails due to system constraints</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> CreateNewPlayerAsync(string username, int kingdomId, object startingConfiguration,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets a player by their username within the specified kingdom context.
        /// Used for login authentication and player lookup operations.
        /// </summary>
        /// <param name="username">The player's username to search for</param>
        /// <param name="kingdomId">The kingdom context for the search</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>The player if found within the kingdom, null otherwise</returns>
        /// <exception cref="ArgumentException">Thrown when username is null/empty or kingdomId is invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player?> GetPlayerByUsernameAsync(string username, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Updates the player's last login time and activity status for kingdom population management.
        /// Tracks login streaks, daily rewards eligibility, and alliance participation metrics.
        /// </summary>
        /// <param name="playerId">The player to update</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="loginMetrics">Additional login tracking data (IP, device, etc.)</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new activity status</returns>
        /// <exception cref="ArgumentException">Thrown when playerId or kingdomId is invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdatePlayerActivityAsync(int playerId, int kingdomId, object? loginMetrics = null,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players who have been inactive beyond the specified threshold for kingdom health monitoring.
        /// Used for identifying accounts at risk of abandonment and triggering retention campaigns.
        /// </summary>
        /// <param name="kingdomId">The kingdom to check for inactive players</param>
        /// <param name="inactiveThreshold">How long without login constitutes inactive</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Inactive players within the kingdom</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetInactivePlayersAsync(int kingdomId, TimeSpan inactiveThreshold,
            CancellationToken cancellationToken = default);

        #endregion

        #region Castle and Progression Management

        /// <summary>
        /// Upgrades a player's castle level, automatically updating capacity limits, unlocking features,
        /// and applying resource costs. Validates upgrade requirements and prerequisite building levels.
        /// </summary>
        /// <param name="playerId">The player upgrading their castle</param>
        /// <param name="targetLevel">The target castle level (Launch cap: Level 30)</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new castle level and unlocked features</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or upgrade is not allowed</exception>
        /// <exception cref="InvalidOperationException">Thrown when player lacks resources or prerequisites</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpgradeCastleLevelAsync(int playerId, int targetLevel, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players within a specific castle level range for matchmaking, event organization,
        /// and progression analytics. Supports alliance recruitment and KvK balancing.
        /// </summary>
        /// <param name="minLevel">Minimum castle level (inclusive)</param>
        /// <param name="maxLevel">Maximum castle level (inclusive)</param>
        /// <param name="kingdomId">The kingdom context for the search</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players within the specified level range</returns>
        /// <exception cref="ArgumentException">Thrown when level parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersByLevelRangeAsync(int minLevel, int maxLevel, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets the top players by castle level within the kingdom for leaderboards and recognition systems.
        /// Includes progression speed metrics and recent advancement tracking.
        /// </summary>
        /// <param name="kingdomId">The kingdom to get top players from</param>
        /// <param name="topCount">Number of top players to return</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Top players ranked by castle level and progression metrics</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetTopPlayersByCastleLevelAsync(int kingdomId, int topCount = 100,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Updates building levels for a player's castle complex, validating prerequisites and resource costs.
        /// Handles hospital, barracks, research facilities, and defensive structures.
        /// </summary>
        /// <param name="playerId">The player upgrading buildings</param>
        /// <param name="buildingUpgrades">Dictionary of building types and target levels</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new building levels</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or upgrades violate rules</exception>
        /// <exception cref="InvalidOperationException">Thrown when player lacks resources for upgrades</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateBuildingLevelsAsync(int playerId, Dictionary<string, int> buildingUpgrades, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Troop and Military Management

        /// <summary>
        /// Updates a player's troop counts for specific tier and type, validating capacity limits
        /// and training requirements. Handles T1-T13 troops with tier-specific restrictions.
        /// </summary>
        /// <param name="playerId">The player whose troops are being updated</param>
        /// <param name="troopUpdates">Dictionary of troop types and count changes</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new troop counts</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or exceed capacity limits</exception>
        /// <exception cref="InvalidOperationException">Thrown when troop updates violate game rules</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateTroopCountsAsync(int playerId, Dictionary<string, int> troopUpdates, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players by military strength for alliance recruitment, KvK balancing, and threat assessment.
        /// Calculates total military power including troops, dragons, and equipment bonuses.
        /// </summary>
        /// <param name="kingdomId">The kingdom to search within</param>
        /// <param name="minimumPower">Minimum military power threshold</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players meeting the minimum military power requirement</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersByMilitaryStrengthAsync(int kingdomId, long minimumPower = 0,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Records troop losses from combat, hospital capacity management, and death mechanics.
        /// Handles wounded vs killed troops, hospital overflow, and resurrection systems.
        /// </summary>
        /// <param name="playerId">The player who suffered losses</param>
        /// <param name="troopLosses">Detailed breakdown of troop casualties</param>
        /// <param name="combatContext">Combat information for loss calculations</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with recorded losses and hospital status</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when loss recording fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> RecordTroopLossesAsync(int playerId, object troopLosses, object combatContext, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Heals wounded troops in the hospital, consuming resources and time based on troop tier and count.
        /// Supports instant healing with premium currency or time-based free healing.
        /// </summary>
        /// <param name="playerId">The player healing troops</param>
        /// <param name="healingConfiguration">Healing method, troops to heal, and resource costs</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with healed troops and consumed resources</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or player lacks resources</exception>
        /// <exception cref="InvalidOperationException">Thrown when healing fails due to game rules</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> HealWoundedTroopsAsync(int playerId, object healingConfiguration, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Resource Management

        /// <summary>
        /// Updates a player's resource counts (food, wood, stone, iron, gold) validating capacity limits
        /// and storage building requirements. Handles resource production, consumption, and transfers.
        /// </summary>
        /// <param name="playerId">The player whose resources are being updated</param>
        /// <param name="resourceChanges">Dictionary of resource types and amount changes (positive or negative)</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="transactionReason">Reason for the resource change (for logging)</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new resource amounts</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or exceed storage limits</exception>
        /// <exception cref="InvalidOperationException">Thrown when player lacks sufficient resources for deduction</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateResourcesAsync(int playerId, Dictionary<string, long> resourceChanges, int kingdomId,
            string transactionReason, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players with resource amounts within specified ranges for trading, alliance support,
        /// and economic analysis. Supports finding players who can provide or need specific resources.
        /// </summary>
        /// <param name="kingdomId">The kingdom to search within</param>
        /// <param name="resourceCriteria">Resource type and amount range criteria</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players matching the resource criteria</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersByResourceCriteriaAsync(int kingdomId, Dictionary<string, (long Min, long Max)> resourceCriteria,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Processes resource production for a player based on building levels, research bonuses, and time elapsed.
        /// Calculates production rates, applies bonuses, and updates storage with capacity limits.
        /// </summary>
        /// <param name="playerId">The player generating resources</param>
        /// <param name="productionDuration">Time period for resource generation</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with produced resources</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when production calculation fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> ProcessResourceProductionAsync(int playerId, TimeSpan productionDuration, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region VIP System and Monetization

        /// <summary>
        /// Processes a VIP points purchase for a player, updating VIP level and unlocking benefits.
        /// Handles VIP level progression, milestone rewards, and secret tier system integration.
        /// </summary>
        /// <param name="playerId">The player making the VIP purchase</param>
        /// <param name="vipPointsPurchased">Number of VIP points purchased</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="purchaseDetails">Transaction details for purchase logging</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new VIP status and rewards</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when VIP processing fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> ProcessVipPurchaseAsync(int playerId, int vipPointsPurchased, int kingdomId, object purchaseDetails,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players by VIP level range for targeted offers, premium events, and customer service prioritization.
        /// Supports VIP-specific matchmaking and exclusive content access management.
        /// </summary>
        /// <param name="kingdomId">The kingdom to search within</param>
        /// <param name="minVipLevel">Minimum VIP level (inclusive)</param>
        /// <param name="maxVipLevel">Maximum VIP level (inclusive)</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players within the specified VIP level range</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersByVipLevelAsync(int kingdomId, int minVipLevel = 0, int maxVipLevel = int.MaxValue,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Claims daily VIP rewards for a player based on their VIP level and login streak.
        /// Prevents duplicate claims and calculates reward amounts based on VIP benefits.
        /// </summary>
        /// <param name="playerId">The player claiming rewards</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with claimed rewards and updated claim status</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when rewards already claimed or player ineligible</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> ClaimVipDailyRewardsAsync(int playerId, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets VIP spending analytics for a player including lifetime value, purchase patterns, and chargeback risk.
        /// Used for customer service, offer personalization, and financial risk management.
        /// </summary>
        /// <param name="playerId">The player to analyze</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Comprehensive VIP spending analytics</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetPlayerVipAnalyticsAsync(int playerId, int kingdomId, CancellationToken cancellationToken = default);

        #endregion

        #region Teleportation and Movement

        /// <summary>
        /// Attempts to teleport a player to new coordinates, validating movement rules, proximity restrictions,
        /// and teleportation costs. Handles free teleports, premium teleports, and alliance territory rules.
        /// </summary>
        /// <param name="playerId">The player requesting teleportation</param>
        /// <param name="targetCoordinates">The desired destination coordinates</param>
        /// <param name="teleportationType">Free, premium, or alliance-assisted teleport</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new coordinates if successful</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or teleport violates rules</exception>
        /// <exception cref="InvalidOperationException">Thrown when player lacks resources or teleport is blocked</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> TeleportPlayerAsync(int playerId, (int X, int Y) targetCoordinates, string teleportationType,
            int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players within a specific coordinate radius for local events, alliance recruitment,
        /// and proximity-based interactions. Supports both circular and square search areas.
        /// </summary>
        /// <param name="centerCoordinates">The center point for the search</param>
        /// <param name="radius">The search radius in coordinate units</param>
        /// <param name="kingdomId">The kingdom context for the search</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players within the specified radius</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersInRadiusAsync((int X, int Y) centerCoordinates, int radius, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Updates a player's movement speed modifiers based on research, equipment, and temporary effects.
        /// Affects march times, teleportation cooldowns, and return speeds.
        /// </summary>
        /// <param name="playerId">The player to update</param>
        /// <param name="speedModifiers">Dictionary of speed modifier sources and values</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new speed calculations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when speed update fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateMovementSpeedAsync(int playerId, Dictionary<string, float> speedModifiers, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Validates if a teleportation is allowed based on game rules, proximity restrictions, and cooldowns.
        /// Checks alliance territory rules, enemy proximity blocks, and teleportation history.
        /// </summary>
        /// <param name="playerId">The player requesting validation</param>
        /// <param name="targetCoordinates">The desired destination</param>
        /// <param name="teleportationType">The type of teleport being attempted</param>
        /// <param name="kingdomId">The kingdom context for validation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Validation result with reasons for any restrictions</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(bool IsAllowed, string[] Restrictions, TimeSpan? Cooldown)> ValidateTeleportationAsync(int playerId,
            (int X, int Y) targetCoordinates, string teleportationType, int kingdomId, CancellationToken cancellationToken = default);

        #endregion

        #region Research and Technology

        /// <summary>
        /// Updates a player's research progress in specific technology trees, validating prerequisites
        /// and resource costs. Handles Military, Economic, and Technology research branches.
        /// </summary>
        /// <param name="playerId">The player conducting research</param>
        /// <param name="researchUpdates">Dictionary of research areas and level increases</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new research levels and unlocked bonuses</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or research violates prerequisites</exception>
        /// <exception cref="InvalidOperationException">Thrown when player lacks resources for research</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateResearchProgressAsync(int playerId, Dictionary<string, int> researchUpdates, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players by research specialization for alliance coordination and strategic planning.
        /// Identifies players with advanced military, economic, or technology research for specific roles.
        /// </summary>
        /// <param name="kingdomId">The kingdom to search within</param>
        /// <param name="researchCriteria">Minimum research levels in specific areas</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players meeting the research criteria</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersByResearchSpecializationAsync(int kingdomId, Dictionary<string, int> researchCriteria,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Calculates total research bonuses for a player including base research, alliance research,
        /// equipment bonuses, and temporary effects. Used for combat calculations and resource production.
        /// </summary>
        /// <param name="playerId">The player to calculate bonuses for</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Comprehensive breakdown of all research bonuses</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> CalculateResearchBonusesAsync(int playerId, int kingdomId, CancellationToken cancellationToken = default);

        #endregion

        #region Equipment and Dragon System

        /// <summary>
        /// Updates a player's equipment loadout, validating equipment compatibility and enhancement levels.
        /// Handles weapon, armor, and accessory systems with stat bonuses and set effects.
        /// </summary>
        /// <param name="playerId">The player updating equipment</param>
        /// <param name="equipmentChanges">Dictionary of equipment slots and new items</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new equipment and calculated stat bonuses</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or equipment incompatible</exception>
        /// <exception cref="InvalidOperationException">Thrown when player lacks required items</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateEquipmentAsync(int playerId, Dictionary<string, object> equipmentChanges, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Updates a player's dragon configuration including skill selection, equipment, and evolution progress.
        /// Dragons must accompany armies and provide skill-based buffs rather than pay-to-win advantages.
        /// </summary>
        /// <param name="playerId">The player updating their dragon</param>
        /// <param name="dragonConfiguration">Dragon skills, equipment, and evolution settings</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new dragon configuration</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or dragon config is incompatible</exception>
        /// <exception cref="InvalidOperationException">Thrown when player lacks required dragon resources</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateDragonConfigurationAsync(int playerId, object dragonConfiguration, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players by equipment power level for matchmaking, alliance organization, and competitive events.
        /// Calculates total equipment score including enhancement levels and set bonuses.
        /// </summary>
        /// <param name="kingdomId">The kingdom to search within</param>
        /// <param name="minimumEquipmentPower">Minimum equipment power threshold</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players meeting the equipment power requirement</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersByEquipmentPowerAsync(int kingdomId, long minimumEquipmentPower = 0,
            CancellationToken cancellationToken = default);

        #endregion

        #region Alliance Integration

        /// <summary>
        /// Gets all players belonging to a specific alliance within the kingdom for alliance management operations.
        /// Includes member roles, contribution metrics, and activity status.
        /// </summary>
        /// <param name="allianceId">The alliance to get members for</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>All players who are members of the specified alliance</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetAllianceMembersAsync(int allianceId, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets players without an alliance within the kingdom for recruitment and alliance invitation systems.
        /// Filters by activity level, castle level, and availability for alliance participation.
        /// </summary>
        /// <param name="kingdomId">The kingdom to search within</param>
        /// <param name="minimumCastleLevel">Minimum castle level for alliance eligibility</param>
        /// <param name="activeOnly">Whether to only include recently active players</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Players available for alliance recruitment</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<Player>> GetPlayersWithoutAllianceAsync(int kingdomId, int minimumCastleLevel = 1,
            bool activeOnly = true, CancellationToken cancellationToken = default);

        /// <summary>
        /// Updates a player's alliance membership, handling alliance changes, role assignments, and contribution tracking.
        /// Manages leaving previous alliance, cooldown periods, and integration into new alliance systems.
        /// </summary>
        /// <param name="playerId">The player changing alliance status</param>
        /// <param name="newAllianceId">The new alliance ID (null for leaving alliance)</param>
        /// <param name="membershipRole">The role within the new alliance</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated player with new alliance status</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or alliance change violates rules</exception>
        /// <exception cref="InvalidOperationException">Thrown when alliance change fails due to cooldowns or restrictions</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<Player> UpdateAllianceMembershipAsync(int playerId, int? newAllianceId, string? membershipRole, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Player Analytics and Performance

        /// <summary>
        /// Gets comprehensive player performance analytics including combat effectiveness, economic efficiency,
        /// social engagement, and progression metrics for administrative analysis and player development.
        /// </summary>
        /// <param name="playerId">The player to analyze</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="timeRange">The time period to analyze</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Detailed player analytics and performance metrics</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetPlayerAnalyticsAsync(int playerId, int kingdomId, TimeSpan timeRange,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets player leaderboard rankings for various metrics including power, castle level, alliance contribution,
        /// and KvK performance. Supports multiple ranking categories and time periods.
        /// </summary>
        /// <param name="kingdomId">The kingdom to generate rankings for</param>
        /// <param name="rankingCategory">The metric to rank by (power, level, contribution, etc.)</param>
        /// <param name="topCount">Number of top players to return</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Top players ranked by the specified metric</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<(Player Player, object RankingValue, int Rank)>> GetPlayerLeaderboardAsync(int kingdomId,
            string rankingCategory, int topCount = 100, CancellationToken cancellationToken = default);

        /// <summary>
        /// Generates a player development report identifying strengths, weaknesses, and recommended improvement areas.
        /// Provides personalized guidance for progression optimization and skill development.
        /// </summary>
        /// <param name="playerId">The player to generate report for</param>
        /// <param name="kingdomId">The kingdom context for the operation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Comprehensive development report with recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GeneratePlayerDevelopmentReportAsync(int playerId, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion
    }
}