/*
 * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/ICombatLogRepository.cs
 * Created: 2025-10-19
 * Last Modified: 2025-10-19
 * Description: Combat log repository interface defining combat-specific data access operations.
 *              Handles field interception combat, battle resolution, KvK events, stealth mechanics,
 *              dragon integration, speed limitations, and attack classifications. Core innovation
 *              is the field interception system where defenders can meet attackers before they reach castles.
 * Last Edit Notes: Initial implementation with field interception, battle resolution, KvK mechanics, and combat analytics.
 */

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

namespace ShadowedRealms.Core.Interfaces.Repositories
{
    /// <summary>
    /// Repository interface for CombatLog entity operations, providing comprehensive combat system management,
    /// field interception mechanics, battle resolution, KvK event tracking, and combat analytics.
    /// Core innovation: Field interception system allows defenders to meet attackers before castle sieges.
    /// </summary>
    public interface ICombatLogRepository : IRepository<CombatLog, int>
    {
        #region Field Interception System (Core Innovation)

        /// <summary>
        /// Creates a field interception combat engagement where defenders meet attackers before they reach the target castle.
        /// CORE INNOVATION: Allows strategic defensive positioning and prevents inevitable castle sieges.
        /// </summary>
        /// <param name="attackingPlayerId">The player initiating the attack</param>
        /// <param name="defendingPlayerId">The player defending (can intercept in the field)</param>
        /// <param name="interceptionCoordinates">Where the field battle takes place</param>
        /// <param name="attackingForce">Attacking army composition and equipment</param>
        /// <param name="defendingForce">Defending army composition and equipment</param>
        /// <param name="kingdomId">The kingdom context for the combat</param>
        /// <param name="combatConfiguration">Battle parameters, terrain effects, and special conditions</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Created combat log with field interception battle results</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or interception is not allowed</exception>
        /// <exception cref="InvalidOperationException">Thrown when field interception cannot be initiated</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<CombatLog> CreateFieldInterceptionCombatAsync(int attackingPlayerId, int defendingPlayerId,
            (int X, int Y) interceptionCoordinates, object attackingForce, object defendingForce, int kingdomId,
            object combatConfiguration, CancellationToken cancellationToken = default);

