feat: add referral growth endpoints

Tiku.Application/Growth/ReferralModels.cs

@@ -0,0 +1,106 @@
+using System.Text.Json;
+
+namespace Tiku.Application.Growth;
+
+public sealed record ReferralActor(Guid TenantId, Guid? UserId = null);
+
+public sealed record ReferralInviteCommand(string? Channel = null, string? LandingPath = null);
+
+public sealed record ResolveReferralCommand(string? Code);
+
+public sealed record TrackReferralEventCommand(
+    string RefCode,
+    string? EventType,
+    string? Source,
+    Guid? TargetUserId,
+    JsonElement? Metadata);
+
+public sealed record BindReferralCommand(
+    string RefCode,
+    string? Source,
+    JsonElement? Metadata);
+
+public sealed record ReferralQrcodeCommand(
+    string? Page,
+    string? Scene,
+    string? Provider,
+    string? QrcodeUrl,
+    JsonElement? Metadata);
+
+public sealed record ReferralInviteItem(string InviteCode);
+
+public sealed record ReferralResolutionItem(
+    bool Valid,
+    Guid? InviterId,
+    string? InviteCode,
+    string? Role,
+    string? Name);
+
+public sealed record ReferralTrackItem(
+    Guid Id,
+    string EventType,
+    string? RefCode,
+    Guid? ReferrerUserId,
+    Guid? TargetUserId,
+    string? Source,
+    DateTimeOffset CreatedAt);
+
+public sealed record ReferralLeadItem(
+    Guid Id,
+    Guid StudentUserId,
+    Guid? ReferrerUserId,
+    string? RefCode,
+    string Status,
+    DateTimeOffset BoundAt,
+    bool Changed);
+
+public sealed record ReferralQrcodeItem(
+    Guid Id,
+    string RefCode,
+    string Scene,
+    string Page,
+    string Provider,
+    string? QrcodeUrl,
+    string Status,
+    JsonElement Metadata);
+
+public sealed record ReferralTrackResult(ReferralTrackItem Item, ReferralLeadItem? Lead, CrmQueuePreviewItem? CrmQueue);
+
+public sealed record ReferralBindResult(ReferralLeadItem Lead, CrmQueuePreviewItem? CrmQueue);
+
+public sealed record CrmQueuePreviewItem(Guid Id, string Status, string? Source);
+
+public interface IReferralService
+{
+    Task<ReferralInviteItem> GetOrCreateInviteCodeAsync(
+        ReferralActor actor,
+        ReferralInviteCommand command,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralResolutionItem> ResolveAsync(
+        ReferralActor actor,
+        ResolveReferralCommand command,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralTrackResult> TrackEventAsync(
+        ReferralActor actor,
+        TrackReferralEventCommand command,
+        string? ipAddress,
+        string? userAgent,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralBindResult> BindAsync(
+        ReferralActor actor,
+        BindReferralCommand command,
+        CancellationToken cancellationToken = default);
+
+    Task<ReferralQrcodeItem> GetOrCreateQrcodeAsync(
+        ReferralActor actor,
+        ReferralQrcodeCommand command,
+        CancellationToken cancellationToken = default);
+}
+
+public sealed class ReferralException(string message, string code) : Exception(message)
+{
+    public string Code { get; } = code;
+}