‫Domain-Driven Design (DDD)؛ بخش ششم: Aggregates

• دامنه: فروش ساده
• Aggregate Root: Order
• Entity درون Aggregate است: OrderLine

• مجموع مبلغ سفارش باید از مجموع اقلام محاسبه شود؛ دستی تغییر نمی‌کند.
• همه اقلام باید هم‌ارز با ارز سفارش باشند.
• مقدار هر قلم باید بیشتر از 0 باشد.
• OrderLine فقط از طریق Order اضافه/حذف می‌شود.

// ضدالگو: مدل دامنه
public class Order
{
    public Guid Id { get; set; }
    public string Currency { get; set; } = default!; // "USD", "EUR", ...
    public decimal Total { get; set; }               // ضدالگو: set عمومی

    public List<OrderLine> Lines { get; set; } = new(); // ضدالگو: set عمومی
}

public class OrderLine
{
    public Guid Id { get; set; }
    public Guid OrderId { get; set; }
    public string Sku { get; set; } = default!;
    public int Quantity { get; set; }            // ضدالگو: set عمومی
    public decimal UnitPrice { get; set; }       // ضدالگو: set عمومی
    public string Currency { get; set; } = default!; // می‌تواند با Order فرق کند!
}

// ضدالگو: EF Core DbContext
public class SalesDbContext : DbContext
{
    public DbSet<Order> Orders => Set<Order>();
    public DbSet<OrderLine> OrderLines => Set<OrderLine>(); // ضدالگو

    public SalesDbContext(DbContextOptions<SalesDbContext> options) : base(options) { }
}

// جای بد ماجرا
var line = await db.OrderLines.FirstAsync();
line.Quantity = -5;                  // نقض قاعده 3
line.Currency = "EUR";              // نقض قاعده 2
await db.SaveChangesAsync();         // سفارش الان "نامعتبر" است

var order = await db.Orders.Include(o => o.Lines).FirstAsync();
order.Total += 100;                  // نقض قاعده 1؛ محاسبه بیرون از Aggregate
await db.SaveChangesAsync();

• فقط Order به‌عنوان Aggregate Root در DbContext ثبت می‌شود.
• OrderLine از خارج قابل ساخت/تغییر نیست؛ فقط از طریق رفتارهای Order.
• محاسبه Total مشتق‌شده (Derived) است و set عمومی ندارد.

// مدل دامنه صحیح با کپسوله‌سازی
public class Order
{
    private readonly List<OrderLine> _lines = new();

    // برای EF Core
    private Order() { }

    public Order(string currency)
    {
        Currency = currency ?? throw new ArgumentNullException(nameof(currency));
    }

    public Guid Id { get; private set; }
    public string Currency { get; private set; }

    // مقدار مشتق‌شده؛ هر بار از اقلام محاسبه می‌شود
    public decimal Total => _lines.Sum(l => l.Subtotal);

    // فقط خواندنی برای بیرون
    public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

    // رفتارهای دروازه‌بان
    public OrderLine AddLine(string sku, int quantity, Money unitPrice)
    {
        if (quantity <= 0) throw new DomainException("Quantity must be > 0");
        if (unitPrice.Currency != Currency) throw new DomainException("Currency mismatch");

        var line = OrderLine.Create(Id, sku, quantity, unitPrice);
        _lines.Add(line);
        return line;
    }

    public void RemoveLine(Guid lineId)
    {
        var line = _lines.FirstOrDefault(l => l.Id == lineId)
                   ?? throw new DomainException("Line not found");
        _lines.Remove(line);
    }

    public void ChangeLineQuantity(Guid lineId, int newQuantity)
    {
        var line = _lines.FirstOrDefault(l => l.Id == lineId)
                   ?? throw new DomainException("Line not found");
        line.ChangeQuantity(newQuantity); // خود Line هم نگهبان قاعده خودش است
    }
}

public class OrderLine
{
    // برای EF Core
    private OrderLine() { }

    private OrderLine(Guid orderId, string sku, int quantity, Money unitPrice)
    {
        Id = Guid.NewGuid();
        OrderId = orderId;
        Sku = sku ?? throw new ArgumentNullException(nameof(sku));
        UnitPrice = unitPrice ?? throw new ArgumentNullException(nameof(unitPrice));
        ChangeQuantity(quantity); // اعتبارسنجی متمرکز
    }

    public static OrderLine Create(Guid orderId, string sku, int quantity, Money unitPrice)
        => new(orderId, sku, quantity, unitPrice);

    public Guid Id { get; private set; }
    public Guid OrderId { get; private set; }
    public string Sku { get; private set; } = default!;
    public int Quantity { get; private set; }
    public Money UnitPrice { get; private set; } = default!;

    public decimal Subtotal => Quantity * UnitPrice.Amount;

