feat: add commission settlement endpoints

Tiku.Api/Contracts/CommissionDtos.cs

@@ -0,0 +1,136 @@
+using System.ComponentModel.DataAnnotations;
+using System.Globalization;
+using System.Text.Json;
+using Tiku.Application.Growth;
+
+namespace Tiku.Api.Contracts;
+
+public sealed class UpdateCommissionSettingsDto
+{
+    [Range(0, 1)]
+    public decimal? DefaultRate { get; set; }
+    [Range(0, int.MaxValue)]
+    public int? MinSettlementCents { get; set; }
+    [StringLength(50)]
+    public string? SettlementCycle { get; set; }
+    public JsonElement? Config { get; set; }
+    public UpdateCommissionSettingsCommand ToCommand() => new(DefaultRate, MinSettlementCents, SettlementCycle, Config);
+}
+
+public sealed class UpdateMemberCommissionRateDto
+{
+    [Required]
+    public Guid UserId { get; set; }
+    [Range(0, 1)]
+    public decimal? CommissionRate { get; set; }
+    public JsonElement? CommissionConfig { get; set; }
+    public UpdateMemberCommissionRateCommand ToCommand() => new(UserId, CommissionRate, CommissionConfig);
+}
+
+public class CommissionPeriodQueryDto
+{
+    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
+    public string? StartDate { get; set; }
+    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
+    public string? EndDate { get; set; }
+    public Guid? ReferrerUserId { get; set; }
+    [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);
+}
+
+public sealed class CommissionSettlementsQueryDto
+{
+    [StringLength(50)]
+    public string? Status { get; set; }
+    public Guid? ReferrerUserId { get; set; }
+    [Range(1, 500)]
+    public int? Limit { get; set; }
+    public CommissionSettlementQuery ToQuery() => new(Status, ReferrerUserId, Limit);
+}
+
+public sealed class GenerateCommissionSettlementDto
+{
+    [Required]
+    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
+    public string StartDate { get; set; } = string.Empty;
+    [Required]
+    [RegularExpression("^\\d{4}-\\d{2}-\\d{2}$")]
+    public string EndDate { get; set; } = string.Empty;
+    [Required]
+    public Guid ReferrerUserId { get; set; }
+    [StringLength(50)]
+    public string? Status { get; set; }
+    [StringLength(1000)]
+    public string? Remark { get; set; }
+    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);
+}
+
+public sealed class UpdateCommissionSettlementStatusDto
+{
+    [Required]
+    public Guid SettlementId { get; set; }
+    [StringLength(50)]
+    public string? Status { get; set; }
+    [StringLength(1000)]
+    public string? ReviewNote { get; set; }
+    [StringLength(100)]
+    public string? PaymentMethod { get; set; }
+    [StringLength(200)]
+    public string? PaymentAccount { get; set; }
+    public JsonElement? Metadata { get; set; }
+    public UpdateCommissionSettlementStatusCommand ToCommand() => new(SettlementId, Status, ReviewNote, PaymentMethod, PaymentAccount, Metadata);
+}
+
+public sealed class CommissionSettlementExportQueryDto
+{
+    [Required]
+    public Guid SettlementId { get; set; }
+    [StringLength(10)]
+    public string? Format { get; set; }
+}
+
+public sealed class CommissionSettlementProofQueryDto
+{
+    [Required]
+    public Guid SettlementId { get; set; }
+}
+
+public sealed class CreateCommissionProofDto
+{
+    [Required]
+    public Guid SettlementId { get; set; }
+    [StringLength(50)]
+    public string? ProofType { get; set; }
+    [StringLength(200)]
+    public string? Title { get; set; }
+    [StringLength(2000)]
+    public string? Description { get; set; }
+    public Guid? AssetId { get; set; }
+    [StringLength(2048)]
+    public string? ExternalUrl { get; set; }
+    [Range(0, int.MaxValue)]
+    public int? AmountCents { get; set; }
+    [StringLength(100)]
+    public string? PaymentMethod { get; set; }
+    [StringLength(200)]
+    public string? PaymentAccount { get; set; }
+    public DateTimeOffset? PaidAt { get; set; }
+    public JsonElement? Metadata { get; set; }
+    public CreateCommissionProofCommand ToCommand() => new(SettlementId, ProofType, Title, Description, AssetId, ExternalUrl, AmountCents, PaymentMethod, PaymentAccount, PaidAt, Metadata);
+}
+
+public sealed class UpdateCommissionProofStatusDto
+{
+    [Required]
+    public Guid ProofId { get; set; }
+    [StringLength(50)]
+    public string? Status { get; set; }
+    [StringLength(1000)]
+    public string? ReviewNote { get; set; }
+    public JsonElement? Metadata { get; set; }
+    public UpdateCommissionProofStatusCommand ToCommand() => new(ProofId, Status, ReviewNote, Metadata);
+}

Tiku.Api/Controllers/CommissionController.cs

