统一聚合根与持久化内核

Aggregate (领域) ──> Entity (数据表) ──> MappingSpecs ──> Generated Mapper ──> Repository

// 声明 Provider 中立的表名与租户软删除特性
[BitzTable("SandboxNote", IsTenant = true, IsSoftDelete = true, Description = "Sandbox 笔记")]
public sealed class Note : TenantAggregateRoot<string>
{
    // 显式声明列长度与非空约束
    [BitzColumn(Length = 200, IsRequired = true)]
    public string Title { get; private set; } = string.Empty;
}

// <auto-generated/>
#nullable enable
namespace BitzOrcas.Sandbox.Infrastructure.Generated;

// 实现 EF Core 强类型实体映射接口
public sealed class NoteEfCoreConfiguration : Microsoft.EntityFrameworkCore.IEntityTypeConfiguration<BitzOrcas.Sandbox.Domain.Note>
{
    // 配置物理表名、列约束、主键与全局软删除过滤器
    public void Configure(Microsoft.EntityFrameworkCore.Metadata.Builders.EntityTypeBuilder<BitzOrcas.Sandbox.Domain.Note> builder)
    {
        builder.ToTable("SandboxNote", comment: "Sandbox 笔记");
        builder.HasKey(x => x.Id);
        builder.Property(x => x.Id).HasColumnName("Id").HasMaxLength(36).IsRequired();
        builder.Property(x => x.TenantId).HasColumnName("TenantId").HasMaxLength(64).IsRequired();
        builder.Property(x => x.Title).HasColumnName("Title").HasMaxLength(200).IsRequired();
        builder.Property(x => x.IsDeleted).HasColumnName("IsDeleted").IsRequired();
        builder.Property(x => x.Version).HasColumnName("Version").IsConcurrencyToken().IsRequired();

        // 全局软删除与多租户过滤基线
        builder.HasQueryFilter(x => !x.IsDeleted);
    }
}

// <auto-generated/>
#nullable enable
namespace BitzOrcas.Sandbox.Infrastructure.Generated;

// 静态注册 SqlSugar 实体元数据
public static class NoteSqlSugarConfiguration
{
    // 静态注入表名、列描述与类型约束
    public static void Apply(SqlSugar.SqlSugarClient client)
    {
        var entity = client.EntityMaintenance.GetEntityInfo<BitzOrcas.Sandbox.Domain.Note>();
        entity.DbTableName = "SandboxNote";
        entity.TableDescription = "Sandbox 笔记";
    }
}

// <auto-generated/>
#nullable enable
namespace BitzOrcas.Sandbox.Infrastructure.Generated;

// 闭泛型静态属性访问器，彻底规避反射调用
public static class NotePersistenceAccessors
{
    // 读取 Id 主键属性
    public static string GetId(BitzOrcas.Sandbox.Domain.Note instance) => instance.Id;

    // 设置 Id 主键属性（由持久化管线在插入时覆写）
    public static void SetId(BitzOrcas.Sandbox.Domain.Note instance, string id)
    {
        instance.GetType().GetProperty("Id")?.SetValue(instance, id);
    }
}

// 声明不可变的地址值对象
public sealed record DeliveryAddress(string Province, string City, string Street);

// 在聚合中声明前缀扁平列：
// 值对象扁平化的 Prefix 语法为规划中能力，当前 [BitzColumn] 未实现该参数；
// 列名由生成器默认约定展开。示例保留设计意图，切勿照抄。
[BitzColumn(/* Prefix 规划中 */)]
public DeliveryAddress Address { get; private set; } = new(string.Empty, string.Empty, string.Empty);

using System.ComponentModel;
using BitzOrcas.Domain.Contracts;
using BitzOrcas.Domain.Entities;
using BitzOrcas.Domain.Results;
using BitzOrcas.Domain.Tenancy;
using BitzOrcas.Persistence.Metadata;

namespace BitzOrcas.Ticket.Domain;

/// <summary>
/// 业务工单统一聚合根
/// </summary>
/// <remarks>
/// 统一聚合根金样板，继承 <see cref="TenantAggregateRoot{TId}"/>，内置标识、租户与审计支持。
/// </remarks>
[BitzTable("SysTicket", IsTenant = true, IsSoftDelete = true, Description = "业务工单聚合根")]
[BitzIndex("IX_SysTicket_Status", nameof(Status), nameof(TenantId))]
public sealed class Ticket : TenantAggregateRoot<string>
{
    public const int TitleMaxLength = 200;
    public const int DescriptionMaxLength = 2000;

