/*
 * File: D:\shadowed-realms-mobile\ShadowedRealmsMobile\src\server\ShadowedRealms.Core\Interfaces\Services\ICombatService.cs
 * Created: 2025-10-19
 * Last Modified: 2025-10-19
 * Description: Combat service interface for coordinating field interception system, battle resolution, march mechanics, and dragon integration - implements Shadowed Realms' core innovation of defenders meeting attackers before castle sieges
 * Last Edit Notes: Initial creation with comprehensive combat system operations including field interception, anti-pay-to-win balance, and skill-based mechanics
 */

using ShadowedRealms.Core.Models;

namespace ShadowedRealms.Core.Interfaces.Services
{
    /// <summary>
    /// Service interface for combat-related business logic operations
    /// Implements field interception system (core innovation), battle resolution, march mechanics, and anti-pay-to-win combat balance
    /// </summary>
    public interface ICombatService
    {
        #region Field Interception System (Core Innovation)

        /// <summary>
        /// Calculates interception opportunities for defenders against attacking marches
        /// Core innovation: Defenders can meet attackers in the field before castle sieges
        /// </summary>
        /// <param name="attackingPlayerId">Player launching the attack</param>
        /// <param name="defendingPlayerId">Player being attacked</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="attackRoute">Route details of the attacking march</param>
        /// <returns>Interception calculations and opportunities</returns>
        Task<Dictionary<string, object>> CalculateInterceptionOpportunitiesAsync(
            int attackingPlayerId, int defendingPlayerId, int kingdomId, Dictionary<string, object> attackRoute);

        /// <summary>
        /// Executes field interception when defender chooses to meet attacker in the field
        /// </summary>
        /// <param name="defendingPlayerId">Player executing the interception</param>
        /// <param name="attackingPlayerId">Player being intercepted</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="interceptionPoint">Coordinates where interception occurs</param>
        /// <param name="defenderTroops">Troops sent by defender for interception</param>
        /// <returns>Interception execution result and combat initiation</returns>
        /// <exception cref="InvalidOperationException">Thrown when interception conditions not met</exception>
        Task<(bool Success, Dictionary<string, object> BattleSetup, DateTime BattleStartTime)>
            ExecuteFieldInterceptionAsync(int defendingPlayerId, int attackingPlayerId, int kingdomId,
                (int X, int Y) interceptionPoint, Dictionary<string, int> defenderTroops);

        /// <summary>
        /// Validates field interception attempt with timing, distance, and troop availability checks
        /// </summary>
        /// <param name="defendingPlayerId">Player attempting interception</param>
        /// <param name="attackingPlayerId">Player being intercepted</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="interceptionPoint">Proposed interception coordinates</param>
        /// <returns>Validation result with detailed requirements and restrictions</returns>
        Task<(bool CanIntercept, List<string> Requirements, Dictionary<string, object> Timing, List<string> Restrictions)>
            ValidateFieldInterceptionAsync(int defendingPlayerId, int attackingPlayerId, int kingdomId,
                (int X, int Y) interceptionPoint);

        /// <summary>
        /// Calculates optimal interception routes and timing windows for defenders
        /// </summary>
        /// <param name="defendingPlayerId">Player planning interception</param>
        /// <param name="attackRoute">Attacking march route information</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Route optimization analysis with multiple interception options</returns>
        Task<Dictionary<string, object>> CalculateOptimalInterceptionRoutesAsync(
            int defendingPlayerId, Dictionary<string, object> attackRoute, int kingdomId);

        #endregion

        #region March Mechanics

        /// <summary>
        /// Initiates combat march with speed calculations, diminishing returns, and grace periods
        /// </summary>
        /// <param name="playerId">Player launching the march</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="targetCoordinates">Target destination coordinates</param>
        /// <param name="troopComposition">Troops participating in march</param>
        /// <param name="marchType">Type of march (attack, raid, siege, defense)</param>
        /// <param name="dragonEquipped">Whether dragon accompanies the march</param>
        /// <returns>March initiation result with timing and route details</returns>
        /// <exception cref="InvalidOperationException">Thrown when march cannot be initiated</exception>
        Task<(bool Success, string MarchId, DateTime EstimatedArrival, Dictionary<string, object> MarchDetails)>
            InitiateCombatMarchAsync(int playerId, int kingdomId, (int X, int Y) targetCoordinates,
                Dictionary<string, int> troopComposition, string marchType, bool dragonEquipped = false);