@@ -0,0 +1,75 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Tiku.Api.Contracts;
+using Tiku.Application.Growth;
+using Tiku.Application.Security;
+
+namespace Tiku.Api.Controllers;
+
+[ApiController]
+[Authorize(Policy = TikuPolicies.TenantAdmin)]
+[Produces("application/json")]
+[Route("api/commission")]
+public sealed class CommissionController(
+    ICommissionService commissionService,
+    ICurrentUser currentUser,
+    ICurrentTenant currentTenant) : ControllerBase
+{
+    [HttpGet("settings")]
+    public async Task<ActionResult<CommissionSettingsItem>> Settings(CancellationToken cancellationToken) =>
+        Ok(await commissionService.GetSettingsAsync(ResolveActor(), cancellationToken));
+
+    [HttpPut("settings")]
+    public async Task<ActionResult<CommissionSettingsItem>> UpdateSettings(UpdateCommissionSettingsDto request, CancellationToken cancellationToken) =>
+        Ok(await commissionService.UpdateSettingsAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+
+    [HttpPut("member-rate")]
+    public async Task<ActionResult<object>> MemberRate(UpdateMemberCommissionRateDto request, CancellationToken cancellationToken) =>
+        Ok(await commissionService.UpdateMemberRateAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+
+    [HttpGet("summary")]
+    public async Task<ActionResult<CommissionSummaryItem>> Summary([FromQuery] CommissionPeriodQueryDto query, CancellationToken cancellationToken) =>
+        Ok(await commissionService.GetSummaryAsync(ResolveActor(), query.ToQuery(), cancellationToken));
+
+    [HttpGet("orders")]
+    public async Task<ActionResult<CommissionList<CommissionSourceItem>>> Orders([FromQuery] CommissionPeriodQueryDto query, CancellationToken cancellationToken) =>
+        Ok(await commissionService.GetOrdersAsync(ResolveActor(), query.ToQuery(), cancellationToken));
+
+    [HttpGet("settlements")]
+    public async Task<ActionResult<CommissionList<CommissionSettlementItemDto>>> Settlements([FromQuery] CommissionSettlementsQueryDto query, CancellationToken cancellationToken) =>
+        Ok(await commissionService.GetSettlementsAsync(ResolveActor(), query.ToQuery(), cancellationToken));
+
+    [HttpGet("settlements/export")]
+    public async Task<ActionResult<CommissionExportItem>> Export([FromQuery] CommissionSettlementExportQueryDto query, CancellationToken cancellationToken) =>
+        Ok(await commissionService.ExportSettlementAsync(ResolveActor(), query.SettlementId, query.Format, cancellationToken));
+
+    [HttpPost("settlements/generate")]
+    public async Task<ActionResult<CommissionSettlementItemDto>> Generate(GenerateCommissionSettlementDto request, CancellationToken cancellationToken) =>
+        Ok(await commissionService.GenerateSettlementAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+
+    [HttpPost("settlements/status")]
+    public async Task<ActionResult<CommissionSettlementItemDto>> UpdateStatus(UpdateCommissionSettlementStatusDto request, CancellationToken cancellationToken) =>
+        Ok(await commissionService.UpdateSettlementStatusAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+
+    [HttpGet("settlements/proofs")]
+    public async Task<ActionResult<CommissionList<CommissionProofItem>>> Proofs([FromQuery] CommissionSettlementProofQueryDto query, CancellationToken cancellationToken) =>
+        Ok(await commissionService.GetProofsAsync(ResolveActor(), query.SettlementId, cancellationToken));
+
+    [HttpPost("settlements/proofs")]
+    public async Task<ActionResult<CommissionProofItem>> CreateProof(CreateCommissionProofDto request, CancellationToken cancellationToken) =>
+        Ok(await commissionService.CreateProofAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+
+    [HttpPost("settlements/proofs/status")]
+    public async Task<ActionResult<CommissionProofItem>> UpdateProofStatus(UpdateCommissionProofStatusDto request, CancellationToken cancellationToken) =>
+        Ok(await commissionService.UpdateProofStatusAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+
+    private CommissionAdminActor ResolveActor()
+    {
+        if (currentTenant.TenantId is null || currentUser.UserId is null)
+        {
+            throw new CommissionException("Commission admin actor was not resolved.", "commission_access_denied");
+        }
+
+        return new CommissionAdminActor(currentTenant.TenantId.Value, currentUser.UserId.Value);
+    }
+}

Tiku.Api/Middleware/ExceptionHandlingMiddleware.cs

@@ -215,6 +215,16 @@ public sealed class ExceptionHandlingMiddleware(
                 return;
             }
 
+            if (exception is CommissionException commissionException)
+            {
+                await WriteProblemAsync(
+                    context,
+                    commissionException.Message,
+                    CommissionStatusCode(commissionException.Code),
+                    commissionException.Code);
+                return;
+            }
+
             if (exception is PaymentProviderException paymentProviderException)
             {
                 await WriteProblemAsync(
@@ -410,4 +420,17 @@ public sealed class ExceptionHandlingMiddleware(
             _ => StatusCodes.Status400BadRequest
         };
     }
+
+    private static int CommissionStatusCode(string code)
+    {
+        return code switch
+        {
+            "commission_access_denied" => StatusCodes.Status403Forbidden,
+            "commission_member_not_found" or "commission_settlement_not_found" or "commission_proof_not_found" =>
+                StatusCodes.Status404NotFound,
+            "commission_no_unsettled_sources" or "commission_below_minimum" or "commission_status_invalid" or
+                "commission_proof_closed" => StatusCodes.Status409Conflict,
+            _ => StatusCodes.Status400BadRequest
+        };
+    }
 }

Tiku.Application/Growth/CommissionModels.cs

@@ -0,0 +1,90 @@
+using System.Text.Json;
+
+namespace Tiku.Application.Growth;
+
+public sealed record CommissionAdminActor(Guid TenantId, Guid UserId);
+
+public sealed record UpdateCommissionSettingsCommand(decimal? DefaultRate, int? MinSettlementCents, string? SettlementCycle, JsonElement? Config);
+
+public sealed record UpdateMemberCommissionRateCommand(Guid UserId, decimal? CommissionRate, JsonElement? CommissionConfig);
+
+public sealed record CommissionPeriodQuery(DateOnly? StartDate = null, DateOnly? EndDate = null, Guid? ReferrerUserId = null, int? Limit = null);
+
+public sealed record CommissionSettlementQuery(string? Status = null, Guid? ReferrerUserId = null, int? Limit = null);
+
+public sealed record GenerateCommissionSettlementCommand(DateOnly StartDate, DateOnly EndDate, Guid ReferrerUserId, string? Status, string? Remark, JsonElement? Metadata);
+
+public sealed record UpdateCommissionSettlementStatusCommand(Guid SettlementId, string? Status, string? ReviewNote, string? PaymentMethod, string? PaymentAccount, JsonElement? Metadata);
+
+public sealed record CreateCommissionProofCommand(Guid SettlementId, string? ProofType, string? Title, string? Description, Guid? AssetId, string? ExternalUrl, int? AmountCents, string? PaymentMethod, string? PaymentAccount, DateTimeOffset? PaidAt, JsonElement? Metadata);
+
+public sealed record UpdateCommissionProofStatusCommand(Guid ProofId, string? Status, string? ReviewNote, JsonElement? Metadata);
+
+public sealed record CommissionSettingsItem(decimal DefaultRate, int MinSettlementCents, string SettlementCycle, JsonElement Config);
+
+public sealed record CommissionSourceItem(
+    string SourceType,
+    Guid SourceId,
+    string? SourceNo,
+    Guid ReferrerUserId,
+    Guid? StudentUserId,
+    int GrossAmountCents,
+    decimal CommissionRate,
+    int CommissionAmountCents,
+    string RateSource,
+    Guid? SettlementId);
+
+public sealed record CommissionSummaryItem(int SourceCount, int PaidUserCount, int GrossAmountCents, int CommissionAmountCents);
+
+public sealed record CommissionSettlementItemDto(
+    Guid Id,
+    string SettlementNo,
+    Guid ReferrerUserId,
+    string Status,
+    DateOnly PeriodStart,
+    DateOnly PeriodEnd,
+    int SourceCount,
+    int PaidUserCount,
+    int GrossAmountCents,
+    int CommissionAmountCents,
+    DateTimeOffset? ReviewedAt,
+    DateTimeOffset? PaidAt);
+
+public sealed record CommissionProofItem(
+    Guid Id,
+    Guid SettlementId,
+    string ProofType,
+    string Status,
+    string? Title,
+    Guid? AssetId,
+    string? ExternalUrl,
+    int? AmountCents,
+    string? PaymentMethod,
+    string? PaymentAccount,
+    DateTimeOffset? PaidAt,
+    DateTimeOffset? ReviewedAt);
+
+public sealed record CommissionExportItem(Guid SettlementId, string Filename, string Format, string MimeType, int RowCount, string ContentBase64, string Sha256, int SizeBytes);
+
+public sealed record CommissionList<T>(IReadOnlyCollection<T> Items);
+
+public interface ICommissionService
+{
+    Task<CommissionSettingsItem> GetSettingsAsync(CommissionAdminActor actor, CancellationToken cancellationToken = default);
+    Task<CommissionSettingsItem> UpdateSettingsAsync(CommissionAdminActor actor, UpdateCommissionSettingsCommand command, CancellationToken cancellationToken = default);
+    Task<object> UpdateMemberRateAsync(CommissionAdminActor actor, UpdateMemberCommissionRateCommand command, CancellationToken cancellationToken = default);
+    Task<CommissionSummaryItem> GetSummaryAsync(CommissionAdminActor actor, CommissionPeriodQuery query, CancellationToken cancellationToken = default);
+    Task<CommissionList<CommissionSourceItem>> GetOrdersAsync(CommissionAdminActor actor, CommissionPeriodQuery query, CancellationToken cancellationToken = default);
+    Task<CommissionList<CommissionSettlementItemDto>> GetSettlementsAsync(CommissionAdminActor actor, CommissionSettlementQuery query, CancellationToken cancellationToken = default);
+    Task<CommissionExportItem> ExportSettlementAsync(CommissionAdminActor actor, Guid settlementId, string? format, CancellationToken cancellationToken = default);
+    Task<CommissionSettlementItemDto> GenerateSettlementAsync(CommissionAdminActor actor, GenerateCommissionSettlementCommand command, CancellationToken cancellationToken = default);
+    Task<CommissionSettlementItemDto> UpdateSettlementStatusAsync(CommissionAdminActor actor, UpdateCommissionSettlementStatusCommand command, CancellationToken cancellationToken = default);
+    Task<CommissionList<CommissionProofItem>> GetProofsAsync(CommissionAdminActor actor, Guid settlementId, CancellationToken cancellationToken = default);
+    Task<CommissionProofItem> CreateProofAsync(CommissionAdminActor actor, CreateCommissionProofCommand command, CancellationToken cancellationToken = default);
+    Task<CommissionProofItem> UpdateProofStatusAsync(CommissionAdminActor actor, UpdateCommissionProofStatusCommand command, CancellationToken cancellationToken = default);
+}
+
+public sealed class CommissionException(string message, string code) : Exception(message)
+{
+    public string Code { get; } = code;
+}

Tiku.Domain/Growth/GrowthEntities.cs

@@ -168,6 +168,39 @@ public sealed class CommissionSettlementItem : AuditableTenantEntity
     public JsonElement Metadata { get; set; } = JsonDefaults.Object();
 }
 
+public sealed class CommissionSettlementProof : AuditableTenantEntity
+{
+    public Guid SettlementId { get; set; }
+    public Guid? AssetId { get; set; }
+    public Guid? SubmittedBy { get; set; }
+    public Guid? ReviewedBy { get; set; }
+    public CommissionProofType ProofType { get; set; } = CommissionProofType.Payment;
+    public CommissionProofStatus Status { get; set; } = CommissionProofStatus.Submitted;
+    public string? Title { get; set; }
+    public string? Description { get; set; }
+    public string? ExternalUrl { get; set; }
+    public int? AmountCents { get; set; }
+    public string? PaymentMethod { get; set; }
+    public string? PaymentAccount { get; set; }
+    public DateTimeOffset? PaidAt { get; set; }
+    public DateTimeOffset? ReviewedAt { get; set; }
+    public string? ReviewNote { get; set; }
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+}
+
+public sealed class CommissionSettlementExportEvent : Entity
+{
+    public Guid TenantId { get; set; }
+    public Guid SettlementId { get; set; }
+    public Guid? ExportedBy { get; set; }
+    public string ExportFormat { get; set; } = "csv";
+    public string Filename { get; set; } = string.Empty;
+    public int RowCount { get; set; }
+    public string? ContentSha256 { get; set; }
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
+}
+
 public enum ReferralCodeStatus { Active, Disabled }
 public enum ReferralLeadBindType { FirstTouch, Manual, Imported }
 public enum ReferralLeadStatus { Protected, Invalid, Released }
@@ -180,3 +213,5 @@ public enum CommissionSettlementCycle { Manual, Weekly, Monthly }
 public enum CommissionSettlementStatus { Draft, PendingReview, Approved, Paid, Rejected, Cancelled }
 public enum CommissionSourceType { Order, ActivationCode }
 public enum CommissionRateSource { Batch, Member, Default }
+public enum CommissionProofType { Payment, Invoice, Receipt, Adjustment, Other }
+public enum CommissionProofStatus { Submitted, Approved, Rejected, Voided }

Tiku.Infrastructure/DependencyInjection.cs

@@ -72,6 +72,7 @@ public static class DependencyInjection
         services.AddScoped<IPointService, PointService>();
         services.AddScoped<IReferralService, ReferralService>();
         services.AddScoped<ICrmService, CrmService>();
+        services.AddScoped<ICommissionService, CommissionService>();
         services.AddScoped<ITenantSecretService, TenantSecretService>();
         services.AddScoped<IPaymentProviderConfigService, PaymentProviderConfigService>();
         services.AddScoped<IPaymentProviderGateway, PaymentProviderGateway>();

Tiku.Infrastructure/Growth/CommissionService.cs

@@ -0,0 +1,348 @@
+using System.Globalization;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using Microsoft.EntityFrameworkCore;
+using Tiku.Application.Growth;
+using Tiku.Domain.Commerce;
+using Tiku.Domain.Common;
+using Tiku.Domain.Growth;
+using Tiku.Domain.Operations;
+using Tiku.Domain.Tenancy;
+using Tiku.Infrastructure.Persistence;
+
+namespace Tiku.Infrastructure.Growth;
+
+public sealed class CommissionService(TikuDbContext dbContext) : ICommissionService
+{
+    public async Task<CommissionSettingsItem> GetSettingsAsync(CommissionAdminActor actor, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        return ToSettingsItem(await GetSettingsCoreAsync(actor.TenantId, cancellationToken));
+    }
+
+    public async Task<CommissionSettingsItem> UpdateSettingsAsync(CommissionAdminActor actor, UpdateCommissionSettingsCommand command, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var settings = await GetSettingsCoreAsync(actor.TenantId, cancellationToken);
+        settings.DefaultRate = command.DefaultRate ?? settings.DefaultRate;
+        settings.MinSettlementCents = command.MinSettlementCents ?? settings.MinSettlementCents;
+        settings.SettlementCycle = ParseEnum(command.SettlementCycle, settings.SettlementCycle, "invalid_commission_cycle");
+        settings.Config = command.Config ?? settings.Config;
+        settings.UpdatedBy = actor.UserId;
+        await dbContext.SaveChangesAsync(cancellationToken);
+        return ToSettingsItem(settings);
+    }
+
+    public async Task<object> UpdateMemberRateAsync(CommissionAdminActor actor, UpdateMemberCommissionRateCommand command, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var member = await dbContext.TenantMemberships
+            .FirstOrDefaultAsync(item => item.TenantId == actor.TenantId && item.UserId == command.UserId, cancellationToken)
+            ?? throw new CommissionException("Commission member was not found.", "commission_member_not_found");
+        member.Permissions = JsonSerializer.SerializeToElement(new
+        {
+            commissionRate = command.CommissionRate,
+            commissionConfig = command.CommissionConfig
+        });
+        await dbContext.SaveChangesAsync(cancellationToken);
+        return new { member.UserId, commissionRate = command.CommissionRate, commissionConfig = command.CommissionConfig };
+    }
+
+    public async Task<CommissionSummaryItem> GetSummaryAsync(CommissionAdminActor actor, CommissionPeriodQuery query, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var rows = await BuildSourcesAsync(actor.TenantId, query, cancellationToken);
+        return new CommissionSummaryItem(
+            rows.Count,
+            rows.Select(item => item.StudentUserId).Where(id => id.HasValue).Distinct().Count(),
+            rows.Sum(item => item.GrossAmountCents),
+            rows.Sum(item => item.CommissionAmountCents));
+    }
+
+    public async Task<CommissionList<CommissionSourceItem>> GetOrdersAsync(CommissionAdminActor actor, CommissionPeriodQuery query, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var rows = await BuildSourcesAsync(actor.TenantId, query, cancellationToken);
+        return new CommissionList<CommissionSourceItem>(rows.Take(Math.Clamp(query.Limit ?? 100, 1, 500)).Select(ToSourceItem).ToArray());
+    }
+
+    public async Task<CommissionList<CommissionSettlementItemDto>> GetSettlementsAsync(CommissionAdminActor actor, CommissionSettlementQuery query, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var items = dbContext.CommissionSettlements.AsNoTracking().Where(item => item.TenantId == actor.TenantId);
+        if (query.ReferrerUserId.HasValue) items = items.Where(item => item.ReferrerUserId == query.ReferrerUserId.Value);
+        if (!string.IsNullOrWhiteSpace(query.Status)) items = items.Where(item => item.Status == ParseEnum(query.Status, CommissionSettlementStatus.Draft, "invalid_commission_status"));
+        var result = await items.OrderByDescending(item => item.CreatedAt).Take(Math.Clamp(query.Limit ?? 100, 1, 500)).ToArrayAsync(cancellationToken);
+        return new CommissionList<CommissionSettlementItemDto>(result.Select(ToSettlementItem).ToArray());
+    }
+
+    public async Task<CommissionExportItem> ExportSettlementAsync(CommissionAdminActor actor, Guid settlementId, string? format, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var settlement = await GetSettlementAsync(actor.TenantId, settlementId, cancellationToken);
+        var items = await dbContext.CommissionSettlementItems.AsNoTracking()
+            .Where(item => item.TenantId == actor.TenantId && item.SettlementId == settlementId)
+            .OrderBy(item => item.SourcePaidAt)
+            .ToArrayAsync(cancellationToken);
+        var resolvedFormat = string.Equals(format, "json", StringComparison.OrdinalIgnoreCase) ? "json" : "csv";
+        var content = resolvedFormat == "json"
+            ? JsonSerializer.Serialize(items.Select(ToSourceItem))
+            : BuildCsv(items);
+        var bytes = Encoding.UTF8.GetBytes(content);
+        var sha = Convert.ToHexString(SHA256.HashData(bytes)).ToLowerInvariant();
+        var filename = $"{settlement.SettlementNo}.{resolvedFormat}";
+        dbContext.CommissionSettlementExportEvents.Add(new CommissionSettlementExportEvent
+        {
+            TenantId = actor.TenantId,
+            SettlementId = settlementId,
+            ExportedBy = actor.UserId,
+            ExportFormat = resolvedFormat,
+            Filename = filename,
+            RowCount = items.Length,
+            ContentSha256 = sha,
+            Metadata = JsonSerializer.SerializeToElement(new { sizeBytes = bytes.Length })
+        });
+        await AddAuditAsync(actor, "commission.settlement.exported", "commission_settlements", settlementId, new { format = resolvedFormat, filename, rowCount = items.Length, sha }, cancellationToken);
+        await dbContext.SaveChangesAsync(cancellationToken);
+        return new CommissionExportItem(settlementId, filename, resolvedFormat, resolvedFormat == "json" ? "application/json" : "text/csv", items.Length, Convert.ToBase64String(bytes), sha, bytes.Length);
+    }
+
+    public async Task<CommissionSettlementItemDto> GenerateSettlementAsync(CommissionAdminActor actor, GenerateCommissionSettlementCommand command, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        if (command.EndDate < command.StartDate) throw new CommissionException("Commission period was invalid.", "invalid_commission_period");
+        var query = new CommissionPeriodQuery(command.StartDate, command.EndDate, command.ReferrerUserId, 5000);
+        var candidates = (await BuildSourcesAsync(actor.TenantId, query, cancellationToken)).Where(item => item.SettlementId is null).ToArray();
+        if (candidates.Length == 0) throw new CommissionException("No unsettled commission sources found.", "commission_no_unsettled_sources");
+        var settings = await GetSettingsCoreAsync(actor.TenantId, cancellationToken);
+        var amount = candidates.Sum(item => item.CommissionAmountCents);
+        if (amount < settings.MinSettlementCents) throw new CommissionException("Commission amount is below settlement minimum.", "commission_below_minimum");
+        var settlement = new CommissionSettlement
+        {
+            TenantId = actor.TenantId,
+            ReferrerUserId = command.ReferrerUserId,
+            GeneratedBy = actor.UserId,
+            SettlementNo = $"CS{DateTimeOffset.UtcNow:yyyyMMddHHmmss}{RandomNumberGenerator.GetInt32(1000, 9999)}",
+            Status = ParseEnum(command.Status, CommissionSettlementStatus.PendingReview, "invalid_commission_status"),
+            PeriodStart = command.StartDate,
+            PeriodEnd = command.EndDate,
+            SourceCount = candidates.Length,
+            PaidUserCount = candidates.Select(item => item.StudentUserId).Where(id => id.HasValue).Distinct().Count(),
+            GrossAmountCents = candidates.Sum(item => item.GrossAmountCents),
+            CommissionAmountCents = amount,
+            DefaultRate = settings.DefaultRate,
+            Remark = command.Remark,
+            Metadata = command.Metadata ?? JsonDefaults.Object()
+        };
+        dbContext.CommissionSettlements.Add(settlement);
+        foreach (var source in candidates)
+        {
+            dbContext.CommissionSettlementItems.Add(new CommissionSettlementItem
+            {
+                TenantId = actor.TenantId,
+                SettlementId = settlement.Id,
+                ReferrerUserId = source.ReferrerUserId,
+                StudentUserId = source.StudentUserId,
+                SourceType = source.SourceType,
+                SourceId = source.SourceId,
+                SourceNo = source.SourceNo,
+                SourcePaidAt = source.SourcePaidAt,
+                GrossAmountCents = source.GrossAmountCents,
+                CommissionRate = source.CommissionRate,
+                CommissionAmountCents = source.CommissionAmountCents,
+                RateSource = source.RateSource,
+                AttributionType = source.AttributionType,
+                Metadata = JsonSerializer.SerializeToElement(new { source = "commission_generate" })
+            });
+        }
+        await dbContext.SaveChangesAsync(cancellationToken);
+        return ToSettlementItem(settlement);
+    }
+
+    public async Task<CommissionSettlementItemDto> UpdateSettlementStatusAsync(CommissionAdminActor actor, UpdateCommissionSettlementStatusCommand command, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var item = await GetSettlementAsync(actor.TenantId, command.SettlementId, cancellationToken);
+        var status = ParseEnum(command.Status, CommissionSettlementStatus.Approved, "invalid_commission_status");
+        if (item.Status == CommissionSettlementStatus.Paid && status != CommissionSettlementStatus.Paid)
+            throw new CommissionException("Paid settlement cannot be reverted.", "commission_status_invalid");
+        item.Status = status;
+        item.Remark = command.ReviewNote ?? item.Remark;
+        item.Metadata = command.Metadata ?? item.Metadata;
+        if (status is CommissionSettlementStatus.Approved or CommissionSettlementStatus.Rejected or CommissionSettlementStatus.Cancelled)
+        {
+            item.ReviewedBy = actor.UserId;
+            item.ReviewedAt = DateTimeOffset.UtcNow;
+        }
+        if (status == CommissionSettlementStatus.Paid)
+        {
+            item.PaidBy = actor.UserId;
+            item.PaidAt = DateTimeOffset.UtcNow;
+            item.PaymentMethod = command.PaymentMethod ?? item.PaymentMethod;
+            item.PaymentAccount = command.PaymentAccount ?? item.PaymentAccount;
+        }
+        await dbContext.SaveChangesAsync(cancellationToken);
+        return ToSettlementItem(item);
+    }
+
+    public async Task<CommissionList<CommissionProofItem>> GetProofsAsync(CommissionAdminActor actor, Guid settlementId, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        await GetSettlementAsync(actor.TenantId, settlementId, cancellationToken);
+        var items = await dbContext.CommissionSettlementProofs.AsNoTracking()
+            .Where(item => item.TenantId == actor.TenantId && item.SettlementId == settlementId)
+            .OrderByDescending(item => item.CreatedAt)
+            .ToArrayAsync(cancellationToken);
+        return new CommissionList<CommissionProofItem>(items.Select(ToProofItem).ToArray());
+    }
+
+    public async Task<CommissionProofItem> CreateProofAsync(CommissionAdminActor actor, CreateCommissionProofCommand command, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var settlement = await GetSettlementAsync(actor.TenantId, command.SettlementId, cancellationToken);
+        var proof = new CommissionSettlementProof
+        {
+            TenantId = actor.TenantId,
+            SettlementId = command.SettlementId,
+            SubmittedBy = actor.UserId,
+            ProofType = ParseEnum(command.ProofType, CommissionProofType.Payment, "invalid_commission_proof_type"),
+            Status = CommissionProofStatus.Submitted,
+            Title = command.Title ?? $"{settlement.SettlementNo} 打款凭证",
+            Description = command.Description,
+            AssetId = command.AssetId,
+            ExternalUrl = command.ExternalUrl,
+            AmountCents = command.AmountCents ?? settlement.CommissionAmountCents,
+            PaymentMethod = command.PaymentMethod,
+            PaymentAccount = command.PaymentAccount,
+            PaidAt = command.PaidAt,
+            Metadata = command.Metadata ?? JsonDefaults.Object()
+        };
+        dbContext.CommissionSettlementProofs.Add(proof);
+        await dbContext.SaveChangesAsync(cancellationToken);
+        return ToProofItem(proof);
+    }
+
+    public async Task<CommissionProofItem> UpdateProofStatusAsync(CommissionAdminActor actor, UpdateCommissionProofStatusCommand command, CancellationToken cancellationToken = default)
+    {
+        await AssertAdminAsync(actor, cancellationToken);
+        var proof = await dbContext.CommissionSettlementProofs.FirstOrDefaultAsync(item => item.TenantId == actor.TenantId && item.Id == command.ProofId, cancellationToken)
+            ?? throw new CommissionException("Commission proof was not found.", "commission_proof_not_found");
+        var status = ParseEnum(command.Status, CommissionProofStatus.Approved, "invalid_commission_proof_status");
+        if (status == CommissionProofStatus.Submitted) throw new CommissionException("Cannot move proof back to submitted.", "invalid_commission_proof_status");
+        if (proof.Status is CommissionProofStatus.Approved or CommissionProofStatus.Rejected or CommissionProofStatus.Voided && proof.Status != status)
+            throw new CommissionException("Closed proof cannot change status.", "commission_proof_closed");
+        proof.Status = status;
+        proof.ReviewedBy = actor.UserId;
+        proof.ReviewedAt = DateTimeOffset.UtcNow;
+        proof.ReviewNote = command.ReviewNote ?? proof.ReviewNote;
+        proof.Metadata = command.Metadata ?? proof.Metadata;
+        await dbContext.SaveChangesAsync(cancellationToken);
+        return ToProofItem(proof);
+    }
+
+    private async Task<IReadOnlyCollection<SourceCandidate>> BuildSourcesAsync(Guid tenantId, CommissionPeriodQuery query, CancellationToken cancellationToken)
+    {
+        var today = DateOnly.FromDateTime(DateTime.UtcNow);
+        var startDate = query.StartDate ?? today.AddDays(-29);
+        var endDate = query.EndDate ?? today;
+        var start = new DateTimeOffset(startDate.ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc));
+        var end = new DateTimeOffset(endDate.AddDays(1).ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc));
+        var settings = await GetSettingsCoreAsync(tenantId, cancellationToken);
+        var existing = await dbContext.CommissionSettlementItems.AsNoTracking()
+            .Where(item => item.TenantId == tenantId)
+            .Select(item => new { item.SourceType, item.SourceId, item.SettlementId })
+            .ToArrayAsync(cancellationToken);
+        var result = new List<SourceCandidate>();
+        var orders = await (
+            from order in dbContext.Orders.AsNoTracking()
+            join lead in dbContext.ReferralLeads.AsNoTracking()
+                on new { order.TenantId, StudentUserId = order.UserId!.Value } equals new { lead.TenantId, lead.StudentUserId }
+            where order.TenantId == tenantId && order.UserId != null && lead.ReferrerUserId != null &&
+                  order.Status == OrderStatus.Paid && order.PaidAt >= start && order.PaidAt < end
+            select new { order, lead })
+            .ToArrayAsync(cancellationToken);
+        foreach (var row in orders)
+        {
+            if (query.ReferrerUserId.HasValue && row.lead.ReferrerUserId != query.ReferrerUserId) continue;
+            var rate = GetMemberRate(await GetMembershipPermissionsAsync(tenantId, row.lead.ReferrerUserId!.Value, cancellationToken)) ?? settings.DefaultRate;
+            var settled = existing.FirstOrDefault(item => item.SourceType == CommissionSourceType.Order && item.SourceId == row.order.Id)?.SettlementId;
+            result.Add(new SourceCandidate(CommissionSourceType.Order, row.order.Id, row.order.OrderNo, row.lead.ReferrerUserId.Value, row.order.UserId, row.order.AmountCents, rate, (int)Math.Round(row.order.AmountCents * rate), CommissionRateSource.Member, settled, row.order.PaidAt, "protected_lead"));
+        }
+        var codes = await (
+            from code in dbContext.ActivationCodes.AsNoTracking()
+            join batch in dbContext.CodeBatches.AsNoTracking()
+                on new { code.TenantId, BatchId = code.BatchId } equals new { batch.TenantId, BatchId = (Guid?)batch.Id } into batches
+            from batch in batches.DefaultIfEmpty()
+            where code.TenantId == tenantId && code.IsUsed && code.AgentUserId != null && code.UsedAt >= start && code.UsedAt < end
+            select new { code, batch })
+            .ToArrayAsync(cancellationToken);
+        foreach (var row in codes)
+        {
+            if (!row.code.AgentUserId.HasValue) continue;
+            var agentUserId = row.code.AgentUserId.Value;
+            if (query.ReferrerUserId.HasValue && agentUserId != query.ReferrerUserId) continue;
+            var rate = row.batch?.CommissionRate ?? GetMemberRate(await GetMembershipPermissionsAsync(tenantId, agentUserId, cancellationToken)) ?? settings.DefaultRate;
+            var sourceAmount = row.code.UnitPriceCents ?? row.batch?.DefaultUnitPriceCents ?? 0;
+            var settled = existing.FirstOrDefault(item => item.SourceType == CommissionSourceType.ActivationCode && item.SourceId == row.code.Id)?.SettlementId;
+            result.Add(new SourceCandidate(CommissionSourceType.ActivationCode, row.code.Id, row.code.Code, agentUserId, row.code.UsedBy, sourceAmount, rate, (int)Math.Round(sourceAmount * rate), row.batch?.CommissionRate is null ? CommissionRateSource.Member : CommissionRateSource.Batch, settled, row.code.UsedAt, "activation_code_agent"));
+        }
+        return result.OrderBy(item => item.SourcePaidAt).ToArray();
+    }
+
+    private async Task<JsonElement> GetMembershipPermissionsAsync(Guid tenantId, Guid userId, CancellationToken cancellationToken) =>
+        await dbContext.TenantMemberships.AsNoTracking().Where(item => item.TenantId == tenantId && item.UserId == userId).Select(item => item.Permissions).FirstOrDefaultAsync(cancellationToken);
+
+    private static decimal? GetMemberRate(JsonElement permissions) =>
+        permissions.ValueKind == JsonValueKind.Object && permissions.TryGetProperty("commissionRate", out var value) && value.ValueKind == JsonValueKind.Number && value.TryGetDecimal(out var rate) ? rate : null;
+
+    private async Task<TenantCommissionSetting> GetSettingsCoreAsync(Guid tenantId, CancellationToken cancellationToken)
+    {
+        var settings = await dbContext.TenantCommissionSettings.FirstOrDefaultAsync(item => item.TenantId == tenantId, cancellationToken);
+        if (settings is not null) return settings;
+        settings = new TenantCommissionSetting { TenantId = tenantId };
+        dbContext.TenantCommissionSettings.Add(settings);
+        return settings;
+    }
+
+    private async Task<CommissionSettlement> GetSettlementAsync(Guid tenantId, Guid settlementId, CancellationToken cancellationToken) =>
+        await dbContext.CommissionSettlements.FirstOrDefaultAsync(item => item.TenantId == tenantId && item.Id == settlementId, cancellationToken)
+        ?? throw new CommissionException("Commission settlement was not found.", "commission_settlement_not_found");
+
+    private async Task AssertAdminAsync(CommissionAdminActor actor, CancellationToken cancellationToken)
+    {
+        var ok = await dbContext.TenantMemberships.AnyAsync(item => item.TenantId == actor.TenantId && item.UserId == actor.UserId && item.Status == MembershipStatus.Active && (item.Role == TenantRole.PlatformAdmin || item.Role == TenantRole.TenantOwner || item.Role == TenantRole.TenantAdmin), cancellationToken);
+        if (!ok) throw new CommissionException("Commission admin access was denied.", "commission_access_denied");
+    }
+
+    private async Task AddAuditAsync(CommissionAdminActor actor, string action, string targetType, Guid targetId, object details, CancellationToken cancellationToken)
+    {
+        dbContext.AuditLogs.Add(new AuditLog { TenantId = actor.TenantId, ActorUserId = actor.UserId, Action = action, TargetType = targetType, TargetId = targetId.ToString(), Details = JsonSerializer.SerializeToElement(details) });
+        await Task.CompletedTask.WaitAsync(cancellationToken);
+    }
+
+    private static string BuildCsv(IEnumerable<CommissionSettlementItem> items)
+    {
+        var builder = new StringBuilder("sourceType,sourceNo,referrerUserId,studentUserId,grossAmountCents,commissionRate,commissionAmountCents\n");
+        foreach (var item in items)
+            builder.Append(CultureInfo.InvariantCulture, $"{item.SourceType},{item.SourceNo},{item.ReferrerUserId},{item.StudentUserId},{item.GrossAmountCents},{item.CommissionRate},{item.CommissionAmountCents}\n");
+        return builder.ToString();
+    }
+
+    private static CommissionSettingsItem ToSettingsItem(TenantCommissionSetting item) => new(item.DefaultRate, item.MinSettlementCents, item.SettlementCycle.ToString(), item.Config);
+    private static CommissionSourceItem ToSourceItem(SourceCandidate item) => new(item.SourceType.ToString(), item.SourceId, item.SourceNo, item.ReferrerUserId, item.StudentUserId, item.GrossAmountCents, item.CommissionRate, item.CommissionAmountCents, item.RateSource.ToString(), item.SettlementId);
+    private static CommissionSourceItem ToSourceItem(CommissionSettlementItem item) => new(item.SourceType.ToString(), item.SourceId, item.SourceNo, item.ReferrerUserId, item.StudentUserId, item.GrossAmountCents, item.CommissionRate, item.CommissionAmountCents, item.RateSource.ToString(), item.SettlementId);
+    private static CommissionSettlementItemDto ToSettlementItem(CommissionSettlement item) => new(item.Id, item.SettlementNo, item.ReferrerUserId, item.Status.ToString(), item.PeriodStart, item.PeriodEnd, item.SourceCount, item.PaidUserCount, item.GrossAmountCents, item.CommissionAmountCents, item.ReviewedAt, item.PaidAt);
+    private static CommissionProofItem ToProofItem(CommissionSettlementProof item) => new(item.Id, item.SettlementId, item.ProofType.ToString(), item.Status.ToString(), item.Title, item.AssetId, item.ExternalUrl, item.AmountCents, item.PaymentMethod, item.PaymentAccount, item.PaidAt, item.ReviewedAt);
+
+    private static TEnum ParseEnum<TEnum>(string? value, TEnum defaultValue, string errorCode) where TEnum : struct, Enum
+    {
+        if (string.IsNullOrWhiteSpace(value)) return defaultValue;
+        var normalized = value.Replace("_", string.Empty, StringComparison.Ordinal);
+        foreach (var enumValue in Enum.GetValues<TEnum>())
+            if (string.Equals(enumValue.ToString(), normalized, StringComparison.OrdinalIgnoreCase)) return enumValue;
+        throw new CommissionException("Commission enum value was invalid.", errorCode);
+    }
+
+    private sealed record SourceCandidate(CommissionSourceType SourceType, Guid SourceId, string? SourceNo, Guid ReferrerUserId, Guid? StudentUserId, int GrossAmountCents, decimal CommissionRate, int CommissionAmountCents, CommissionRateSource RateSource, Guid? SettlementId, DateTimeOffset? SourcePaidAt, string AttributionType);
+}

Tiku.Infrastructure/Persistence/Configurations/GrowthConfigurations.cs

@@ -1,5 +1,6 @@
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Metadata.Builders;
+using Tiku.Domain.Content;
 using Tiku.Domain.Growth;
 using Tiku.Domain.Identity;
 using Tiku.Domain.Tenancy;
@@ -257,3 +258,56 @@ internal sealed class CommissionSettlementItemConfiguration : IEntityTypeConfigu
         builder.HasOne<User>().WithMany().HasForeignKey(entity => entity.StudentUserId).OnDelete(DeleteBehavior.SetNull);
     }
 }
+
+internal sealed class CommissionSettlementProofConfiguration : IEntityTypeConfiguration<CommissionSettlementProof>
+{
+    public void Configure(EntityTypeBuilder<CommissionSettlementProof> builder)
+    {
+        builder.ConfigureTenantEntity("commission_settlement_proofs");
+        builder.ConfigureTimestamps();
+        builder.Property(entity => entity.ProofType).HasSnakeCaseEnum();
+        builder.Property(entity => entity.Status).HasSnakeCaseEnum();
+        builder.Property(entity => entity.Title).HasMaxLength(200);
+        builder.Property(entity => entity.ExternalUrl).HasMaxLength(2048);
+        builder.Property(entity => entity.PaymentMethod).HasMaxLength(100);
+        builder.Property(entity => entity.PaymentAccount).HasMaxLength(200);
+        builder.Property(entity => entity.Metadata).IsJson("{}");
+        builder.HasIndex(entity => new { entity.TenantId, entity.SettlementId, entity.Status, entity.CreatedAt });
+        builder.ToTable(table => table.HasCheckConstraint(
+            "ck_commission_settlement_proofs_amount",
+            "amount_cents is null or amount_cents >= 0"));
+        builder.HasOne<CommissionSettlement>().WithMany()
+            .HasForeignKey(entity => new { entity.TenantId, entity.SettlementId })
+            .HasPrincipalKey(entity => new { entity.TenantId, entity.Id })
+            .OnDelete(DeleteBehavior.Cascade);
+        builder.HasOne<ContentAsset>().WithMany()
+            .HasForeignKey(entity => new { entity.TenantId, entity.AssetId })
+            .HasPrincipalKey(entity => new { entity.TenantId, entity.Id })
+            .OnDelete(DeleteBehavior.SetNull);
+        builder.HasOne<User>().WithMany().HasForeignKey(entity => entity.SubmittedBy).OnDelete(DeleteBehavior.SetNull);
+        builder.HasOne<User>().WithMany().HasForeignKey(entity => entity.ReviewedBy).OnDelete(DeleteBehavior.SetNull);
+    }
+}
+
+internal sealed class CommissionSettlementExportEventConfiguration : IEntityTypeConfiguration<CommissionSettlementExportEvent>
+{
+    public void Configure(EntityTypeBuilder<CommissionSettlementExportEvent> builder)
+    {
+        builder.ToTable("commission_settlement_export_events");
+        builder.HasKey(entity => entity.Id);
+        builder.Property(entity => entity.Id).HasDefaultValueSql("gen_random_uuid()");
+        builder.Property(entity => entity.ExportFormat).HasMaxLength(20);
+        builder.Property(entity => entity.Filename).HasMaxLength(500);
+        builder.Property(entity => entity.ContentSha256).HasMaxLength(128);
+        builder.Property(entity => entity.Metadata).IsJson("{}");
+        builder.Property(entity => entity.CreatedAt).HasDefaultValueSql("now()");
+        builder.HasIndex(entity => new { entity.TenantId, entity.SettlementId, entity.CreatedAt });
+        builder.ToTable(table => table.HasCheckConstraint("ck_commission_export_events_rows", "row_count >= 0"));
+        builder.HasOne<Tenant>().WithMany().HasForeignKey(entity => entity.TenantId).OnDelete(DeleteBehavior.Cascade);
+        builder.HasOne<CommissionSettlement>().WithMany()
+            .HasForeignKey(entity => new { entity.TenantId, entity.SettlementId })
+            .HasPrincipalKey(entity => new { entity.TenantId, entity.Id })
+            .OnDelete(DeleteBehavior.Cascade);
+        builder.HasOne<User>().WithMany().HasForeignKey(entity => entity.ExportedBy).OnDelete(DeleteBehavior.SetNull);
+    }
+}

Tiku.Infrastructure/Persistence/Migrations/20260726122712_AddCommissionSettlementProofs.cs

@@ -0,0 +1,157 @@
+using System;
+using System.Text.Json;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Tiku.Infrastructure.Persistence.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddCommissionSettlementProofs : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.CreateTable(
+                name: "commission_settlement_export_events",
+                columns: table => new
+                {
+                    id = table.Column<Guid>(type: "uuid", nullable: false, defaultValueSql: "gen_random_uuid()"),
+                    tenant_id = table.Column<Guid>(type: "uuid", nullable: false),
+                    settlement_id = table.Column<Guid>(type: "uuid", nullable: false),
+                    exported_by = table.Column<Guid>(type: "uuid", nullable: true),
+                    export_format = table.Column<string>(type: "character varying(20)", maxLength: 20, nullable: false),
+                    filename = table.Column<string>(type: "character varying(500)", maxLength: 500, nullable: false),
+                    row_count = table.Column<int>(type: "integer", nullable: false),
+                    content_sha256 = table.Column<string>(type: "character varying(128)", maxLength: 128, nullable: true),
+                    metadata = table.Column<JsonElement>(type: "jsonb", nullable: false, defaultValueSql: "'{}'::jsonb"),
+                    created_at = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: false, defaultValueSql: "now()")
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("pk_commission_settlement_export_events", x => x.id);
+                    table.CheckConstraint("ck_commission_export_events_rows", "row_count >= 0");
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_export_events_commission_settlements_~",
+                        columns: x => new { x.tenant_id, x.settlement_id },
+                        principalTable: "commission_settlements",
+                        principalColumns: new[] { "tenant_id", "id" },
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_export_events_tenants_tenant_id",
+                        column: x => x.tenant_id,
+                        principalTable: "tenants",
+                        principalColumn: "id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_export_events_users_exported_by",
+                        column: x => x.exported_by,
+                        principalTable: "users",
+                        principalColumn: "id",
+                        onDelete: ReferentialAction.SetNull);
+                });
+
+            migrationBuilder.CreateTable(
+                name: "commission_settlement_proofs",
+                columns: table => new
+                {
+                    id = table.Column<Guid>(type: "uuid", nullable: false, defaultValueSql: "gen_random_uuid()"),
+                    settlement_id = table.Column<Guid>(type: "uuid", nullable: false),
+                    asset_id = table.Column<Guid>(type: "uuid", nullable: true),
+                    submitted_by = table.Column<Guid>(type: "uuid", nullable: true),
+                    reviewed_by = table.Column<Guid>(type: "uuid", nullable: true),
+                    proof_type = table.Column<string>(type: "character varying(32)", maxLength: 32, nullable: false),
+                    status = table.Column<string>(type: "character varying(32)", maxLength: 32, nullable: false),
+                    title = table.Column<string>(type: "character varying(200)", maxLength: 200, nullable: true),
+                    description = table.Column<string>(type: "text", nullable: true),
+                    external_url = table.Column<string>(type: "character varying(2048)", maxLength: 2048, nullable: true),
+                    amount_cents = table.Column<int>(type: "integer", nullable: true),
+                    payment_method = table.Column<string>(type: "character varying(100)", maxLength: 100, nullable: true),
+                    payment_account = table.Column<string>(type: "character varying(200)", maxLength: 200, nullable: true),
+                    paid_at = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: true),
+                    reviewed_at = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: true),
+                    review_note = table.Column<string>(type: "text", nullable: true),
+                    metadata = table.Column<JsonElement>(type: "jsonb", nullable: false, defaultValueSql: "'{}'::jsonb"),
+                    tenant_id = table.Column<Guid>(type: "uuid", nullable: false),
+                    created_at = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: false, defaultValueSql: "now()"),
+                    updated_at = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: false, defaultValueSql: "now()")
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("pk_commission_settlement_proofs", x => x.id);
+                    table.UniqueConstraint("ak_commission_settlement_proofs_tenant_id_id", x => new { x.tenant_id, x.id });
+                    table.CheckConstraint("ck_commission_settlement_proofs_amount", "amount_cents is null or amount_cents >= 0");
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_proofs_commission_settlements_tenant_~",
+                        columns: x => new { x.tenant_id, x.settlement_id },
+                        principalTable: "commission_settlements",
+                        principalColumns: new[] { "tenant_id", "id" },
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_proofs_content_assets_tenant_id_asset~",
+                        columns: x => new { x.tenant_id, x.asset_id },
+                        principalTable: "content_assets",
+                        principalColumns: new[] { "tenant_id", "id" },
+                        onDelete: ReferentialAction.SetNull);
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_proofs_tenants_tenant_id",
+                        column: x => x.tenant_id,
+                        principalTable: "tenants",
+                        principalColumn: "id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_proofs_users_reviewed_by",
+                        column: x => x.reviewed_by,
+                        principalTable: "users",
+                        principalColumn: "id",
+                        onDelete: ReferentialAction.SetNull);
+                    table.ForeignKey(
+                        name: "fk_commission_settlement_proofs_users_submitted_by",
+                        column: x => x.submitted_by,
+                        principalTable: "users",
+                        principalColumn: "id",
+                        onDelete: ReferentialAction.SetNull);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "ix_commission_settlement_export_events_exported_by",
+                table: "commission_settlement_export_events",
+                column: "exported_by");
+
+            migrationBuilder.CreateIndex(
+                name: "ix_commission_settlement_export_events_tenant_id_settlement_id~",
+                table: "commission_settlement_export_events",
+                columns: new[] { "tenant_id", "settlement_id", "created_at" });
+
+            migrationBuilder.CreateIndex(
+                name: "ix_commission_settlement_proofs_reviewed_by",
+                table: "commission_settlement_proofs",
+                column: "reviewed_by");
+
+            migrationBuilder.CreateIndex(
+                name: "ix_commission_settlement_proofs_submitted_by",
+                table: "commission_settlement_proofs",
+                column: "submitted_by");
+
+            migrationBuilder.CreateIndex(
+                name: "ix_commission_settlement_proofs_tenant_id_asset_id",
+                table: "commission_settlement_proofs",
+                columns: new[] { "tenant_id", "asset_id" });
+
+            migrationBuilder.CreateIndex(
+                name: "ix_commission_settlement_proofs_tenant_id_settlement_id_status~",
+                table: "commission_settlement_proofs",
+                columns: new[] { "tenant_id", "settlement_id", "status", "created_at" });
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "commission_settlement_export_events");
+
+            migrationBuilder.DropTable(
+                name: "commission_settlement_proofs");
+        }
+    }
+}