    public void ChangeQuantity(int newQuantity)
    {
        if (newQuantity <= 0) throw new DomainException("Quantity must be > 0");
        Quantity = newQuantity;
    }
}

// Value Object برای پول
public class Money
{
    // برای EF Core
    private Money() { }

    public Money(decimal amount, string currency)
    {
        if (amount < 0) throw new DomainException("Amount cannot be negative");
        Amount = amount;
        Currency = currency ?? throw new ArgumentNullException(nameof(currency));
    }

    public decimal Amount { get; private set; }
    public string Currency { get; private set; }
}

public class DomainException : Exception
{
    public DomainException(string message) : base(message) { }
}

• تنها Order در DbSet قرار می‌گیرد.
• OrderLine به‌عنوان Entity داخلی با Backing Field نگاشت می‌شود.
• Money به‌صورت Owned Type نگاشت می‌شود.

public class SalesDbContext : DbContext
{
    public DbSet<Order> Orders => Set<Order>(); // فقط Aggregate Root

    public SalesDbContext(DbContextOptions<SalesDbContext> options) : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfiguration(new OrderConfig());
        modelBuilder.ApplyConfiguration(new OrderLineConfig());
        modelBuilder.Owned<Money>(); // یا داخل Config مربوطه
    }
}

public class OrderConfig : IEntityTypeConfiguration<Order>
{
    public void Configure(EntityTypeBuilder<Order> b)
    {
        b.HasKey(o => o.Id);
        b.Property(o => o.Currency).IsRequired().HasMaxLength(3);

        // Lines: Backing Field
        b.Navigation("Lines").Metadata.SetField("_lines"); // برای EF < 7 ممکن است متفاوت باشد
        b.Metadata.FindNavigation(nameof(Order.Lines))!
            .SetPropertyAccessMode(PropertyAccessMode.Field);

        b.HasMany<OrderLine>("_lines")
         .WithOne()
         .HasForeignKey(l => l.OrderId)
         .OnDelete(DeleteBehavior.Cascade);
    }
}

public class OrderLineConfig : IEntityTypeConfiguration<OrderLine>
{
    public void Configure(EntityTypeBuilder<OrderLine> b)
    {
        b.HasKey(l => l.Id);
        b.Property(l => l.Sku).IsRequired().HasMaxLength(64);
        b.OwnsOne(l => l.UnitPrice, mb =>
        {
            mb.Property(m => m.Amount).HasColumnType("decimal(18,2)").IsRequired();
            mb.Property(m => m.Currency).HasMaxLength(3).IsRequired();
        });

        // جلوگیری از دستکاری مستقیم
        b.Property(l => l.Quantity).UsePropertyAccessMode(PropertyAccessMode.FieldDuringConstruction);
    }
}

نکته: اگر از EF Core 7/8 استفاده می‌کنید، UsePropertyAccessMode و تنظیم BackingField را دقیقاً مطابق نسخه‌تان اعمال کنید. ایده‌ی اصلی: کلکسیون فقط از طریق میدان خصوصی مدیریت شود.

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default);
    Task AddAsync(Order order, CancellationToken ct = default);
    Task SaveChangesAsync(CancellationToken ct = default);
}

public class EfOrderRepository : IOrderRepository
{
    private readonly SalesDbContext _db;
    public EfOrderRepository(SalesDbContext db) => _db = db;

    public Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default) =>
        _db.Orders
           .Include(o => o.Lines)
           .FirstOrDefaultAsync(o => o.Id == id, ct);

    public async Task AddAsync(Order order, CancellationToken ct = default)
        => await _db.Orders.AddAsync(order, ct);

    public Task SaveChangesAsync(CancellationToken ct = default)
        => _db.SaveChangesAsync(ct);
}

// سرویس کاربردی: مرز تراکنش
public class PlaceOrderService
{
    private readonly IOrderRepository _repo;
    public PlaceOrderService(IOrderRepository repo) => _repo = repo;

    public async Task<Guid> PlaceAsync(string currency, (string sku,int qty, decimal price)[] lines)
    {
        var order = new Order(currency);
        foreach (var l in lines)
        {
            var money = new Money(l.price, currency);
            order.AddLine(l.sku, l.qty, money);
        }
        await _repo.AddAsync(order);
        await _repo.SaveChangesAsync();
        return order.Id;
    }
}

[Fact]
public void ChangingLineQuantity_Directly_ShouldNotBePossible()
{
    var order = new Order("USD");
    var line = order.AddLine("ABC-1", 1, new Money(10, "USD"));

    // بیرون از Aggregate هیچ set عمومی نداریم
    // line.Quantity = -5; // کامپایل نمی‌شود

    Assert.Throws<DomainException>(() => order.ChangeLineQuantity(line.Id, 0));
}

