@polymorphism-tech/morph-spec 4.7.0 → 4.7.2

package/.morph/framework/standards/architecture/ddd/entities.md

@@ -0,0 +1,99 @@
+# Architecture Standard: DDD Entities
+
+## Overview
+Entities have identity — two entities with the same ID are the same, regardless of their attribute values.
+
+## Entity Base Class
+```csharp
+public abstract class Entity
+{
+    public Guid Id { get; protected set; } = Guid.NewGuid();
+    public DateTime CreatedAt { get; protected set; } = DateTime.UtcNow;
+    public DateTime? UpdatedAt { get; protected set; }
+    public bool IsDeleted { get; private set; }
+    public DateTime? DeletedAt { get; private set; }
+
+    // Identity equality (not attribute equality)
+    public override bool Equals(object? obj)
+        => obj is Entity other && Id == other.Id;
+
+    public override int GetHashCode() => Id.GetHashCode();
+    public static bool operator ==(Entity? a, Entity? b) => a?.Equals(b) ?? b is null;
+    public static bool operator !=(Entity? a, Entity? b) => !(a == b);
+
+    // Soft delete support
+    public void SoftDelete()
+    {
+        IsDeleted = true;
+        DeletedAt = DateTime.UtcNow;
+    }
+}
+```
+
+## Entity Lifecycle
+```csharp
+// Entities are created through factory methods (never bare constructors from outside the aggregate)
+public class OrderItem : Entity
+{
+    private OrderItem() { } // Private for EF Core
+
+    internal static OrderItem Create(Guid productId, string productName, decimal price, int quantity)
+    {
+        if (price <= 0) throw new DomainException("Price must be positive");
+        if (quantity <= 0) throw new DomainException("Quantity must be positive");
+
+        return new OrderItem
+        {
+            ProductId = productId,
+            ProductName = productName,
+            UnitPrice = price,
+            Quantity = quantity
+        };
+    }
+
+    public Guid ProductId { get; private set; }
+    public string ProductName { get; private set; } = string.Empty;
+    public decimal UnitPrice { get; private set; }
+    public int Quantity { get; private set; }
+    public decimal Subtotal => UnitPrice * Quantity;
+
+    internal void IncreaseQuantity(int additionalQuantity)
+    {
+        if (additionalQuantity <= 0) throw new DomainException("Quantity must be positive");
+        Quantity += additionalQuantity;
+        UpdatedAt = DateTime.UtcNow;
+    }
+}
+```
+
+## EF Core Mapping
+
+### Required Conventions
+```csharp
+builder.HasKey(e => e.Id);
+builder.Property(e => e.CreatedAt).IsRequired();
+
+// Soft delete filter (apply globally)
+builder.HasQueryFilter(e => !e.IsDeleted);
+
+// All string properties: max length
+builder.Property(e => e.Name)
+    .IsRequired()
+    .HasMaxLength(200);
+```
+
+### Inheritance (TPH by default)
+```csharp
+// Table Per Hierarchy (single table with discriminator)
+builder.HasDiscriminator<string>("Type")
+    .HasValue<ProductOrder>("product")
+    .HasValue<ServiceOrder>("service");
+```
+
+## Entity vs Value Object Decision
+| Use Entity When | Use Value Object When |
+|----------------|----------------------|
+| Has lifecycle (created, updated, deleted) | Immutable by definition |
+| Identity matters (two objects with same data are different) | Equality by value |
+| Needs to be tracked in a repository | Owned by an entity (no separate table) |
+| Examples: User, Order, Product | Examples: Money, Address, DateRange |

package/.morph/framework/standards/architecture/ddd/ubiquitous-language.md

@@ -0,0 +1,58 @@
+# DDD Ubiquitous Language
+
+> **Scope:** universal
+> **Layer:** 2
+> **Keywords:** ubiquitous-language, ddd, glossary, domain-terms, naming
+
+Linguagem Ubíqua é o vocabulário compartilhado entre devs e domínio de negócio.
+Elimina ambiguidade e alinha código com a linguagem do negócio.
+
+---
+
+## Formato do Glossário
+
+```markdown
+# Ubiquitous Language: {Feature/BoundedContext}
+
+## Termos do Domínio
+
+| Termo | Definição | Contexto | Código |
+|-------|-----------|----------|--------|
+| Subscription | Contrato ativo de uso por um tenant | Billing | `Subscription` (AggregateRoot) |
+| PlanTier | Nível do plano (Free/Pro/Enterprise) | Billing | `PlanTier` (ValueObject) |
+| Activation | Ato de ativar Subscription após pagamento | Billing | `Subscription.Activate()` |
+
+## Estados e Transições
+
+| Estado | Descrição | Transições |
+|--------|-----------|-----------|
+| Draft | Criada, aguardando pagamento | → Active |
+| Active | Paga e em uso | → Suspended, Cancelled |
+| Cancelled | Encerrada definitivamente | (terminal) |
+
+## Invariants em Linguagem Natural
+
+- "Uma Subscription só pode ser Cancelada se estiver Active ou Suspended"
+- "Um Tenant não pode ter duas Subscriptions Active simultaneamente"
+```
+
+---
+
+## Regras de Nomenclatura
+
+1. Use termos do glossário como nomes de classe/método
+2. Eventos no passado: `OrderConfirmed`, não `OrderConfirmation`
+3. Commands no imperativo: `CreateOrder`, não `OrderCreation`
+4. Value Objects no substantivo: `Money`, `Email`
+5. Métodos do Aggregate espelham ações do negócio: `order.Confirm()`, não `order.SetStatusToConfirmed()`
+
+---
+
+## Quando Gerar
+
+- **Nível 2:** Seção inline no `spec.md` (Aggregate Blueprint)
+- **Nível 3:** Arquivo separado `1-design/ubiquitous-language.md` por BC
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/architecture/ddd/value-objects.md

