tiku-backend.net/Tiku.Api/Contracts/ReferralDtos.cs

using System.ComponentModel.DataAnnotations;
using System.Globalization;
using System.Text.Json;
using Tiku.Application.Growth;

namespace Tiku.Api.Contracts;

/// <summary>
/// 推荐租户查询参数。
/// </summary>
public sealed class ReferralTenantQueryDto
{
    /// <summary>
    /// 租户编码。
    /// </summary>
    [StringLength(100)]
    public string? TenantCode { get; set; }
}

/// <summary>
/// 推荐邀请码请求 DTO。
/// </summary>
public sealed class ReferralInviteDto
{
    /// <summary>
    /// 渠道。
    /// </summary>
    [StringLength(100)]
    public string? Channel { get; set; }

    /// <summary>
    /// 落地页路径。
    /// </summary>
    [StringLength(2048)]
    public string? LandingPath { get; set; }

    public ReferralInviteCommand ToCommand()
    {
        return new ReferralInviteCommand(Channel, LandingPath);
    }
}

/// <summary>
/// 解析推荐请求 DTO。
/// </summary>
public sealed class ResolveReferralDto
{
    /// <summary>
    /// 编码。
    /// </summary>
    [StringLength(100)]
    public string? Code { get; set; }

    /// <summary>
    /// 租户编码。
    /// </summary>
    [StringLength(100)]
    public string? TenantCode { get; set; }

    public ResolveReferralCommand ToCommand()
    {
        return new ResolveReferralCommand(Code);
    }
}

/// <summary>
/// 记录推荐事件请求 DTO。
/// </summary>
public sealed class TrackReferralEventDto
{
    /// <summary>
    /// 推荐码。
    /// </summary>
    [Required]
    [StringLength(100)]
    public string RefCode { get; set; } = string.Empty;

    /// <summary>
    /// 事件类型。
    /// </summary>
    [StringLength(100)]
    public string? EventType { get; set; }

    /// <summary>
    /// 来源。
    /// </summary>
    [StringLength(100)]
    public string? Source { get; set; }

    /// <summary>
    /// 目标用户 ID。
    /// </summary>
    public Guid? TargetUserId { get; set; }

    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }

    /// <summary>
    /// 租户编码。
    /// </summary>
    [StringLength(100)]
    public string? TenantCode { get; set; }

    public TrackReferralEventCommand ToCommand()
    {
        return new TrackReferralEventCommand(RefCode, EventType, Source, TargetUserId, Metadata);
    }
}

/// <summary>
/// 绑定推荐请求 DTO。
/// </summary>
public sealed class BindReferralDto
{
    /// <summary>
    /// 推荐码。
    /// </summary>
    [Required]
    [StringLength(100)]
    public string RefCode { get; set; } = string.Empty;

    /// <summary>
    /// 来源。
    /// </summary>
    [StringLength(100)]
    public string? Source { get; set; }

    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }

    public BindReferralCommand ToCommand()
    {
        return new BindReferralCommand(RefCode, Source, Metadata);
    }
}

/// <summary>
/// 推荐二维码请求 DTO。
/// </summary>
public sealed class ReferralQrcodeDto
{
    /// <summary>
    /// 页码。
    /// </summary>
    [StringLength(500)]
    public string? Page { get; set; }

    /// <summary>
    /// 场景参数。
    /// </summary>
    [StringLength(128)]
    public string? Scene { get; set; }

    /// <summary>
    /// 服务提供方。
    /// </summary>
    [StringLength(100)]
    public string? Provider { get; set; }

    /// <summary>
    /// 二维码地址。
    /// </summary>
    [StringLength(2048)]
    public string? QrcodeUrl { get; set; }

    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }

    public ReferralQrcodeCommand ToCommand()
    {
        return new ReferralQrcodeCommand(Page, Scene, Provider, QrcodeUrl, Metadata);
    }
}

/// <summary>
/// 推荐统计查询参数。
/// </summary>
public sealed class ReferralStatsQueryDto
{
    /// <summary>
    /// 推荐人用户 ID。
    /// </summary>
    public Guid? ReferrerUserId { get; set; }

    /// <summary>
    /// 返回数量上限。
    /// </summary>
    [Range(1, 500)]
    public int? Limit { get; set; }

    public ReferralStatsQuery ToQuery()
    {
        return new ReferralStatsQuery(ReferrerUserId, Limit);
    }
}

/// <summary>
/// 推荐Conversion查询参数。
/// </summary>
public sealed class ReferralConversionQueryDto
{
    /// <summary>
    /// 推荐人用户 ID。
    /// </summary>
    public Guid? ReferrerUserId { get; set; }

    /// <summary>
    /// 开始日期，格式为 yyyy-MM-dd。
    /// </summary>
    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
    public string? StartDate { get; set; }

    /// <summary>
    /// 结束日期，格式为 yyyy-MM-dd。
    /// </summary>
    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
    public string? EndDate { get; set; }

    /// <summary>
    /// 天数。
    /// </summary>
    [Range(1, 365)]
    public int? Days { get; set; }

    /// <summary>
    /// 返回数量上限。
    /// </summary>
    [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);
    }
}

/// <summary>
/// 人工绑定推荐请求 DTO。
/// </summary>
public sealed class ManualBindReferralDto
{
    /// <summary>
    /// 学生用户 ID。
    /// </summary>
    [Required]
    public Guid StudentUserId { get; set; }

    /// <summary>
    /// 推荐人用户 ID。
    /// </summary>
    [Required]
    public Guid ReferrerUserId { get; set; }

    /// <summary>
    /// 来源。
    /// </summary>
    [StringLength(100)]
    public string? Source { get; set; }

    /// <summary>
    /// 是否强制执行。
    /// </summary>
    public bool Force { get; set; }

    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }

    public ManualBindReferralCommand ToCommand()
    {
        return new ManualBindReferralCommand(StudentUserId, ReferrerUserId, Source, Force, Metadata);
    }
}

/// <summary>
/// 推荐团队查询参数。
/// </summary>
public sealed class ReferralTeamQueryDto
{
    /// <summary>
    /// 上级成员用户 ID。
    /// </summary>
    public Guid? LeaderUserId { get; set; }

    public ReferralTeamQuery ToQuery()
    {
        return new ReferralTeamQuery(LeaderUserId);
    }
}

/// <summary>
/// 新增或更新推荐团队请求 DTO。
/// </summary>
public sealed class UpsertReferralTeamDto
{
    /// <summary>
    /// 成员用户 ID。
    /// </summary>
    [Required]
    public Guid MemberUserId { get; set; }

    /// <summary>
    /// 上级成员用户 ID。
    /// </summary>
    public Guid? LeaderUserId { get; set; }

    /// <summary>
    /// 关系类型。
    /// </summary>
    [StringLength(50)]
    public string? RelationType { get; set; }

    /// <summary>
    /// 状态。
    /// </summary>
    [StringLength(50)]
    public string? Status { get; set; }

    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }

    public UpsertReferralTeamCommand ToCommand()
    {
        return new UpsertReferralTeamCommand(MemberUserId, LeaderUserId, RelationType, Status, Metadata);
    }
}