Tiku.Infrastructure/Persistence/Migrations/TikuDbContextModelSnapshot.cs

@@ -6635,6 +6635,74 @@ namespace Tiku.Infrastructure.Persistence.Migrations
                         });
                 });
 
+            modelBuilder.Entity("Tiku.Domain.Growth.CommissionSettlementExportEvent", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("uuid")
+                        .HasColumnName("id")
+                        .HasDefaultValueSql("gen_random_uuid()");
+
+                    b.Property<string>("ContentSha256")
+                        .HasMaxLength(128)
+                        .HasColumnType("character varying(128)")
+                        .HasColumnName("content_sha256");
+
+                    b.Property<DateTimeOffset>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasColumnName("created_at")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<string>("ExportFormat")
+                        .IsRequired()
+                        .HasMaxLength(20)
+                        .HasColumnType("character varying(20)")
+                        .HasColumnName("export_format");
+
+                    b.Property<Guid?>("ExportedBy")
+                        .HasColumnType("uuid")
+                        .HasColumnName("exported_by");
+
+                    b.Property<string>("Filename")
+                        .IsRequired()
+                        .HasMaxLength(500)
+                        .HasColumnType("character varying(500)")
+                        .HasColumnName("filename");
+
+                    b.Property<JsonElement>("Metadata")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("jsonb")
+                        .HasColumnName("metadata")
+                        .HasDefaultValueSql("'{}'::jsonb");
+
+                    b.Property<int>("RowCount")
+                        .HasColumnType("integer")
+                        .HasColumnName("row_count");
+
+                    b.Property<Guid>("SettlementId")
+                        .HasColumnType("uuid")
+                        .HasColumnName("settlement_id");
+
+                    b.Property<Guid>("TenantId")
+                        .HasColumnType("uuid")
+                        .HasColumnName("tenant_id");
+
+                    b.HasKey("Id")
+                        .HasName("pk_commission_settlement_export_events");
+
+                    b.HasIndex("ExportedBy")
+                        .HasDatabaseName("ix_commission_settlement_export_events_exported_by");
+
+                    b.HasIndex("TenantId", "SettlementId", "CreatedAt")
+                        .HasDatabaseName("ix_commission_settlement_export_events_tenant_id_settlement_id~");
+
+                    b.ToTable("commission_settlement_export_events", null, t =>
+                        {
+                            t.HasCheckConstraint("ck_commission_export_events_rows", "row_count >= 0");
+                        });
+                });
+
             modelBuilder.Entity("Tiku.Domain.Growth.CommissionSettlementItem", b =>
                 {
                     b.Property<Guid>("Id")
@@ -6751,6 +6819,128 @@ namespace Tiku.Infrastructure.Persistence.Migrations
                         });
                 });
 
