tiku-backend.net/Tiku.Api/Contracts/CommissionDtos.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 UpdateCommissionSettingsDto
{
    /// <summary>
    /// 默认佣金比例。
    /// </summary>
    [Range(0, 1)]
    public decimal? DefaultRate { get; set; }
    /// <summary>
    /// 最低结算金额，单位为分。
    /// </summary>
    [Range(0, int.MaxValue)]
    public int? MinSettlementCents { get; set; }
    /// <summary>
    /// 结算周期。
    /// </summary>
    [StringLength(50)]
    public string? SettlementCycle { get; set; }
    /// <summary>
    /// 配置内容。
    /// </summary>
    public JsonElement? Config { get; set; }
    public UpdateCommissionSettingsCommand ToCommand() => new(DefaultRate, MinSettlementCents, SettlementCycle, Config);
}

/// <summary>
/// 调整成员佣金比例请求。
/// </summary>
public sealed class UpdateMemberCommissionRateDto
{
    /// <summary>
    /// 用户 ID。
    /// </summary>
    [Required]
    public Guid UserId { get; set; }
    /// <summary>
    /// 成员佣金比例。
    /// </summary>
    [Range(0, 1)]
    public decimal? CommissionRate { get; set; }
    /// <summary>
    /// 佣金扩展配置。
    /// </summary>
    public JsonElement? CommissionConfig { get; set; }
    public UpdateMemberCommissionRateCommand ToCommand() => new(UserId, CommissionRate, CommissionConfig);
}

/// <summary>
/// 佣金统计周期查询参数。
/// </summary>
public class CommissionPeriodQueryDto
{
    /// <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>
    /// 推荐人用户 ID。
    /// </summary>
    public Guid? ReferrerUserId { get; set; }
    /// <summary>
    /// 返回数量上限。
    /// </summary>
    [Range(1, 500)]
    public int? Limit { get; set; }
    public CommissionPeriodQuery ToQuery() => new(ParseDate(StartDate), ParseDate(EndDate), ReferrerUserId, Limit);
    protected static DateOnly? ParseDate(string? value) => string.IsNullOrWhiteSpace(value) ? null : DateOnly.ParseExact(value, "yyyy-MM-dd", CultureInfo.InvariantCulture);
}

/// <summary>
/// 佣金结算单查询参数。
/// </summary>
public sealed class CommissionSettlementsQueryDto
{
    /// <summary>
    /// 状态。
    /// </summary>
    [StringLength(50)]
    public string? Status { get; set; }
    /// <summary>
    /// 推荐人用户 ID。
    /// </summary>
    public Guid? ReferrerUserId { get; set; }
    /// <summary>
    /// 返回数量上限。
    /// </summary>
    [Range(1, 500)]
    public int? Limit { get; set; }
    public CommissionSettlementQuery ToQuery() => new(Status, ReferrerUserId, Limit);
}

/// <summary>
/// 生成佣金结算单请求 DTO。
/// </summary>
public sealed class GenerateCommissionSettlementDto
{
    /// <summary>
    /// 开始日期，格式为 yyyy-MM-dd。
    /// </summary>
    [Required]
    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
    public string StartDate { get; set; } = string.Empty;
    /// <summary>
    /// 结束日期，格式为 yyyy-MM-dd。
    /// </summary>
    [Required]
    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
    public string EndDate { get; set; } = string.Empty;
    /// <summary>
    /// 推荐人用户 ID。
    /// </summary>
    [Required]
    public Guid ReferrerUserId { get; set; }
    /// <summary>
    /// 状态。
    /// </summary>
    [StringLength(50)]
    public string? Status { get; set; }
    /// <summary>
    /// 备注。
    /// </summary>
    [StringLength(1000)]
    public string? Remark { get; set; }
    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }
    public GenerateCommissionSettlementCommand ToCommand() => new(Parse(StartDate), Parse(EndDate), ReferrerUserId, Status, Remark, Metadata);
    private static DateOnly Parse(string value) => DateOnly.ParseExact(value, "yyyy-MM-dd", CultureInfo.InvariantCulture);
}

