Initial import into Gitea

IntelligenceApi/Models/SpendDistributionModels.cs

@@ -0,0 +1,117 @@
+namespace IntelligenceApi.Models;
+
+// ════════════════════════════════════════════════
+// Request: Gateway → IntelligenceApi
+// Gateway injects clientCategory from ClientContext
+// before forwarding the wizard's forecast request.
+// ════════════════════════════════════════════════
+
+public sealed class SpendDistributionRequest
+{
+    /// <summary>
+    /// Client category — the primary engine selector.
+    /// Values: General | Franchisee | Franchisor | FoodFranchisee | etc.
+    /// Injected by the Gateway from ClientContext.ClientCategory.
+    /// </summary>
+    public string ClientCategory { get; set; } = "General";
+
+    /// <summary>Advertising objective: awareness, traffic, leads, sales</summary>
+    public string Objective { get; set; } = "traffic";
+
+    /// <summary>Business category from wizard Step 1 (industry)</summary>
+    public string? BusinessCategory { get; set; }
+
+    /// <summary>Keywords from URL analysis</summary>
+    public List<string> Keywords { get; set; } = new();
+
+    /// <summary>Geo targeting from audience step</summary>
+    public GeoTargeting? GeoTargeting { get; set; }
+
+    /// <summary>Audience parameters</summary>
+    public AudienceParams? Audience { get; set; }
+
+    /// <summary>Monthly budget in whole dollars</summary>
+    public decimal MonthlyBudget { get; set; }
+
+    /// <summary>Channels to estimate</summary>
+    public List<string>? Channels { get; set; }
+
+    /// <summary>
+    /// Provider base URLs forwarded from Gateway config.
+    /// Allows engines to call providers without needing their own config.
+    /// </summary>
+    public Dictionary<string, string>? ProviderUrls { get; set; }
+
+    /// <summary>Internal API keys forwarded from Gateway config.</summary>
+    public Dictionary<string, string>? InternalKeys { get; set; }
+}
+
+public sealed class GeoTargeting
+{
+    public List<string>? ZipCodes { get; set; }
+    public double? RadiusMiles { get; set; }
+    public List<long>? GeoTargetIds { get; set; }
+}
+
+public sealed class AudienceParams
+{
+    public int? AgeMin { get; set; }
+    public int? AgeMax { get; set; }
+    public List<string>? Genders { get; set; }
+    public List<string>? Interests { get; set; }
+}
+
+// ════════════════════════════════════════════════
+// Response: IntelligenceApi → Gateway → Client
+// Identical shape to ChannelForecastResponse in
+// the Gateway so no client changes are needed.
+// ════════════════════════════════════════════════
+
+public sealed class SpendDistributionResponse
+{
+    public bool Ok { get; set; } = true;
+    public string Objective { get; set; } = string.Empty;
+    public decimal TotalBudget { get; set; }
+    public List<ChannelAllocation> Channels { get; set; } = new();
+    public DistributionRecommendation? Recommendation { get; set; }
+    public DistributionMeta Metadata { get; set; } = new();
+}
+
+public sealed class ChannelAllocation
+{
+    public string Provider { get; set; } = string.Empty;
+    public int AllocationPercent { get; set; }
+    public decimal AllocatedBudget { get; set; }
+    public AllocationMetrics Estimates { get; set; } = new();
+    public double EfficiencyScore { get; set; }
+    public string StrengthLabel { get; set; } = string.Empty;
+    public string Confidence { get; set; } = "none";
+    public string DataSource { get; set; } = "none";
+}
+
+public sealed class AllocationMetrics
+{
+    public double Impressions { get; set; }
+    public double? Reach { get; set; }
+    public double Clicks { get; set; }
+    public double Conversions { get; set; }
+    public decimal AvgCpc { get; set; }
+    public decimal AvgCpm { get; set; }
+    public decimal? EstimatedCpa { get; set; }
+    public double Ctr { get; set; }
+}
+
+public sealed class DistributionRecommendation
+{
+    public string Summary { get; set; } = string.Empty;
+    public List<string> Highlights { get; set; } = new();
+}
+
+public sealed class DistributionMeta
+{
+    public DateTimeOffset GeneratedAt { get; set; } = DateTimeOffset.UtcNow;
+    public string ForecastPeriod { get; set; } = "30 days";
+
+    /// <summary>Which engine handled this request — useful for debugging and billing.</summary>
+    public string Engine { get; set; } = "General";
+}