@@ -0,0 +1,124 @@
+# Architecture Standard: DDD Value Objects
+
+## Overview
+Value objects have no identity — equality is based on their attribute values. They are immutable.
+
+## Value Object Base Class
+```csharp
+public abstract class ValueObject
+{
+    protected abstract IEnumerable<object?> GetEqualityComponents();
+
+    public override bool Equals(object? obj)
+    {
+        if (obj is null || obj.GetType() != GetType()) return false;
+        return GetEqualityComponents().SequenceEqual(((ValueObject)obj).GetEqualityComponents());
+    }
+
+    public override int GetHashCode()
+        => GetEqualityComponents().Aggregate(0, (hash, c) => HashCode.Combine(hash, c?.GetHashCode() ?? 0));
+
+    public static bool operator ==(ValueObject? a, ValueObject? b) => a?.Equals(b) ?? b is null;
+    public static bool operator !=(ValueObject? a, ValueObject? b) => !(a == b);
+}
+```
+
+## Money Value Object
+```csharp
+public sealed class Money : ValueObject
+{
+    public decimal Amount { get; }
+    public string Currency { get; }
+
+    private Money(decimal amount, string currency)
+    {
+        Amount = amount;
+        Currency = currency.ToUpper();
+    }
+
+    public static Money Of(decimal amount, string currency = "BRL")
+    {
+        if (amount < 0) throw new DomainException("Money amount cannot be negative");
+        if (string.IsNullOrWhiteSpace(currency)) throw new DomainException("Currency required");
+        return new Money(amount, currency);
+    }
+
+    public Money Add(Money other)
+    {
+        if (Currency != other.Currency)
+            throw new DomainException($"Cannot add {Currency} and {other.Currency}");
+        return new Money(Amount + other.Amount, Currency);
+    }
+
+    public Money Multiply(decimal factor)
+        => new(Amount * factor, Currency);
+
+    public override string ToString() => $"{Amount:F2} {Currency}";
+
+    protected override IEnumerable<object?> GetEqualityComponents()
+    {
+        yield return Amount;
+        yield return Currency;
+    }
+}
+```
+
+## Address Value Object
+```csharp
+public sealed class Address : ValueObject
+{
+    public string Street { get; }
+    public string City { get; }
+    public string State { get; }
+    public string ZipCode { get; }
+    public string Country { get; }
+
+    public Address(string street, string city, string state, string zipCode, string country)
+    {
+        Street = street ?? throw new DomainException("Street required");
+        City = city ?? throw new DomainException("City required");
+        State = state ?? throw new DomainException("State required");
+        ZipCode = zipCode ?? throw new DomainException("ZipCode required");
+        Country = country ?? throw new DomainException("Country required");
+    }
+
+    protected override IEnumerable<object?> GetEqualityComponents()
+    {
+        yield return Street;
+        yield return City;
+        yield return State;
+        yield return ZipCode;
+        yield return Country;
+    }
+}
+```
+
+## EF Core Configuration (Owned Types)
+```csharp
+public class OrderConfiguration : IEntityTypeConfiguration<Order>
+{
+    public void Configure(EntityTypeBuilder<Order> builder)
+    {
+        // Embedded in same table (no separate table)
+        builder.OwnsOne(o => o.ShippingAddress, addr =>
+        {
+            addr.Property(a => a.Street).HasMaxLength(200).IsRequired();
+            addr.Property(a => a.City).HasMaxLength(100).IsRequired();
+            addr.Property(a => a.ZipCode).HasMaxLength(20).IsRequired();
+        });
+
+        // Money: stored as separate Amount + Currency columns
+        builder.OwnsOne(o => o.Total, money =>
+        {
+            money.Property(m => m.Amount).HasColumnType("decimal(18,2)").IsRequired();
+            money.Property(m => m.Currency).HasMaxLength(3).IsRequired();
+        });
+    }
+}
+```
+
+## Rules
+- Value objects are always immutable — no setters, return new instance from methods
+- Use `record` types only when they don't need to inherit from `ValueObject` base class
+- Never use value objects as EF Core entity (no `Id` column)
+- Never create value objects with invalid state — validate in constructor/factory