• DbSet برای Entityهای داخلی Aggregate
• public set روی مجموعۀ اقلام یا ویژگی‌های حساس
• محاسبۀ «Total» به‌صورت دستی در لایه‌های بیرونی

• رفتارهای غنی روی Aggregate (AddLine, ChangeLineQuantity)
• Value Objectها برای مفاهیم اتمیک (Money)
• نگاشت EF به Backing Field و Owned Types

• پاسخ: Read Model جداگانه (CQRS Read) که از View/Projection تغذیه شود؛ نه «باز کردن» Aggregate.

• پاسخ: «یک Read Model اختصاصی یا Materialized View می‌سازم؛ دامنه را نمی‌شکنم.»

• پاسخ: «باز هم مرز Aggregate را نمی‌شکنیم؛ Loadهای ضروری را صریحاً با Include یا Specification می‌آوریم.»

• تنها Aggregate Root در DbSet است.
• مجموعه‌های داخلی با Backing Field نگاشت شده‌اند.
• رفتارها (Methods) مالک اعمال روی داده‌اند؛ نه لایه‌های بیرونی.
• Invariantها در یک‌جا (Aggregate/Entity) enforce شده‌اند.
• مقادیر مشتق‌شده set عمومی ندارند.
• گزارش‌گیری جدا از مدل نوشتاری (Read Model/CQRS).

• Validationهای UI/API (مانند Required/Regex) محترم‌اند ولی کافی نیستند.
• Invariantها باید در قلب دامنه (Aggregate/Entity) برقرار شوند؛ جایی که EF هم دورش نمی‌تواند بزند.

public enum PostStatus { Draft, Published, Archived }

public class Comment
{
    public Guid Id { get; private set; }
    public string Author { get; private set; }
    public string Text { get; private set; }

    // سازنده برای EF Core
    private Comment() { }

    public Comment(string author, string text)
    {
        // ... اعتبارسنجی‌های اولیه
        Author = author;
        Text = text;
    }
}

public class BlogPost
{
    public Guid Id { get; private set; }
    public string Title { get; private set; }
    public PostStatus Status { get; private set; }

    // و دوباره همان حفره امنیتی آشنا!
    public List<Comment> Comments { get; private set; } = new();

    public BlogPost(string title)
    {
        Id = Guid.NewGuid();
        Title = title;
        Status = PostStatus.Draft; // هر پست به صورت پیش‌نویس شروع می‌شود
    }

    public void Publish()
    {
        if (Status == PostStatus.Draft)
        {
            Status = PostStatus.Published;
        }
    }
}

// کد در لایه Application یا Service
var post = new BlogPost("مقدمه‌ای بر DDD");

// پست هنوز در وضعیت پیش‌نویس (Draft) است.
// Console.WriteLine(post.Status); // خروجی: Draft

// نقض مستقیم قانون کسب‌وکار!
// ما Aggregate Root را نادیده گرفتیم و مستقیماً نظر اضافه کردیم.
var sneakyComment = new Comment("یک کاربر ناشناس", "این پست عالیه!");
post.Comments.Add(sneakyComment);

// فاجعه! یک پست پیش‌نویس حالا نظر دارد.
// این داده نامعتبر می‌تواند در پایگاه داده ذخیره شود.
Console.WriteLine(post.Comments.Count); // خروجی: 1

• نمایش نظرات نامرتبط: ممکن است در بخشی از UI، به اشتباه نظرات یک پست پیش‌نویس نمایش داده شود و باعث سردرگمی کاربران شود.
• از دست رفتن منطق کسب‌وکار: شاید در آینده بخواهیم هنگام افزودن نظر، یک ایمیل اطلاع‌رسانی برای نویسنده پست ارسال کنیم. اگر منطق افزودن نظر در سراسر برنامه پخش شده باشد، اعمال این تغییر جدید بسیار دشوار و خطازا خواهد بود.
• داده‌های ناسازگار: تصور کنید پستی حذف می‌شود اما نظرات آن به دلیل دستکاری مستقیم، در سیستم باقی می‌مانند و به یک پست یتیم تبدیل می‌شوند.

public class BlogPost
{
    public Guid Id { get; private set; }
    public string Title { get; private set; }
    public PostStatus Status { get; private set; }

    // 1. لیست داخلی را کاملاً خصوصی و غیرقابل دسترس می‌کنیم.
    private readonly List<Comment> _comments = new();

    // 2. یک نمای امن و فقط-خواندنی از نظرات را به بیرون ارائه می‌دهیم.
    public IReadOnlyCollection<Comment> Comments => _comments.AsReadOnly();

    public BlogPost(string title)
    {
        Id = Guid.NewGuid();
        Title = title;
        Status = PostStatus.Draft;
    }

    public void Publish()
    {
        if (Status != PostStatus.Draft)
        {
            throw new InvalidOperationException("فقط یک پیش‌نویس را می‌توان منتشر کرد.");
        }
        Status = PostStatus.Published;
    }