/// <summary>
/// 更新佣金结算单状态请求 DTO。
/// </summary>
public sealed class UpdateCommissionSettlementStatusDto
{
    /// <summary>
    /// 结算单 ID。
    /// </summary>
    [Required]
    public Guid SettlementId { get; set; }
    /// <summary>
    /// 状态。
    /// </summary>
    [StringLength(50)]
    public string? Status { get; set; }
    /// <summary>
    /// 审核备注。
    /// </summary>
    [StringLength(1000)]
    public string? ReviewNote { get; set; }
    /// <summary>
    /// 支付方式。
    /// </summary>
    [StringLength(100)]
    public string? PaymentMethod { get; set; }
    /// <summary>
    /// 收款账号。
    /// </summary>
    [StringLength(200)]
    public string? PaymentAccount { get; set; }
    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }
    public UpdateCommissionSettlementStatusCommand ToCommand() => new(SettlementId, Status, ReviewNote, PaymentMethod, PaymentAccount, Metadata);
}

/// <summary>
/// 佣金结算单导出查询参数。
/// </summary>
public sealed class CommissionSettlementExportQueryDto
{
    /// <summary>
    /// 结算单 ID。
    /// </summary>
    [Required]
    public Guid SettlementId { get; set; }
    /// <summary>
    /// 导出格式。
    /// </summary>
    [StringLength(10)]
    public string? Format { get; set; }
}

/// <summary>
/// 佣金结算单凭证查询参数。
/// </summary>
public sealed class CommissionSettlementProofQueryDto
{
    /// <summary>
    /// 结算单 ID。
    /// </summary>
    [Required]
    public Guid SettlementId { get; set; }
}

/// <summary>
/// 创建佣金结算凭证请求。
/// </summary>
public sealed class CreateCommissionProofDto
{
    /// <summary>
    /// 结算单 ID。
    /// </summary>
    [Required]
    public Guid SettlementId { get; set; }
    /// <summary>
    /// 凭证类型。
    /// </summary>
    [StringLength(50)]
    public string? ProofType { get; set; }
    /// <summary>
    /// 标题。
    /// </summary>
    [StringLength(200)]
    public string? Title { get; set; }
    /// <summary>
    /// 说明。
    /// </summary>
    [StringLength(2000)]
    public string? Description { get; set; }
    /// <summary>
    /// 资产 ID。
    /// </summary>
    public Guid? AssetId { get; set; }
    /// <summary>
    /// 外部链接。
    /// </summary>
    [StringLength(2048)]
    public string? ExternalUrl { get; set; }
    /// <summary>
    /// 金额，单位为分。
    /// </summary>
    [Range(0, int.MaxValue)]
    public int? AmountCents { get; set; }
    /// <summary>
    /// 支付方式。
    /// </summary>
    [StringLength(100)]
    public string? PaymentMethod { get; set; }
    /// <summary>
    /// 收款账号。
    /// </summary>
    [StringLength(200)]
    public string? PaymentAccount { get; set; }
    /// <summary>
    /// 支付时间。
    /// </summary>
    public DateTimeOffset? PaidAt { get; set; }
    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }
    public CreateCommissionProofCommand ToCommand() => new(SettlementId, ProofType, Title, Description, AssetId, ExternalUrl, AmountCents, PaymentMethod, PaymentAccount, PaidAt, Metadata);
}

/// <summary>
/// 更新佣金结算凭证状态请求。
/// </summary>
public sealed class UpdateCommissionProofStatusDto
{
    /// <summary>
    /// 凭证 ID。
    /// </summary>
    [Required]
    public Guid ProofId { get; set; }
    /// <summary>
    /// 状态。
    /// </summary>
    [StringLength(50)]
    public string? Status { get; set; }
    /// <summary>
    /// 审核备注。
    /// </summary>
    [StringLength(1000)]
    public string? ReviewNote { get; set; }
    /// <summary>
    /// 扩展元数据。
    /// </summary>
    public JsonElement? Metadata { get; set; }
    public UpdateCommissionProofStatusCommand ToCommand() => new(ProofId, Status, ReviewNote, Metadata);
}