/*
 * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\IPlayerService.cs
 * Created: 2025-10-19
 * Last Modified: 2025-10-19
 * Description: Player service interface for coordinating player-related business logic operations including castle progression, VIP management, teleportation mechanics, and cross-system player interactions
 * Last Edit Notes: Initial creation with comprehensive player management operations
 */

using ShadowedRealms.Core.Models;

namespace ShadowedRealms.Core.Interfaces.Services
{
    /// <summary>
    /// Service interface for player-related business logic operations
    /// Coordinates repository operations for castle progression, VIP management, teleportation, and player interactions
    /// </summary>
    public interface IPlayerService
    {
        #region Castle Management

        /// <summary>
        /// Upgrades player's castle to next level with resource validation and progression benefits
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="useSpeedups">Whether to apply speedup items to complete instantly</param>
        /// <returns>Upgrade result with new castle level and benefits granted</returns>
        /// <exception cref="InvalidOperationException">Thrown when upgrade requirements not met</exception>
        /// <exception cref="ArgumentException">Thrown when player not found or invalid kingdom</exception>
        Task<(bool Success, int NewCastleLevel, Dictionary<string, object> BenefitsGranted)> UpgradeCastleAsync(
            int playerId, int kingdomId, bool useSpeedups = false);

        /// <summary>
        /// Calculates castle upgrade requirements and validates player readiness
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Upgrade requirements and validation results</returns>
        Task<Dictionary<string, object>> GetCastleUpgradeRequirementsAsync(int playerId, int kingdomId);

        /// <summary>
        /// Processes castle construction queue with timing and resource management
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="buildingType">Type of building to construct</param>
        /// <param name="useSpeedups">Whether to apply speedup items</param>
        /// <returns>Construction result with completion time</returns>
        Task<(bool Success, DateTime CompletionTime, Dictionary<string, object> ResourcesConsumed)> StartConstructionAsync(
            int playerId, int kingdomId, string buildingType, bool useSpeedups = false);

        #endregion

        #region VIP Management

        /// <summary>
        /// Processes VIP tier advancement with secret tier handling and chargeback protection
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="purchaseAmount">Purchase amount contributing to VIP progress</param>
        /// <returns>VIP update result with tier changes and benefits</returns>
        Task<(bool TierChanged, int NewTier, bool IsSecretTier, Dictionary<string, object> NewBenefits, bool ChargebackRisk)>
            ProcessVipAdvancementAsync(int playerId, int kingdomId, decimal purchaseAmount);

        /// <summary>
        /// Grants VIP-specific benefits including speed bonuses and exclusive features
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="vipTier">VIP tier to apply benefits for</param>
        /// <returns>Benefits granted and their values</returns>
        Task<Dictionary<string, object>> GrantVipBenefitsAsync(int playerId, int kingdomId, int vipTier);

        /// <summary>
        /// Validates VIP privilege usage and prevents abuse
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="privilegeType">Type of VIP privilege being used</param>
        /// <returns>Validation result and privilege details</returns>
        Task<(bool CanUse, string Reason, Dictionary<string, object> PrivilegeDetails)> ValidateVipPrivilegeAsync(
            int playerId, int kingdomId, string privilegeType);

        #endregion

        #region Teleportation System

        /// <summary>
        /// Processes player teleportation with distance calculations, restrictions, and costs
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="targetX">Target X coordinate</param>
        /// <param name="targetY">Target Y coordinate</param>
        /// <param name="teleportType">Type of teleportation (free, paid, alliance)</param>
        /// <returns>Teleportation result with new coordinates and costs</returns>
        /// <exception cref="InvalidOperationException">Thrown when teleportation blocked or invalid</exception>
        Task<(bool Success, int NewX, int NewY, Dictionary<string, object> CostsApplied, DateTime NextTeleportAvailable)>
            ExecuteTeleportationAsync(int playerId, int kingdomId, int targetX, int targetY, string teleportType);

        /// <summary>
        /// Validates teleportation attempt and calculates costs/restrictions
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="targetX">Target X coordinate</param>
        /// <param name="targetY">Target Y coordinate</param>
        /// <returns>Validation result with costs and restrictions</returns>
        Task<(bool CanTeleport, string Reason, Dictionary<string, object> Costs, List<string> Restrictions)>
            ValidateTeleportationAsync(int playerId, int kingdomId, int targetX, int targetY);

        /// <summary>
        /// Checks for teleportation blocks due to proximity to other players or recent combat
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="targetX">Target X coordinate</param>
        /// <param name="targetY">Target Y coordinate</param>
        /// <returns>Block status and details</returns>
        Task<(bool IsBlocked, string BlockReason, List<(int BlockingPlayerId, string PlayerName, double Distance)> NearbyPlayers)>
            CheckTeleportationBlocksAsync(int playerId, int kingdomId, int targetX, int targetY);

        #endregion

        #region Resource Management

        /// <summary>
        /// Manages player resource collection, production bonuses, and capacity limits
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Collection result with resources gained and new totals</returns>
        Task<Dictionary<string, object>> CollectResourcesAsync(int playerId, int kingdomId);