+            modelBuilder.Entity("Tiku.Domain.Growth.CommissionSettlementProof", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("uuid")
+                        .HasColumnName("id")
+                        .HasDefaultValueSql("gen_random_uuid()");
+
+                    b.Property<int?>("AmountCents")
+                        .HasColumnType("integer")
+                        .HasColumnName("amount_cents");
+
+                    b.Property<Guid?>("AssetId")
+                        .HasColumnType("uuid")
+                        .HasColumnName("asset_id");
+
+                    b.Property<DateTimeOffset>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasColumnName("created_at")
+                        .HasDefaultValueSql("now()");
+
+                    b.Property<string>("Description")
+                        .HasColumnType("text")
+                        .HasColumnName("description");
+
+                    b.Property<string>("ExternalUrl")
+                        .HasMaxLength(2048)
+                        .HasColumnType("character varying(2048)")
+                        .HasColumnName("external_url");
+
+                    b.Property<JsonElement>("Metadata")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("jsonb")
+                        .HasColumnName("metadata")
+                        .HasDefaultValueSql("'{}'::jsonb");
+
+                    b.Property<DateTimeOffset?>("PaidAt")
+                        .HasColumnType("timestamp with time zone")
+                        .HasColumnName("paid_at");
+
+                    b.Property<string>("PaymentAccount")
+                        .HasMaxLength(200)
+                        .HasColumnType("character varying(200)")
+                        .HasColumnName("payment_account");
+
+                    b.Property<string>("PaymentMethod")
+                        .HasMaxLength(100)
+                        .HasColumnType("character varying(100)")
+                        .HasColumnName("payment_method");
+
+                    b.Property<string>("ProofType")
+                        .IsRequired()
+                        .HasMaxLength(32)
+                        .HasColumnType("character varying(32)")
+                        .HasColumnName("proof_type");
+
+                    b.Property<string>("ReviewNote")
+                        .HasColumnType("text")
+                        .HasColumnName("review_note");
+
+                    b.Property<DateTimeOffset?>("ReviewedAt")
+                        .HasColumnType("timestamp with time zone")
+                        .HasColumnName("reviewed_at");
+
+                    b.Property<Guid?>("ReviewedBy")
+                        .HasColumnType("uuid")
+                        .HasColumnName("reviewed_by");
+
+                    b.Property<Guid>("SettlementId")
+                        .HasColumnType("uuid")
+                        .HasColumnName("settlement_id");
+
+                    b.Property<string>("Status")
+                        .IsRequired()
+                        .HasMaxLength(32)
+                        .HasColumnType("character varying(32)")
+                        .HasColumnName("status");
+
+                    b.Property<Guid?>("SubmittedBy")
+                        .HasColumnType("uuid")
+                        .HasColumnName("submitted_by");
+
+                    b.Property<Guid>("TenantId")
+                        .HasColumnType("uuid")
+                        .HasColumnName("tenant_id");
+
+                    b.Property<string>("Title")
+                        .HasMaxLength(200)
+                        .HasColumnType("character varying(200)")
+                        .HasColumnName("title");
+
+                    b.Property<DateTimeOffset>("UpdatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasColumnName("updated_at")
+                        .HasDefaultValueSql("now()");
+
+                    b.HasKey("Id")
+                        .HasName("pk_commission_settlement_proofs");
+
+                    b.HasAlternateKey("TenantId", "Id")
+                        .HasName("ak_commission_settlement_proofs_tenant_id_id");
+
+                    b.HasIndex("ReviewedBy")
+                        .HasDatabaseName("ix_commission_settlement_proofs_reviewed_by");
+
+                    b.HasIndex("SubmittedBy")
+                        .HasDatabaseName("ix_commission_settlement_proofs_submitted_by");
+
+                    b.HasIndex("TenantId", "AssetId")
+                        .HasDatabaseName("ix_commission_settlement_proofs_tenant_id_asset_id");
+
+                    b.HasIndex("TenantId", "SettlementId", "Status", "CreatedAt")
+                        .HasDatabaseName("ix_commission_settlement_proofs_tenant_id_settlement_id_status~");
+
+                    b.ToTable("commission_settlement_proofs", null, t =>
+                        {
+                            t.HasCheckConstraint("ck_commission_settlement_proofs_amount", "amount_cents is null or amount_cents >= 0");
+                        });
+                });
+
             modelBuilder.Entity("Tiku.Domain.Growth.CrmConfig", b =>
                 {
                     b.Property<Guid>("Id")
@@ -14747,6 +14937,30 @@ namespace Tiku.Infrastructure.Persistence.Migrations
                         .HasConstraintName("fk_commission_settlements_tenants_tenant_id");
                 });
 