        /// <summary>
        /// Validates if field interception is possible based on army positions, movement speeds, timing windows,
        /// and strategic positioning. Calculates interception probability and optimal positioning.
        /// </summary>
        /// <param name="attackingPlayerId">The attacking player</param>
        /// <param name="defendingPlayerId">The potential intercepting player</param>
        /// <param name="targetCoordinates">The original target of the attack</param>
        /// <param name="kingdomId">The kingdom context for validation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Interception feasibility analysis with optimal positioning recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(bool CanIntercept, double InterceptionProbability, (int X, int Y)[] OptimalPositions, TimeSpan TimeWindow)>
            ValidateFieldInterceptionAsync(int attackingPlayerId, int defendingPlayerId, (int X, int Y) targetCoordinates,
            int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets active field interception opportunities for alliance members and kingdom defenders.
        /// Identifies incoming attacks that can be intercepted and calculates strategic value.
        /// </summary>
        /// <param name="defendingPlayerId">The player looking for interception opportunities</param>
        /// <param name="searchRadius">Radius around player to search for interception opportunities</param>
        /// <param name="kingdomId">The kingdom context for the search</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Available interception opportunities with strategic analysis</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<(object AttackDetails, double StrategicValue, TimeSpan TimeToIntercept)>>
            GetFieldInterceptionOpportunitiesAsync(int defendingPlayerId, int searchRadius, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Processes field interception battle resolution using statistical combat system with attack/defense/health
        /// calculations, damage modifiers, dragon bonuses, and equipment effects.
        /// </summary>
        /// <param name="combatLogId">The combat engagement to resolve</param>
        /// <param name="battleParameters">Combat calculations, random factors, and environmental effects</param>
        /// <param name="kingdomId">The kingdom context for the battle</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated combat log with battle resolution and casualty reports</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat already resolved</exception>
        /// <exception cref="InvalidOperationException">Thrown when battle resolution fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<CombatLog> ResolveFieldInterceptionBattleAsync(int combatLogId, object battleParameters, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Attack Classification System

        /// <summary>
        /// Classifies attack types based on army composition, target selection, and strategic intent.
        /// Ranges from Lightning Raids (unrestricted) to Castle Sieges (fully restricted by field interception).
        /// </summary>
        /// <param name="attackingPlayerId">The attacking player</param>
        /// <param name="targetCoordinates">The target location</param>
        /// <param name="armyComposition">Army size, composition, and equipment</param>
        /// <param name="kingdomId">The kingdom context for classification</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Attack classification with interception rules and restrictions</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(string AttackType, string[] InterceptionRules, double VulnerabilityFactor)> ClassifyAttackTypeAsync(
            int attackingPlayerId, (int X, int Y) targetCoordinates, object armyComposition, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets combat logs filtered by attack classification for strategic analysis and defensive planning.
        /// Helps identify attack patterns and defensive effectiveness by attack type.
        /// </summary>
        /// <param name="attackType">The attack classification to filter by</param>
        /// <param name="kingdomId">The kingdom context for the search</param>
        /// <param name="timeRange">Time period to analyze</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Combat logs matching the attack classification</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<CombatLog>> GetCombatLogsByAttackTypeAsync(string attackType, int kingdomId, TimeSpan timeRange,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Analyzes attack effectiveness by classification, identifying successful strategies and defensive gaps.
        /// Provides insights for both offensive planning and defensive improvements.
        /// </summary>
        /// <param name="kingdomId">The kingdom to analyze</param>
        /// <param name="analysisTimeframe">Time period for analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Attack effectiveness analysis by classification with strategic recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> AnalyzeAttackEffectivenessByTypeAsync(int kingdomId, TimeSpan analysisTimeframe,
            CancellationToken cancellationToken = default);

        #endregion

        #region Speed Limitations and March Mechanics

        /// <summary>
        /// Calculates march times between coordinates considering minimum march times, diminishing returns on speed,
        /// terrain effects, alliance territory bonuses, and temporary speed modifications.
        /// </summary>
        /// <param name="startCoordinates">Starting position</param>
        /// <param name="endCoordinates">Destination position</param>
        /// <param name="armyComposition">Army affecting march speed</param>
        /// <param name="playerId">Player for speed bonuses calculation</param>
        /// <param name="kingdomId">The kingdom context for calculations</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>March time calculations with speed factors and arrival prediction</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(TimeSpan MarchTime, TimeSpan MinimumTime, double SpeedModifier, DateTime EstimatedArrival)>
            CalculateMarchTimeAsync((int X, int Y) startCoordinates, (int X, int Y) endCoordinates,
            object armyComposition, int playerId, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Validates march legality based on speed limitations, grace periods, cooldown restrictions,
        /// and movement rule violations. Prevents exploitation of speed mechanics.
        /// </summary>
        /// <param name="playerId">The player attempting the march</param>
        /// <param name="marchConfiguration">March details including target, army, and timing</param>
        /// <param name="kingdomId">The kingdom context for validation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>March validation result with restriction details and cooldown information</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? RequiredWait)> ValidateMarchLegalityAsync(
            int playerId, object marchConfiguration, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Records march history for speed limitation enforcement and pattern analysis.
        /// Tracks march frequency, destinations, and timing to prevent exploitation.
        /// </summary>
        /// <param name="playerId">The player making the march</param>
        /// <param name="marchDetails">Complete march information</param>
        /// <param name="kingdomId">The kingdom context for recording</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated march history with timing validation</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="InvalidOperationException">Thrown when march recording fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> RecordMarchHistoryAsync(int playerId, object marchDetails, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets march analytics for players including frequency patterns, preferred targets,
        /// timing strategies, and effectiveness metrics for behavioral analysis.
        /// </summary>
        /// <param name="playerId">The player to analyze</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="analysisTimeframe">Time period for march analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Comprehensive march behavior analysis</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetPlayerMarchAnalyticsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
            CancellationToken cancellationToken = default);

        #endregion

        #region Stealth and Route Planning

        /// <summary>
        /// Creates stealth march plans with hidden routes and timing to avoid detection and interception.
        /// Balances free strategic planning with premium convenience options for route optimization.
        /// </summary>
        /// <param name="playerId">The player planning the stealth march</param>
        /// <param name="targetCoordinates">The intended target</param>
        /// <param name="stealthConfiguration">Stealth parameters and route preferences</param>
        /// <param name="kingdomId">The kingdom context for planning</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Stealth march plan with route options and detection probability</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or stealth not available</exception>
        /// <exception cref="InvalidOperationException">Thrown when stealth planning fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> CreateStealthMarchPlanAsync(int playerId, (int X, int Y) targetCoordinates,
            object stealthConfiguration, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Detects stealth marches based on intelligence networks, scout reports, and detection systems.
        /// Provides early warning for defended territories and alliance coordination.
        /// </summary>
        /// <param name="defendingPlayerId">The player with detection capabilities</param>
        /// <param name="detectionRadius">Area to scan for stealth marches</param>
        /// <param name="kingdomId">The kingdom context for detection</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Detected stealth marches with confidence levels and estimated targets</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<IEnumerable<(object MarchDetails, double DetectionConfidence, (int X, int Y) EstimatedTarget)>>
            DetectStealthMarchesAsync(int defendingPlayerId, int detectionRadius, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Validates route planning options based on player access level (free vs premium features).
        /// Ensures skill-based alternatives exist while providing convenience options for premium users.
        /// </summary>
        /// <param name="playerId">The player planning routes</param>
        /// <param name="routePreferences">Desired route characteristics</param>
        /// <param name="kingdomId">The kingdom context for validation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Available route planning options with feature access levels</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(object[] FreeOptions, object[] PremiumOptions, string[] SkillBasedAlternatives)>
            ValidateRoutePlanningAccessAsync(int playerId, object routePreferences, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Dragon Integration and Combat Bonuses

        /// <summary>
        /// Applies dragon bonuses to combat calculations including skill-based buffs, equipment effects,
        /// and evolution bonuses. Dragons must accompany armies and provide strategic advantages.
        /// </summary>
        /// <param name="combatLogId">The combat engagement to apply dragon bonuses to</param>
        /// <param name="attackingDragonConfiguration">Attacking player's dragon setup</param>
        /// <param name="defendingDragonConfiguration">Defending player's dragon setup</param>
        /// <param name="kingdomId">The kingdom context for the combat</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated combat log with dragon bonus calculations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or dragons not present</exception>
        /// <exception cref="InvalidOperationException">Thrown when dragon bonus application fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<CombatLog> ApplyDragonBonusesToCombatAsync(int combatLogId, object attackingDragonConfiguration,
            object defendingDragonConfiguration, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Validates dragon participation in combat based on army composition, dragon stamina,
        /// skill compatibility, and equipment requirements for combat engagement.
        /// </summary>
        /// <param name="playerId">The player with the dragon</param>
        /// <param name="dragonConfiguration">Dragon skills, equipment, and status</param>
        /// <param name="armyComposition">Army the dragon will accompany</param>
        /// <param name="kingdomId">The kingdom context for validation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Dragon participation validation with skill effectiveness prediction</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<(bool CanParticipate, double EffectivenessModifier, string[] SkillBonuses, string[] Restrictions)>
            ValidateDragonParticipationAsync(int playerId, object dragonConfiguration, object armyComposition,
            int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets dragon combat performance analytics including skill effectiveness, equipment impact,
        /// evolution benefits, and strategic value in different combat scenarios.
        /// </summary>
        /// <param name="playerId">The player to analyze dragon performance for</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="analysisTimeframe">Time period for dragon performance analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Dragon performance analytics with optimization recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetDragonCombatAnalyticsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
            CancellationToken cancellationToken = default);

        #endregion

        #region KvK Combat Events

        /// <summary>
        /// Creates large-scale KvK combat events involving multiple kingdoms, alliances, and coalition forces.
        /// Handles complex battle scenarios with kingdom vs kingdom mechanics and territory control.
        /// </summary>
        /// <param name="participatingKingdoms">Kingdoms involved in the KvK combat</param>
        /// <param name="eventType">Type of KvK event (3-kingdom war, alliance conquest, etc.)</param>
        /// <param name="battlefieldConfiguration">Terrain, objectives, and victory conditions</param>
        /// <param name="coalitionArrangements">Alliance coalitions and their battle formations</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Created KvK combat event with initial battle state</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or kingdoms ineligible</exception>
        /// <exception cref="InvalidOperationException">Thrown when KvK event creation fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<CombatLog> CreateKvKCombatEventAsync(IEnumerable<int> participatingKingdoms, string eventType,
            object battlefieldConfiguration, object coalitionArrangements, CancellationToken cancellationToken = default);

        /// <summary>
        /// Tracks KvK battle progression including territory control changes, casualty reports,
        /// strategic objective completion, and coalition performance metrics.
        /// </summary>
        /// <param name="kvkCombatId">The KvK combat event to track</param>
        /// <param name="battleUpdates">Current battle state and changes</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Updated KvK combat log with battle progression</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat not found</exception>
        /// <exception cref="InvalidOperationException">Thrown when battle tracking fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<CombatLog> TrackKvKBattleProgressionAsync(int kvkCombatId, object battleUpdates,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Resolves KvK combat events with multiple victory paths including military dominance,
        /// economic control, diplomatic success, and technological advancement.
        /// </summary>
        /// <param name="kvkCombatId">The KvK combat event to resolve</param>
        /// <param name="victoryConditions">Conditions met for victory determination</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Resolved KvK combat log with victory outcomes and rewards distribution</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat already resolved</exception>
        /// <exception cref="InvalidOperationException">Thrown when KvK resolution fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<CombatLog> ResolveKvKCombatEventAsync(int kvkCombatId, object victoryConditions,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets KvK combat history for kingdoms including participation records, performance metrics,
        /// victory/defeat ratios, and strategic lessons learned for future matchmaking.
        /// </summary>
        /// <param name="kingdomId">The kingdom to get KvK history for</param>
        /// <param name="historyTimeframe">Time period for historical analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>KvK combat history with performance trends and strategic insights</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetKvKCombatHistoryAsync(int kingdomId, TimeSpan historyTimeframe,
            CancellationToken cancellationToken = default);

        #endregion

        #region Forest Barrier and Banishment Mechanics

        /// <summary>
        /// Applies forest barrier speed penalties (50% reduction) for players crossing into contested forest zones
        /// during KvK events. Handles terrain-based movement restrictions and strategic positioning.
        /// </summary>
        /// <param name="playerId">The player entering forest barriers</param>
        /// <param name="forestCoordinates">The forest zone coordinates</param>
        /// <param name="crossingConfiguration">Crossing attempt details and timing</param>
        /// <param name="kingdomId">The kingdom context for the crossing</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Forest crossing result with speed penalties and strategic implications</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or crossing not allowed</exception>
        /// <exception cref="InvalidOperationException">Thrown when forest crossing fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> ApplyForestBarrierPenaltyAsync(int playerId, (int X, int Y) forestCoordinates,
            object crossingConfiguration, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Processes castle banishment for players who lose battles in contested forest zones.
        /// Handles forced teleportation, temporary restrictions, and recovery mechanics.
        /// </summary>
        /// <param name="banishedPlayerId">The player being banished from their castle</param>
        /// <param name="banishmentTrigger">Combat result or event causing banishment</param>
        /// <param name="banishmentDuration">How long the banishment lasts</param>
        /// <param name="kingdomId">The kingdom context for banishment</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Banishment result with recovery options and timeline</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or banishment not justified</exception>
        /// <exception cref="InvalidOperationException">Thrown when banishment processing fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> ProcessCastleBanishmentAsync(int banishedPlayerId, object banishmentTrigger,
            TimeSpan banishmentDuration, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets forest zone control status including alliance territorial claims, contested areas,
        /// and strategic resource locations that trigger barrier mechanics during conflicts.
        /// </summary>
        /// <param name="forestZoneId">The forest zone to analyze</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Forest zone control analysis with territorial disputes and strategic value</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetForestZoneControlStatusAsync(int forestZoneId, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Combat Analytics and Intelligence

        /// <summary>
        /// Gets comprehensive combat analytics for players including win/loss ratios, effectiveness by attack type,
        /// field interception success rates, and strategic pattern analysis for performance improvement.
        /// </summary>
        /// <param name="playerId">The player to analyze</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="analysisTimeframe">Time period for combat analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Detailed combat performance analytics with improvement recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetPlayerCombatAnalyticsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Generates combat intelligence reports for alliances including threat assessment, enemy patterns,
        /// strategic vulnerabilities, and recommended defensive posturing for alliance coordination.
        /// </summary>
        /// <param name="allianceId">The alliance requesting intelligence</param>
        /// <param name="kingdomId">The kingdom context for intelligence</param>
        /// <param name="intelligenceScope">Local threats, kingdom-wide, or KvK intelligence</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Combat intelligence report with threat analysis and strategic recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GenerateAllianceCombatIntelligenceAsync(int allianceId, int kingdomId, string intelligenceScope,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Gets kingdom combat statistics including overall military activity, power distribution,
        /// alliance conflicts, and readiness for KvK events for administrative and strategic planning.
        /// </summary>
        /// <param name="kingdomId">The kingdom to analyze</param>
        /// <param name="statisticsTimeframe">Time period for statistical analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Kingdom combat statistics with military readiness assessment</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> GetKingdomCombatStatisticsAsync(int kingdomId, TimeSpan statisticsTimeframe,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Analyzes combat effectiveness of different troop compositions, equipment combinations,
        /// and strategic approaches to provide data-driven optimization recommendations.
        /// </summary>
        /// <param name="combatParameters">Combat scenarios and variables to analyze</param>
        /// <param name="kingdomId">The kingdom context for analysis</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Combat effectiveness analysis with optimization recommendations</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> AnalyzeCombatEffectivenessAsync(object combatParameters, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion

        #region Battle Resolution and Statistical Combat

        /// <summary>
        /// Processes statistical combat resolution using attack/defense/health calculations with damage modifiers,
        /// critical hits, armor penetration, and tactical bonuses for realistic battle outcomes.
        /// </summary>
        /// <param name="combatLogId">The combat engagement to resolve</param>
        /// <param name="combatParameters">All factors affecting battle outcome</param>
        /// <param name="kingdomId">The kingdom context for resolution</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Resolved combat log with detailed battle results and casualty breakdown</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat already resolved</exception>
        /// <exception cref="InvalidOperationException">Thrown when battle resolution fails</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<CombatLog> ResolveStatisticalCombatAsync(int combatLogId, object combatParameters, int kingdomId,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Calculates troop effectiveness modifiers based on tier differences, equipment quality,
        /// research bonuses, alliance support, and environmental factors for accurate combat predictions.
        /// </summary>
        /// <param name="attackingArmy">Attacking force composition and bonuses</param>
        /// <param name="defendingArmy">Defending force composition and bonuses</param>
        /// <param name="battleConditions">Environmental and situational factors</param>
        /// <param name="kingdomId">The kingdom context for calculations</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Combat effectiveness calculations with modifier breakdown</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> CalculateTroopEffectivenessAsync(object attackingArmy, object defendingArmy,
            object battleConditions, int kingdomId, CancellationToken cancellationToken = default);

        /// <summary>
        /// Simulates combat outcomes for strategic planning without actually conducting battles.
        /// Provides probability distributions and expected results for tactical decision-making.
        /// </summary>
        /// <param name="simulationParameters">Hypothetical combat scenarios to simulate</param>
        /// <param name="simulationCount">Number of simulation runs for statistical accuracy</param>
        /// <param name="kingdomId">The kingdom context for simulation</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Combat simulation results with probability analysis and outcome predictions</returns>
        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
        Task<object> SimulateCombatOutcomesAsync(object simulationParameters, int simulationCount, int kingdomId,
            CancellationToken cancellationToken = default);

        #endregion
    }
}