        /// <summary>
        /// Calculates march speed with diminishing returns for large armies and minimum march times
        /// </summary>
        /// <param name="troopComposition">Composition of marching troops</param>
        /// <param name="distance">Distance to travel</param>
        /// <param name="playerVipTier">Player's VIP tier for speed bonuses</param>
        /// <param name="allianceResearchBonuses">Alliance research speed bonuses</param>
        /// <param name="dragonSpeedBonus">Dragon-provided speed improvements</param>
        /// <returns>Speed calculation with breakdown of contributing factors</returns>
        Task<Dictionary<string, object>> CalculateMarchSpeedAsync(
            Dictionary<string, int> troopComposition, double distance, int playerVipTier,
            Dictionary<string, double> allianceResearchBonuses, double dragonSpeedBonus = 0.0);

        /// <summary>
        /// Processes march arrival and determines combat engagement or other outcomes
        /// </summary>
        /// <param name="marchId">Unique march identifier</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Arrival processing result and next actions</returns>
        Task<Dictionary<string, object>> ProcessMarchArrivalAsync(string marchId, int kingdomId);

        /// <summary>
        /// Cancels active march with appropriate penalties and troop return timing
        /// </summary>
        /// <param name="marchId">March to cancel</param>
        /// <param name="playerId">Player cancelling march</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Cancellation result with penalties and return timing</returns>
        Task<(bool Success, Dictionary<string, object> Penalties, DateTime TroopReturnTime)>
            CancelMarchAsync(string marchId, int playerId, int kingdomId);

        #endregion

        #region Battle Resolution

        /// <summary>
        /// Executes complete battle resolution with statistical combat system
        /// Balances attack/defense/health with damage modifiers and skill-based mechanics
        /// </summary>
        /// <param name="attackerId">Attacking player ID</param>
        /// <param name="defenderId">Defending player ID</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="battleContext">Battle context including troops, location, buffs</param>
        /// <returns>Complete battle results with casualties, victor, and rewards</returns>
        Task<Dictionary<string, object>> ResolveBattleAsync(int attackerId, int defenderId, int kingdomId,
            Dictionary<string, object> battleContext);

        /// <summary>
        /// Calculates pre-battle power comparison and estimated outcomes
        /// </summary>
        /// <param name="attackerTroops">Attacking army composition</param>
        /// <param name="defenderTroops">Defending army composition</param>
        /// <param name="battleModifiers">Combat modifiers from various sources</param>
        /// <returns>Battle prediction analysis and probability outcomes</returns>
        Task<Dictionary<string, object>> CalculateBattlePredictionAsync(
            Dictionary<string, int> attackerTroops, Dictionary<string, int> defenderTroops,
            Dictionary<string, object> battleModifiers);

        /// <summary>
        /// Processes battle casualties and survivor calculations with hospital mechanics
        /// </summary>
        /// <param name="battleResult">Complete battle outcome data</param>
        /// <param name="attackerId">Attacking player ID</param>
        /// <param name="defenderId">Defending player ID</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Casualty processing with wounded/killed breakdown</returns>
        Task<Dictionary<string, object>> ProcessBattleCasualtiesAsync(
            Dictionary<string, object> battleResult, int attackerId, int defenderId, int kingdomId);

        /// <summary>
        /// Applies battle rewards including experience, resources, and achievement progress
        /// </summary>
        /// <param name="winnerId">Victorious player ID</param>
        /// <param name="loserId">Defeated player ID</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="battleResult">Complete battle outcome for reward calculations</param>
        /// <returns>Rewards distributed to participants</returns>
        Task<Dictionary<string, object>> ProcessBattleRewardsAsync(int winnerId, int loserId, int kingdomId,
            Dictionary<string, object> battleResult);

        #endregion

        #region Dragon Integration

        /// <summary>
        /// Integrates dragon skills and equipment into combat calculations
        /// Dragons must accompany armies and provide skill-based buffs rather than passive bonuses
        /// </summary>
        /// <param name="playerId">Player using dragon in combat</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="dragonSkills">Active dragon skills for this battle</param>
        /// <param name="battleContext">Current battle context</param>
        /// <returns>Dragon combat integration and skill effects</returns>
        Task<Dictionary<string, object>> IntegrateDragonCombatAsync(int playerId, int kingdomId,
            List<string> dragonSkills, Dictionary<string, object> battleContext);

