using IntelligenceApi.Models;

namespace IntelligenceApi.Engines.Franchisor;

/// <summary>
/// Spend distribution engine for Franchisor (brand / network owner) clients.
///
/// CURRENT STATUS: Stub — delegates to GeneralEngine logic.
///
/// PLANNED: Network-level AI recommendations incorporating:
///   - Co-op budget allocation across franchisee network
///     (brand-level national vs. local tier split)
///   - Network-wide performance benchmarks and outlier detection
///   - Territory coverage analysis — identifying under-served markets
///   - Brand consistency enforcement across provider configurations
///   - Consolidated reporting roll-up across all franchisee accounts
///   - Seasonal and promotional campaign coordination
///   - Franchisee performance ranking to guide co-op investment priority
///
/// DISTINCTION FROM FRANCHISEE ENGINE:
///   Franchisee = single-location optimisation (local)
///   Franchisor  = multi-location orchestration (network-wide)
///
/// IMPLEMENTATION PATH:
///   1. Inject IFranchiseeNetworkService (all locations, territories, tiers)
///   2. Inject INetworkPerformanceService (aggregate metrics across accounts)
///   3. Implement network-aware allocation: national brand % + local co-op %
///   4. Surface network health summary in DistributionRecommendation
/// </summary>
public sealed class FranchisorEngine : ISpendDistributionEngine
{
    private readonly General.GeneralEngine _general;
    private readonly ILogger<FranchisorEngine> _logger;

    public string EngineName => "Franchisor";

    public FranchisorEngine(General.GeneralEngine general, ILogger<FranchisorEngine> logger)
    {
        _general = general;
        _logger  = logger;
    }

    public async Task<SpendDistributionResponse> RecommendAsync(
        SpendDistributionRequest request, CancellationToken ct)
    {
        _logger.LogInformation(
            "[FranchisorEngine] Stub — delegating to GeneralEngine | Budget={Budget}",
            request.MonthlyBudget);

        var response = await _general.RecommendAsync(request, ct);
        response.Metadata.Engine = EngineName;

        // TODO: Replace with network-aware allocation once
        // IFranchiseeNetworkService is implemented.

        return response;
    }
}