Initial import into Gitea

IntelligenceApi/Engines/Franchisor/FranchisorEngine.cs

@@ -0,0 +1,58 @@
+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;
+    }
+}