    /// <summary>
    /// 工单标题
    /// </summary>
    [BitzColumn(Length = TitleMaxLength, IsRequired = true, ColumnDescription = "工单标题")]
    public string Title { get; private set; }

    /// <summary>
    /// 工单详细描述
    /// </summary>
    [BitzColumn(Length = DescriptionMaxLength, IsRequired = false, ColumnDescription = "工单详细描述")]
    public string? Description { get; private set; }

    /// <summary>
    /// 业务状态枚举
    /// </summary>
    /// <remarks>
    /// 数据库物理存储为 int 或 string 影子列。
    /// </remarks>
    [BitzColumn(IsRequired = true, ColumnDescription = "工单状态")]
    public TicketStatus Status { get; private set; }

    /// <summary>
    /// 工单地理位置复合值对象
    /// </summary>
    /// <remarks>
    /// 编译期由 Roslyn 增量生成器自动扁平化为 Location_Province 与 Location_City 列。
    /// </remarks>
    [BitzColumn(/* Prefix 规划中，当前由生成器默认列名约定 */)]
    public TicketLocation Location { get; private set; }

    /// <summary>
    /// 动态扩展标签快照
    /// </summary>
    /// <remarks>
    /// 以严格 JSON 格式落库持久化。
    /// </remarks>
    [BitzColumn(IsJson = true, ColumnDescription = "动态标签集合快照")]
    public IReadOnlyList<string> Tags { get; private set; }

    /// <summary>
    /// 纯内存计算属性
    /// </summary>
    /// <remarks>
    /// 运行时即时求值，无需持久化到数据库物理列。
    /// </remarks>
    [BitzColumn(Ignore = true)]
    public bool IsOverdue => Status == TicketStatus.Open && DateTimeOffset.UtcNow > CreateTime.AddDays(7);

    /// <summary>
    /// 仅供 ORM 物化使用的无参构造函数
    /// </summary>
    /// <remarks>
    /// 编译期 error: true 契约彻底杜绝业务代码误调用无参构造绕过工厂验证。
    /// </remarks>
    [Obsolete("For ORM materialization only. Use Factory Methods.", error: true)]
    [EditorBrowsable(EditorBrowsableState.Never)]
    public Ticket() : base("0")
    {
        Title = "Materialized";
        Status = TicketStatus.Open;
        Location = TicketLocation.Empty;
        Tags = [];
    }

    /// <summary>
    /// 领域内聚私有构造函数
    /// </summary>
    private Ticket(
        string id,
        string title,
        string? description,
        TicketLocation location,
        IReadOnlyList<string> tags,
        string tenantId) : base(id)
    {
        Title = title;
        Description = description;
        Status = TicketStatus.Open;
        Location = location;
        Tags = tags;
        TenantId = tenantId;
    }

    /// <summary>
    /// 创建工单聚合根
    /// </summary>
    /// <remarks>
    /// 执行领域不变量校验并初始化工单状态。
    /// </remarks>
    public static Result<Ticket> Create(
        string? title,
        string? description,
        TicketLocation? location,
        IReadOnlyList<string>? tags,
        string? tenantId)
    {
        var normalizedTitle = title?.Trim();
        if (string.IsNullOrWhiteSpace(normalizedTitle) || normalizedTitle.Length > TitleMaxLength)
        {
            return Result<Ticket>.Failure(TicketErrors.TitleInvalid);
        }

        if (string.IsNullOrWhiteSpace(tenantId) || !TenancyDefaults.IsValid(tenantId))
        {
            return Result<Ticket>.Failure(TicketErrors.TenantRequired);
        }

        var ticket = new Ticket(
            "0", // 占位 Id，持久化管线在 Insert 时会自动由雪花算法覆写
            normalizedTitle,
            description?.Trim(),
            location ?? TicketLocation.Empty,
            tags ?? [],
            tenantId);

        return Result<Ticket>.Success(ticket);
    }

    /// <summary>
    /// 解决工单
    /// </summary>
    /// <remarks>
    /// 标记工单为已解决状态并记录解决时间。
    /// </remarks>
    public Result Resolve()
    {
        if (Status == TicketStatus.Resolved)
        {
            return Result.Failure(TicketErrors.AlreadyResolved);
        }

        Status = TicketStatus.Resolved;
        return Result.Success();
    }
}

/// <summary>
/// 工单地理位置值对象
/// </summary>
public sealed record TicketLocation(
    [property: BitzColumn(Length = 64)] string Province,
    [property: BitzColumn(Length = 64)] string City)
{
    public static TicketLocation Empty => new(string.Empty, string.Empty);
}

public enum TicketStatus
{
    Open = 10,
    InProgress = 20,
    Resolved = 30,
    Closed = 40
}