feat: add referral management endpoints

Tiku.Application/Growth/ReferralModels.cs

@@ -4,6 +4,8 @@ namespace Tiku.Application.Growth;
 
 public sealed record ReferralActor(Guid TenantId, Guid? UserId = null);
 
+public sealed record ReferralAdminActor(Guid TenantId, Guid UserId);
+
 public sealed record ReferralInviteCommand(string? Channel = null, string? LandingPath = null);
 
 public sealed record ResolveReferralCommand(string? Code);
@@ -27,6 +29,26 @@ public sealed record ReferralQrcodeCommand(
     string? QrcodeUrl,
     JsonElement? Metadata);
 
+public sealed record ReferralStatsQuery(Guid? ReferrerUserId = null, int? Limit = null);
+
+public sealed record ReferralConversionQuery(Guid? ReferrerUserId = null, DateOnly? StartDate = null, DateOnly? EndDate = null, int? Days = null, int? Limit = null);
+
+public sealed record ManualBindReferralCommand(
+    Guid StudentUserId,
+    Guid ReferrerUserId,
+    string? Source,
+    bool Force,
+    JsonElement? Metadata);
+
+public sealed record ReferralTeamQuery(Guid? LeaderUserId = null);
+
+public sealed record UpsertReferralTeamCommand(
+    Guid MemberUserId,
+    Guid? LeaderUserId,
+    string? RelationType,
+    string? Status,
+    JsonElement? Metadata);
+
 public sealed record ReferralInviteItem(string InviteCode);
 
 public sealed record ReferralResolutionItem(
@@ -70,6 +92,37 @@ public sealed record ReferralBindResult(ReferralLeadItem Lead, CrmQueuePreviewIt
 
 public sealed record CrmQueuePreviewItem(Guid Id, string Status, string? Source);
 
+public sealed record ReferralStatsItem(
+    Guid ReferrerUserId,
+    string? Name,
+    string Role,
+    string? InviteCode,
+    int LeadCount,
+    int PaidLeadCount,
+    int PaidAmountCents,
+    int TrackCount,
+    decimal ConversionRate);
+
+public sealed record ReferralList<T>(IReadOnlyCollection<T> Items);
+
+public sealed record ReferralConversionReport(
+    DateOnly StartDate,
+    DateOnly EndDate,
+    int LeadCount,
+    int PaidLeadCount,
+    int PaidAmountCents,
+    decimal ConversionRate,
+    IReadOnlyCollection<ReferralStatsItem> TopReferrers,
+    IReadOnlyCollection<ReferralLeadItem> RecentUnconvertedLeads);
+
+public sealed record ReferralTeamItem(
+    Guid Id,
+    Guid MemberUserId,
+    Guid? LeaderUserId,
+    string RelationType,
+    string Status,
+    JsonElement Metadata);
+
 public interface IReferralService
 {
     Task<ReferralInviteItem> GetOrCreateInviteCodeAsync(
@@ -98,6 +151,41 @@ public interface IReferralService
         ReferralActor actor,
         ReferralQrcodeCommand command,
         CancellationToken cancellationToken = default);
+
+    Task<ReferralStatsItem> GetStatsAsync(
+        ReferralAdminActor actor,
+        ReferralStatsQuery query,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralList<ReferralStatsItem>> GetSalesStatsAsync(
+        ReferralAdminActor actor,
+        ReferralStatsQuery query,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralConversionReport> GetConversionReportAsync(
+        ReferralAdminActor actor,
+        ReferralConversionQuery query,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralList<ReferralLeadItem>> GetClientsAsync(
+        ReferralAdminActor actor,
+        ReferralStatsQuery query,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralBindResult> ManualBindAsync(
+        ReferralAdminActor actor,
+        ManualBindReferralCommand command,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralList<ReferralTeamItem>> GetTeamAsync(
+        ReferralAdminActor actor,
+        ReferralTeamQuery query,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralTeamItem> UpsertTeamAsync(
+        ReferralAdminActor actor,
+        UpsertReferralTeamCommand command,
+        CancellationToken cancellationToken = default);
 }
 
 public sealed class ReferralException(string message, string code) : Exception(message)