+            modelBuilder.Entity("Tiku.Domain.Growth.CommissionSettlementExportEvent", b =>
+                {
+                    b.HasOne("Tiku.Domain.Identity.User", null)
+                        .WithMany()
+                        .HasForeignKey("ExportedBy")
+                        .OnDelete(DeleteBehavior.SetNull)
+                        .HasConstraintName("fk_commission_settlement_export_events_users_exported_by");
+
+                    b.HasOne("Tiku.Domain.Tenancy.Tenant", null)
+                        .WithMany()
+                        .HasForeignKey("TenantId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired()
+                        .HasConstraintName("fk_commission_settlement_export_events_tenants_tenant_id");
+
+                    b.HasOne("Tiku.Domain.Growth.CommissionSettlement", null)
+                        .WithMany()
+                        .HasForeignKey("TenantId", "SettlementId")
+                        .HasPrincipalKey("TenantId", "Id")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired()
+                        .HasConstraintName("fk_commission_settlement_export_events_commission_settlements_~");
+                });
+
             modelBuilder.Entity("Tiku.Domain.Growth.CommissionSettlementItem", b =>
                 {
                     b.HasOne("Tiku.Domain.Identity.User", null)
@@ -14777,6 +14991,43 @@ namespace Tiku.Infrastructure.Persistence.Migrations
                         .HasConstraintName("fk_commission_settlement_items_commission_settlements_tenant_i~");
                 });
 
+            modelBuilder.Entity("Tiku.Domain.Growth.CommissionSettlementProof", b =>
+                {
+                    b.HasOne("Tiku.Domain.Identity.User", null)
+                        .WithMany()
+                        .HasForeignKey("ReviewedBy")
+                        .OnDelete(DeleteBehavior.SetNull)
+                        .HasConstraintName("fk_commission_settlement_proofs_users_reviewed_by");
+
+                    b.HasOne("Tiku.Domain.Identity.User", null)
+                        .WithMany()
+                        .HasForeignKey("SubmittedBy")
+                        .OnDelete(DeleteBehavior.SetNull)
+                        .HasConstraintName("fk_commission_settlement_proofs_users_submitted_by");
+
+                    b.HasOne("Tiku.Domain.Tenancy.Tenant", null)
+                        .WithMany()
+                        .HasForeignKey("TenantId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired()
+                        .HasConstraintName("fk_commission_settlement_proofs_tenants_tenant_id");
+
+                    b.HasOne("Tiku.Domain.Content.ContentAsset", null)
+                        .WithMany()
+                        .HasForeignKey("TenantId", "AssetId")
+                        .HasPrincipalKey("TenantId", "Id")
+                        .OnDelete(DeleteBehavior.SetNull)
+                        .HasConstraintName("fk_commission_settlement_proofs_content_assets_tenant_id_asset~");
+
+                    b.HasOne("Tiku.Domain.Growth.CommissionSettlement", null)
+                        .WithMany()
+                        .HasForeignKey("TenantId", "SettlementId")
+                        .HasPrincipalKey("TenantId", "Id")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired()
+                        .HasConstraintName("fk_commission_settlement_proofs_commission_settlements_tenant_~");
+                });
+
             modelBuilder.Entity("Tiku.Domain.Growth.CrmConfig", b =>
                 {
                     b.HasOne("Tiku.Domain.Tenancy.Tenant", null)

Tiku.Infrastructure/Persistence/TikuDbContext.cs

@@ -124,6 +124,8 @@ public sealed class TikuDbContext(DbContextOptions<TikuDbContext> options) : DbC
     public DbSet<TenantCommissionSetting> TenantCommissionSettings => Set<TenantCommissionSetting>();
     public DbSet<CommissionSettlement> CommissionSettlements => Set<CommissionSettlement>();
     public DbSet<CommissionSettlementItem> CommissionSettlementItems => Set<CommissionSettlementItem>();
+    public DbSet<CommissionSettlementProof> CommissionSettlementProofs => Set<CommissionSettlementProof>();
+    public DbSet<CommissionSettlementExportEvent> CommissionSettlementExportEvents => Set<CommissionSettlementExportEvent>();
     public DbSet<Banner> Banners => Set<Banner>();
     public DbSet<Faq> Faqs => Set<Faq>();
     public DbSet<Announcement> Announcements => Set<Announcement>();

Tiku.IntegrationTests/Api/CommissionEndpointTests.cs

@@ -0,0 +1,179 @@
+using System.Net;
+using System.Net.Http.Json;
+using System.Text.Json;
+using Tiku.Api.Contracts;
+using Tiku.Application.Auth;
+using Tiku.Application.Growth;
+using Tiku.Domain.Commerce;
+using Tiku.Domain.Growth;
+using Tiku.Domain.Identity;
+using Tiku.Domain.Tenancy;
+using Tiku.Infrastructure.Auth;
+
+namespace Tiku.IntegrationTests.Api;
+
+public sealed class CommissionEndpointTests
+{
+    [Fact]
+    public async Task Anonymous_commission_request_returns_401()
+    {
+        await using var factory = new ApiTestFactory();
+        using var client = factory.CreateClient();
+
+        var response = await client.GetAsync("/api/commission/settings");
+
+        Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
+    }
+
+    [Fact]
+    public async Task Admin_can_generate_export_and_proof_commission_settlement()
+    {
+        await using var factory = new ApiTestFactory();
+        var seed = await SeedCommissionAsync(factory);
+        using var client = factory.CreateClient();
+        await LoginAsync(client, seed.Admin);
+
+        var settings = await client.PutAsJsonAsync(
+            "/api/commission/settings",
+            new UpdateCommissionSettingsDto { DefaultRate = 0.2m, MinSettlementCents = 1, SettlementCycle = "monthly" });
+        var sources = await client.GetAsync($"/api/commission/orders?referrerUserId={seed.Referrer.UserId}&startDate=2026-07-01&endDate=2026-07-31");
+        var summary = await client.GetAsync($"/api/commission/summary?referrerUserId={seed.Referrer.UserId}&startDate=2026-07-01&endDate=2026-07-31");
+        var generate = await client.PostAsJsonAsync(
+            "/api/commission/settlements/generate",
+            new GenerateCommissionSettlementDto
+            {
+                ReferrerUserId = seed.Referrer.UserId,
+                StartDate = "2026-07-01",
+                EndDate = "2026-07-31",
+                Status = "pending_review"
+            });
+        var settlement = await generate.Content.ReadFromJsonAsync<CommissionSettlementItemDto>();
+        var duplicate = await client.PostAsJsonAsync(
+            "/api/commission/settlements/generate",
+            new GenerateCommissionSettlementDto
+            {
+                ReferrerUserId = seed.Referrer.UserId,
+                StartDate = "2026-07-01",
+                EndDate = "2026-07-31"
+            });
+        var status = await client.PostAsJsonAsync(
+            "/api/commission/settlements/status",
+            new UpdateCommissionSettlementStatusDto
+            {
+                SettlementId = settlement!.Id,
+                Status = "paid",
+                PaymentMethod = "bank",
+                PaymentAccount = "****1234"
+            });
+        var proof = await client.PostAsJsonAsync(
+            "/api/commission/settlements/proofs",
+            new CreateCommissionProofDto
+            {
+                SettlementId = settlement.Id,
+                ProofType = "payment",
+                ExternalUrl = "https://example.test/proof.png"
+            });
+        var proofItem = await proof.Content.ReadFromJsonAsync<CommissionProofItem>();
+        var proofStatus = await client.PostAsJsonAsync(
+            "/api/commission/settlements/proofs/status",
+            new UpdateCommissionProofStatusDto { ProofId = proofItem!.Id, Status = "approved" });
+        var export = await client.GetAsync($"/api/commission/settlements/export?settlementId={settlement.Id}&format=csv");
+        var exportItem = await export.Content.ReadFromJsonAsync<CommissionExportItem>();
+
+        Assert.Equal(HttpStatusCode.OK, settings.StatusCode);
+        Assert.Equal(HttpStatusCode.OK, sources.StatusCode);
+        Assert.Equal(HttpStatusCode.OK, summary.StatusCode);
+        Assert.Equal(HttpStatusCode.OK, generate.StatusCode);
+        Assert.Equal(2, settlement.SourceCount);
+        Assert.Equal(3000, settlement.CommissionAmountCents);
+        Assert.Equal(HttpStatusCode.Conflict, duplicate.StatusCode);
+        Assert.Equal(HttpStatusCode.OK, status.StatusCode);
+        Assert.Equal(HttpStatusCode.OK, proof.StatusCode);
+        Assert.Equal(HttpStatusCode.OK, proofStatus.StatusCode);
+        Assert.Equal(HttpStatusCode.OK, export.StatusCode);
+        Assert.Equal("csv", exportItem!.Format);
+        Assert.False(string.IsNullOrWhiteSpace(exportItem.Sha256));
+    }
+
+    private static async Task<CommissionSeed> SeedCommissionAsync(ApiTestFactory factory)
+    {
+        var tenantId = Guid.NewGuid();
+        var admin = new LoginSeed(tenantId, Guid.NewGuid(), "13800003001");
+        var referrer = new LoginSeed(tenantId, Guid.NewGuid(), "13800003002");
+        var student = new LoginSeed(tenantId, Guid.NewGuid(), "13800003003");
+        var paidAt = new DateTimeOffset(2026, 7, 10, 12, 0, 0, TimeSpan.Zero);
+        var batchId = Guid.NewGuid();
+        await factory.SeedAsync(
+            new Tenant { Id = tenantId, Slug = tenantId.ToString("N"), Name = "Commission Tenant" },
+            User(admin, "tenant_admin"),
+            User(referrer, "sales"),
+            User(student, "student"),
+            Identity(admin),
+            Identity(referrer),
+            Identity(student),
+            Membership(admin, TenantRole.TenantAdmin),
+            Membership(referrer, TenantRole.Sales),
+            Membership(student, TenantRole.Student),
+            new ReferralLead
+            {
+                TenantId = tenantId,
+                StudentUserId = student.UserId,
+                ReferrerUserId = referrer.UserId,
+                RefCode = "COMM2026",
+                Source = "manual"
+            },
+            new Order
+            {
+                TenantId = tenantId,
+                UserId = student.UserId,
+                OrderNo = "C202607100001",
+                Status = OrderStatus.Paid,
+                AmountCents = 10000,
+                ProductType = "svip",
+                ProductName = "SVIP",
+                PaidAt = paidAt
+            },
+            new CodeBatch
+            {
+                Id = batchId,
+                TenantId = tenantId,
+                Name = "代理码",
+                TotalCount = 1,
+                DefaultUnitPriceCents = 5000,
+                CommissionRate = 0.2m
+            },
+            new ActivationCode
+            {
+                TenantId = tenantId,
+                BatchId = batchId,
+                AgentUserId = referrer.UserId,
+                UsedBy = student.UserId,
+                Code = "CODE2026",
+                IsUsed = true,
+                UnitPriceCents = 5000,
+                UsedAt = paidAt
+            });
+        return new CommissionSeed(tenantId, admin, referrer, student);
+    }
+
+    private static User User(LoginSeed seed, string role) => new() { Id = seed.UserId, Phone = seed.Phone, Name = role, PrimaryRole = role };
+    private static TenantMembership Membership(LoginSeed seed, TenantRole role) => new() { TenantId = seed.TenantId, UserId = seed.UserId, Role = role, Status = MembershipStatus.Active };
+    private static UserIdentity Identity(LoginSeed seed) => new() { UserId = seed.UserId, Provider = "password", ProviderSubject = seed.Phone, Phone = seed.Phone, SecretPayload = CreateSecretPayload(new PasswordHasher().Hash("passw0rd!")) };
+
+    private static async Task LoginAsync(HttpClient client, LoginSeed seed)
+    {
+        var loginResponse = await client.PostAsJsonAsync("/api/auth/login/password", new PasswordLoginDto { TenantId = seed.TenantId, Phone = seed.Phone, Password = "passw0rd!" });
+        loginResponse.EnsureSuccessStatusCode();
+        using var loginJson = await JsonDocument.ParseAsync(await loginResponse.Content.ReadAsStreamAsync());
+        client.DefaultRequestHeaders.Authorization = new("Bearer", loginJson.RootElement.GetProperty("tokens").GetProperty("accessToken").GetString());
+    }
+
+    private static JsonElement CreateSecretPayload(string passwordHash)
+    {
+        using var document = JsonDocument.Parse($$"""{"passwordHash":{{JsonSerializer.Serialize(passwordHash)}}}""");
+        return document.RootElement.Clone();
+    }
+
+    private sealed record LoginSeed(Guid TenantId, Guid UserId, string Phone);
+    private sealed record CommissionSeed(Guid TenantId, LoginSeed Admin, LoginSeed Referrer, LoginSeed Student);
+}

Tiku.IntegrationTests/PersistenceModelTests.cs

@@ -31,7 +31,7 @@ public sealed class PersistenceModelTests
             .Select(entity => entity.GetTableName())
             .ToHashSet(StringComparer.Ordinal);
 
-        Assert.Equal(131, tableNames.Count);
+        Assert.Equal(133, tableNames.Count);
         Assert.Contains("tenants", tableNames);
         Assert.Contains("tenant_settings", tableNames);
         Assert.Contains("content_entries", tableNames);
@@ -116,6 +116,8 @@ public sealed class PersistenceModelTests
         Assert.Contains("tenant_commission_settings", tableNames);
         Assert.Contains("commission_settlements", tableNames);
         Assert.Contains("commission_settlement_items", tableNames);
+        Assert.Contains("commission_settlement_proofs", tableNames);
+        Assert.Contains("commission_settlement_export_events", tableNames);
         Assert.Contains("banners", tableNames);
         Assert.Contains("faqs", tableNames);
         Assert.Contains("announcements", tableNames);
@@ -684,6 +686,8 @@ public sealed class PersistenceModelTests
     [InlineData(typeof(TenantCommissionSetting), nameof(TenantCommissionSetting.Config), "'{}'::jsonb")]
     [InlineData(typeof(CommissionSettlement), nameof(CommissionSettlement.Metadata), "'{}'::jsonb")]
     [InlineData(typeof(CommissionSettlementItem), nameof(CommissionSettlementItem.Metadata), "'{}'::jsonb")]
+    [InlineData(typeof(CommissionSettlementProof), nameof(CommissionSettlementProof.Metadata), "'{}'::jsonb")]
+    [InlineData(typeof(CommissionSettlementExportEvent), nameof(CommissionSettlementExportEvent.Metadata), "'{}'::jsonb")]
     public void Growth_json_properties_are_mapped_to_jsonb(
         Type entityType,
         string propertyName,