        /// <summary>
        /// Validates dragon equipment and skill combinations for combat effectiveness
        /// </summary>
        /// <param name="playerId">Player's dragon setup</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="proposedSkills">Skills player wants to use</param>
        /// <returns>Validation result with optimal skill recommendations</returns>
        Task<(bool IsValid, List<string> ValidationErrors, Dictionary<string, object> OptimalSetup)>
            ValidateDragonCombatSetupAsync(int playerId, int kingdomId, List<string> proposedSkills);

        /// <summary>
        /// Calculates dragon skill cooldowns and usage restrictions
        /// </summary>
        /// <param name="playerId">Player using dragon skills</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="skillsUsed">Skills activated in recent combat</param>
        /// <returns>Cooldown timers and skill availability</returns>
        Task<Dictionary<string, object>> CalculateDragonSkillCooldownsAsync(int playerId, int kingdomId,
            List<string> skillsUsed);

        #endregion

        #region Attack Classification System

        /// <summary>
        /// Classifies attack type and applies appropriate speed/interception restrictions
        /// Lightning raids (unrestricted) to castle sieges (fully restricted)
        /// </summary>
        /// <param name="attackerId">Player launching attack</param>
        /// <param name="defenderId">Target player</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="attackParameters">Attack configuration parameters</param>
        /// <returns>Attack classification with applicable restrictions and bonuses</returns>
        Task<Dictionary<string, object>> ClassifyAttackTypeAsync(int attackerId, int defenderId, int kingdomId,
            Dictionary<string, object> attackParameters);

        /// <summary>
        /// Validates attack restrictions based on classification and recent activity
        /// </summary>
        /// <param name="attackerId">Player attempting attack</param>
        /// <param name="defenderId">Target player</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="attackType">Classified attack type</param>
        /// <returns>Attack validation with restrictions and requirements</returns>
        Task<(bool CanAttack, List<string> Restrictions, Dictionary<string, object> Requirements)>
            ValidateAttackRestrictionsAsync(int attackerId, int defenderId, int kingdomId, string attackType);

        #endregion

        #region Stealth and Route Planning

        /// <summary>
        /// Provides free route planning tools vs premium convenience options
        /// Maintains skill-based alternatives to premium features
        /// </summary>
        /// <param name="playerId">Player planning route</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="startCoordinates">Starting position</param>
        /// <param name="targetCoordinates">Destination coordinates</param>
        /// <param name="usePremiumTools">Whether to use premium route optimization</param>
        /// <returns>Route planning analysis with free and premium options</returns>
        Task<Dictionary<string, object>> CalculateRouteOptionsAsync(int playerId, int kingdomId,
            (int X, int Y) startCoordinates, (int X, int Y) targetCoordinates, bool usePremiumTools = false);

        /// <summary>
        /// Calculates stealth mechanics and detection probabilities for marching armies
        /// </summary>
        /// <param name="marchingPlayerId">Player whose march may be detected</param>
        /// <param name="observingPlayerId">Player who might detect the march</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="marchDetails">Details of the marching army</param>
        /// <returns>Stealth calculation and detection probabilities</returns>
        Task<Dictionary<string, object>> CalculateStealthMechanicsAsync(int marchingPlayerId, int observingPlayerId,
            int kingdomId, Dictionary<string, object> marchDetails);

        /// <summary>
        /// Processes intelligence gathering and scouting reports
        /// </summary>
        /// <param name="scoutingPlayerId">Player conducting reconnaissance</param>
        /// <param name="targetPlayerId">Player being scouted</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="scoutingMethod">Method used for intelligence gathering</param>
        /// <returns>Intelligence report with accuracy based on scouting method</returns>
        Task<Dictionary<string, object>> ProcessIntelligenceGatheringAsync(int scoutingPlayerId, int targetPlayerId,
            int kingdomId, string scoutingMethod);

        #endregion

        #region Anti-Pay-to-Win Combat Balance

        /// <summary>
        /// Monitors combat outcomes for pay-to-win dominance and applies skill-based balance
        /// Ensures free players can compete through strategic skill and coordination
        /// </summary>
        /// <param name="battleResult">Completed battle result</param>
        /// <param name="attackerId">Attacking player ID</param>
        /// <param name="defenderId">Defending player ID</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Balance analysis and any corrective measures needed</returns>
        Task<Dictionary<string, object>> MonitorCombatBalanceAsync(Dictionary<string, object> battleResult,
            int attackerId, int defenderId, int kingdomId);