    // 3. تنها راه افزودن نظر، این متد است که از قوانین ما محافظت می‌کند.
    public void AddComment(string author, string text)
    {
        // اینجا دروازه و نگهبان ماست!
        if (Status != PostStatus.Published)
        {
            throw new InvalidOperationException("امکان ثبت نظر برای پستی که منتشر نشده، وجود ندارد.");
        }

        var newComment = new Comment(author, text);
        _comments.Add(newComment);
        
        // اینجا می‌توان کارهای دیگری هم انجام داد:
        // مثلاً ارسال ایمیل به نویسنده
    }
}

• کپسوله‌سازی کامل:List به _comments خصوصی تبدیل شد. دیگر هیچ راهی برای دسترسی مستقیم به آن از بیرون وجود ندارد.
• نمای فقط-خواندنی: با ارائه IReadOnlyCollection، به دیگران اجازه می‌دهیم نظرات را ببینند، اما هرگز نمی‌توانند لیست را دستکاری کنند.
• متد کسب‌وکاری: متد AddComment تنها راه مجاز برای افزودن نظر است. این متد قبل از انجام هر کاری، وضعیت پست را بررسی می‌کند. او نگهبان وفادار قانون کسب‌وکار ماست.

[TestMethod]
public void Cannot_Add_Comment_To_A_Draft_Post()
{
    // Arrange
    // از نسخه نفوذناپذیر استفاده می‌کنیم
    var post = new BlogPost("پست تستی"); 
    // پست به صورت پیش‌فرض در وضعیت Draft است.

    // Act & Assert
    // انتظار داریم که تلاش برای افزودن نظر، با یک استثنا مواجه شود.
    Assert.ThrowsException<InvalidOperationException>(() => 
    {
        post.AddComment("کاربر مشتاق", "منتظر انتشار این پست هستم!");
    });
}

• در نسخه نشت‌دار: این تست شکست می‌خورد (Fail)، چون هیچ مکانیزمی جلوی افزودن نظر به پیش‌نویس را نمی‌گرفت و هیچ استثنایی پرتاب نمی‌شد.
• در نسخه نفوذناپذیر: این تست با افتخار پاس می‌شود (Pass)، زیرا متد AddComment به درستی وضعیت پست را بررسی کرده و InvalidOperationException را پرتاب می‌کند. این دقیقاً همان رفتار مورد انتظار ماست.

• Aggregate یک نگهبان هویت و قوانین است. هویت BlogPost به وضعیت آن (پیش‌نویس، منتشر شده) گره خورده و قوانین آن (مثل شرایط نظردهی) باید توسط خودش محافظت شوند.
• متدهای Aggregate باید داستان کسب‌وکار را تعریف کنند. نام‌هایی مانند Publish یا AddComment بسیار معنادارتر از SetStatus یا GetComments().Add() هستند. آن‌ها قصد و نیت را بیان می‌کنند.
• کپسوله‌سازی، فقط پنهان کردن داده‌ها نیست؛ بلکه حفاظت از اعتبار و سلامت آنهاست.

• یک کلاس BlogPostService که منطق بررسی وضعیت پست قبل از افزودن نظر را در خود دارد. (این منطق باید داخل BlogPost باشد!)
• ارائه کلکسیون‌های داخلی با public List یا public ICollection.
• متدهای عمومی که فقط داده‌ها را تنظیم می‌کنند بدون اینکه هیچ قانون کسب‌وکاری را اجرا کنند (Anemic Domain Model).

• کلاس BlogPost خودش می‌تواند تصمیم بگیرد که آیا نظری پذیرفته می‌شود یا خیر.
• عدم وجود set های عمومی برای پراپرتی‌هایی که منطق کسب‌وکاری پیچیده‌ای دارند (مثل Status یا Comments).
• هر متد عمومی، Aggregate را در یک وضعیت کاملاً معتبر رها می‌کند.

• [ ] آیا این مجموعه‌ای از کلاس‌ها یک واحد مفهومی و تراکنشی را تشکیل می‌دهند؟ (پس یک Aggregate هستند)
• [ ] آیا دروازه اصلی (Aggregate Root) را به درستی شناسایی کرده‌ام؟
• [ ] آیا تمام راه‌های نفوذ به داخل Aggregate را بسته‌ام و فقط از طریق متدهای کنترل‌شده اجازه تعامل می‌دهم?
• [ ] آیا متدهای من، بیانگر زبان کسب‌وکار (Ubiquitous Language) هستند؟
• [ ] آیا قوانین پایدار (Invariants) در داخل خود Aggregate محافظت می‌شوند، حتی اگر یک توسعه‌دهنده دیگر سعی در نقض آن‌ها داشته باشد؟