Initial import into Gitea

IntelligenceApi/Engines/Franchisee/FranchiseeEngine.cs

@@ -0,0 +1,59 @@
+using IntelligenceApi.Models;
+
+namespace IntelligenceApi.Engines.Franchisee;
+
+/// <summary>
+/// Spend distribution engine for Franchisee clients.
+///
+/// CURRENT STATUS: Stub — delegates to GeneralEngine logic.
+/// Returns General recommendations with engine name set to "Franchisee"
+/// so billing and logging correctly identify the tier.
+///
+/// PLANNED: Premium AI-driven recommendations incorporating:
+///   - Proximity analysis to sibling franchisee locations
+///     (avoid cannibalisation, identify territory gaps)
+///   - Local competitor density from Google Maps / Places API
+///   - Demographic fit scoring per geo zone
+///   - Franchisor brand guidelines (approved channels, spend floors)
+///   - Historical performance benchmarks across the franchise network
+///   - Dayparting patterns specific to the franchise category
+///     (e.g. lunch peaks for food, weekend spikes for home services)
+///
+/// IMPLEMENTATION PATH:
+///   1. Inject IFranchiseeDataService (location DB + geo queries)
+///   2. Inject ICompetitorIntelligenceService (Places API or similar)
+///   3. Replace scoring weights with category-trained model output
+///   4. Surface franchise-specific highlights in DistributionRecommendation
+/// </summary>
+public sealed class FranchiseeEngine : ISpendDistributionEngine
+{
+    private readonly General.GeneralEngine _general;
+    private readonly ILogger<FranchiseeEngine> _logger;
+
+    public string EngineName => "Franchisee";
+
+    public FranchiseeEngine(General.GeneralEngine general, ILogger<FranchiseeEngine> logger)
+    {
+        _general = general;
+        _logger  = logger;
+    }
+
+    public async Task<SpendDistributionResponse> RecommendAsync(
+        SpendDistributionRequest request, CancellationToken ct)
+    {
+        _logger.LogInformation(
+            "[FranchiseeEngine] Stub — delegating to GeneralEngine | Budget={Budget}",
+            request.MonthlyBudget);
+
+        // Delegate to General for now
+        var response = await _general.RecommendAsync(request, ct);
+
+        // Override engine name so billing / logging is correct
+        response.Metadata.Engine = EngineName;
+
+        // TODO: Augment recommendation with franchise-specific insights
+        // once data services are wired in.
+
+        return response;
+    }
+}