        /// <summary>
        /// Calculates skill-based combat bonuses that provide alternatives to premium advantages
        /// </summary>
        /// <param name="playerId">Player to calculate skill bonuses for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="combatContext">Current combat situation</param>
        /// <returns>Skill-based bonuses and strategic advantages</returns>
        Task<Dictionary<string, object>> CalculateSkillBasedCombatBonusesAsync(int playerId, int kingdomId,
            Dictionary<string, object> combatContext);

        /// <summary>
        /// Validates combat effectiveness ratios to ensure balanced gameplay
        /// </summary>
        /// <param name="playerId">Player to validate effectiveness for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="timeframeDays">Analysis timeframe in days</param>
        /// <returns>Effectiveness analysis with balance recommendations</returns>
        Task<Dictionary<string, object>> ValidateCombatEffectivenessAsync(int playerId, int kingdomId,
            int timeframeDays = 30);

        #endregion

        #region Combat Statistics and Analytics

        /// <summary>
        /// Retrieves comprehensive combat history and performance analytics
        /// </summary>
        /// <param name="playerId">Player to get combat history for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="timeframeDays">Historical period to analyze</param>
        /// <returns>Combat statistics and performance metrics</returns>
        Task<Dictionary<string, object>> GetCombatHistoryAnalyticsAsync(int playerId, int kingdomId,
            int timeframeDays = 30);

        /// <summary>
        /// Calculates kingdom-wide combat trends and power balance metrics
        /// </summary>
        /// <param name="kingdomId">Kingdom to analyze</param>
        /// <param name="analysisType">Type of analysis to perform</param>
        /// <returns>Kingdom combat analytics and trend analysis</returns>
        Task<Dictionary<string, object>> AnalyzeKingdomCombatTrendsAsync(int kingdomId, string analysisType);

        /// <summary>
        /// Generates battle replay data for post-combat analysis
        /// </summary>
        /// <param name="combatLogId">Combat log to generate replay for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Battle replay data and analysis points</returns>
        Task<Dictionary<string, object>> GenerateBattleReplayAsync(int combatLogId, int kingdomId);

        #endregion

        #region Alliance Combat Coordination

        /// <summary>
        /// Coordinates alliance-wide combat operations and joint attacks
        /// </summary>
        /// <param name="coordinatingPlayerId">Player organizing alliance combat</param>
        /// <param name="allianceId">Alliance conducting joint operations</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="operationDetails">Details of the coordinated operation</param>
        /// <returns>Alliance combat coordination setup and timing</returns>
        Task<Dictionary<string, object>> CoordinateAllianceCombatAsync(int coordinatingPlayerId, int allianceId,
            int kingdomId, Dictionary<string, object> operationDetails);

        /// <summary>
        /// Processes alliance reinforcement requests and deployment
        /// </summary>
        /// <param name="requestingPlayerId">Player requesting reinforcements</param>
        /// <param name="reinforcingPlayerId">Player providing reinforcements</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="reinforcementType">Type of reinforcement needed</param>
        /// <returns>Reinforcement deployment result and timing</returns>
        Task<(bool Success, DateTime ArrivalTime, Dictionary<string, object> ReinforcementDetails)>
            ProcessAllianceReinforcementAsync(int requestingPlayerId, int reinforcingPlayerId, int kingdomId,
                string reinforcementType);

        #endregion

        #region Combat Event Management

        /// <summary>
        /// Retrieves active combat events and march status for a player
        /// </summary>
        /// <param name="playerId">Player to check combat events for</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Current combat events and active marches</returns>
        Task<Dictionary<string, object>> GetActiveCombatEventsAsync(int playerId, int kingdomId);

        /// <summary>
        /// Processes scheduled combat events and automatic resolutions
        /// </summary>
        /// <param name="eventId">Combat event to process</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <returns>Event processing result and outcomes</returns>
        Task<Dictionary<string, object>> ProcessScheduledCombatEventAsync(string eventId, int kingdomId);

        /// <summary>
        /// Cancels or modifies scheduled combat events when conditions change
        /// </summary>
        /// <param name="eventId">Combat event to modify</param>
        /// <param name="playerId">Player making the modification</param>
        /// <param name="kingdomId">Kingdom scope for security</param>
        /// <param name="modificationType">Type of modification to apply</param>
        /// <returns>Modification result and updated event details</returns>
        Task<(bool Success, Dictionary<string, object> UpdatedEvent)> ModifyCombatEventAsync(
            string eventId, int playerId, int kingdomId, string modificationType);

        #endregion
    }
}