        /// <summary>
        /// Processes resource spending with validation and anti-exploitation checks
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="resourceCosts">Resources to spend by type</param>
        /// <param name="purpose">Purpose of spending for logging</param>
        /// <returns>Spending result and new resource totals</returns>
        Task<(bool Success, Dictionary<string, long> NewResourceTotals, string ValidationMessage)>
            SpendResourcesAsync(int playerId, int kingdomId, Dictionary<string, long> resourceCosts, string purpose);

        /// <summary>
        /// Calculates resource production rates including bonuses from buildings, VIP, and alliance research
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Production rates by resource type and contributing factors</returns>
        Task<Dictionary<string, object>> CalculateResourceProductionAsync(int playerId, int kingdomId);

        #endregion

        #region Player Progression

        /// <summary>
        /// Processes player experience gains and level advancement
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="experienceGained">Experience points to add</param>
        /// <param name="source">Source of experience for tracking</param>
        /// <returns>Level advancement result and rewards</returns>
        Task<(bool LevelUp, int NewLevel, Dictionary<string, object> LevelRewards)>
            ProcessExperienceGainAsync(int playerId, int kingdomId, long experienceGained, string source);

        /// <summary>
        /// Updates player power calculation based on troops, buildings, research, and equipment
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>New power calculation and breakdown</returns>
        Task<(long NewPower, Dictionary<string, long> PowerBreakdown)> RecalculatePlayerPowerAsync(int playerId, int kingdomId);

        /// <summary>
        /// Processes player achievements and milestone rewards
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="achievementType">Type of achievement unlocked</param>
        /// <param name="progressValue">Progress value for achievement</param>
        /// <returns>Achievement unlock result and rewards</returns>
        Task<(bool NewAchievement, List<string> UnlockedAchievements, Dictionary<string, object> Rewards)>
            ProcessAchievementProgressAsync(int playerId, int kingdomId, string achievementType, long progressValue);

        #endregion

        #region Combat Integration

        /// <summary>
        /// Prepares player for combat participation with troop validation and march setup
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="troopComposition">Troops to march with</param>
        /// <param name="marchType">Type of march (attack, defend, gather)</param>
        /// <returns>March preparation result and estimated arrival time</returns>
        Task<(bool CanMarch, Dictionary<string, object> MarchDetails, DateTime EstimatedArrival, List<string> Warnings)>
            PrepareCombatMarchAsync(int playerId, int kingdomId, Dictionary<string, int> troopComposition, string marchType);

        /// <summary>
        /// Processes combat participation results and updates player statistics
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="combatResult">Results from combat engagement</param>
        /// <returns>Player updates applied from combat</returns>
        Task<Dictionary<string, object>> ProcessCombatResultsAsync(int playerId, int kingdomId, Dictionary<string, object> combatResult);

        #endregion

        #region Social Integration

        /// <summary>
        /// Processes alliance invitation or application for player
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="allianceId">Alliance to join</param>
        /// <param name="isInvitation">Whether this is an invitation or application</param>
        /// <returns>Join result and alliance integration details</returns>
        Task<(bool Success, Dictionary<string, object> AllianceDetails, List<string> NewPrivileges)>
            ProcessAllianceJoinAsync(int playerId, int kingdomId, int allianceId, bool isInvitation);

        /// <summary>
        /// Handles player leaving alliance with territory and benefit adjustments
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="reason">Reason for leaving (voluntary, kicked, disbanded)</param>
        /// <returns>Leave result and benefit adjustments</returns>
        Task<(bool Success, Dictionary<string, object> BenefitsLost, bool TerritoryEviction)>
            ProcessAllianceLeaveAsync(int playerId, int kingdomId, string reason);

        #endregion

        #region Anti-Exploitation

        /// <summary>
        /// Validates player actions for potential exploitation or cheating
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="actionType">Type of action being performed</param>
        /// <param name="actionDetails">Details of the action for validation</param>
        /// <returns>Validation result and risk assessment</returns>
        Task<(bool IsValid, List<string> Warnings, Dictionary<string, object> RiskFactors)>
            ValidatePlayerActionAsync(int playerId, int kingdomId, string actionType, Dictionary<string, object> actionDetails);

        /// <summary>
        /// Monitors player progression patterns for artificial acceleration or bot activity
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Monitoring result and any flags raised</returns>
        Task<(bool SuspiciousActivity, List<string> Flags, Dictionary<string, object> ProgressionMetrics)>
            MonitorProgressionPatternsAsync(int playerId, int kingdomId);

        #endregion

        #region Player Information

        /// <summary>
        /// Retrieves comprehensive player profile including stats, progression, and social connections
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="includePrivateData">Whether to include private data (for own profile)</param>
        /// <returns>Complete player profile data</returns>
        Task<Dictionary<string, object>> GetPlayerProfileAsync(int playerId, int kingdomId, bool includePrivateData = false);

        /// <summary>
        /// Retrieves player's current status including online state, march status, and active buffs
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Current player status information</returns>
        Task<Dictionary<string, object>> GetPlayerStatusAsync(int playerId, int kingdomId);

        /// <summary>
        /// Retrieves player leaderboard rankings across different categories
        /// </summary>
        /// <param name="playerId">Player identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Player rankings in power, level, kills, etc.</returns>
        Task<Dictionary<string, object>> GetPlayerRankingsAsync(int playerId, int kingdomId);

        #endregion
    }
}