feat: add referral management endpoints

Tiku.Api/Contracts/ReferralDtos.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel.DataAnnotations;
+using System.Globalization;
 using System.Text.Json;
 using Tiku.Application.Growth;
 
@@ -101,3 +102,102 @@ public sealed class ReferralQrcodeDto
         return new ReferralQrcodeCommand(Page, Scene, Provider, QrcodeUrl, Metadata);
     }
 }
+
+public sealed class ReferralStatsQueryDto
+{
+    public Guid? ReferrerUserId { get; set; }
+
+    [Range(1, 500)]
+    public int? Limit { get; set; }
+
+    public ReferralStatsQuery ToQuery()
+    {
+        return new ReferralStatsQuery(ReferrerUserId, Limit);
+    }
+}
+
+public sealed class ReferralConversionQueryDto
+{
+    public Guid? ReferrerUserId { get; set; }
+
+    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
+    public string? StartDate { get; set; }
+
+    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
+    public string? EndDate { get; set; }
+
+    [Range(1, 365)]
+    public int? Days { get; set; }
+
+    [Range(1, 100)]
+    public int? Limit { get; set; }
+
+    public ReferralConversionQuery ToQuery()
+    {
+        return new ReferralConversionQuery(
+            ReferrerUserId,
+            ParseDate(StartDate),
+            ParseDate(EndDate),
+            Days,
+            Limit);
+    }
+
+    private static DateOnly? ParseDate(string? value)
+    {
+        return string.IsNullOrWhiteSpace(value)
+            ? null
+            : DateOnly.ParseExact(value, "yyyy-MM-dd", CultureInfo.InvariantCulture);
+    }
+}
+
+public sealed class ManualBindReferralDto
+{
+    [Required]
+    public Guid StudentUserId { get; set; }
+
+    [Required]
+    public Guid ReferrerUserId { get; set; }
+
+    [StringLength(100)]
+    public string? Source { get; set; }
+
+    public bool Force { get; set; }
+
+    public JsonElement? Metadata { get; set; }
+
+    public ManualBindReferralCommand ToCommand()
+    {
+        return new ManualBindReferralCommand(StudentUserId, ReferrerUserId, Source, Force, Metadata);
+    }
+}
+
+public sealed class ReferralTeamQueryDto
+{
+    public Guid? LeaderUserId { get; set; }
+
+    public ReferralTeamQuery ToQuery()
+    {
+        return new ReferralTeamQuery(LeaderUserId);
+    }
+}
+
+public sealed class UpsertReferralTeamDto
+{
+    [Required]
+    public Guid MemberUserId { get; set; }
+
+    public Guid? LeaderUserId { get; set; }
+
+    [StringLength(50)]
+    public string? RelationType { get; set; }
+
+    [StringLength(50)]
+    public string? Status { get; set; }
+
+    public JsonElement? Metadata { get; set; }
+
+    public UpsertReferralTeamCommand ToCommand()
+    {
+        return new UpsertReferralTeamCommand(MemberUserId, LeaderUserId, RelationType, Status, Metadata);
+    }
+}