@polymorphism-tech/morph-spec 4.6.0 → 4.7.0

package/docs/examples/order-management/spec.md

@@ -0,0 +1,162 @@
+# Feature Specification: Order Management
+
+| Field | Value |
+|-------|-------|
+| **ID** | order-management |
+| **Status** | Approved |
+| **Created** | 2026-02-23 |
+| **Stack** | .NET 10 / Blazor Server / EF Core |
+| **Complexity** | Medium |
+| **Agents** | Core: All / Specialists: domain-architect, ef-modeler, event-architect |
+
+---
+
+## Overview
+
+**Problem:** Usuários precisam criar e gerenciar pedidos com rastreamento de status.
+
+**Solution:** Aggregate Order com factory method, invariants de estado, e Domain Events para notificações.
+
+**Success Criteria:**
+- [ ] Order CRUD com validações de negócio
+- [ ] Status tracking com transições controladas
+- [ ] Notificação ao confirmar pedido
+
+---
+
+## Requirements
+
+**Functional:**
+FR001: Criar pedido com mínimo 1 item | FR002: Confirmar pedido (Draft → Confirmed) | FR003: Cancelar pedido (Draft/Confirmed → Cancelled) | FR004: Calcular total automaticamente
+
+**Non-Functional:**
+NFR001: Performance - operações < 200ms | NFR002: Consistência - invariants garantidas em toda operação
+
+---
+
+## User Stories
+
+### US001: Criar Pedido
+**As** usuário autenticado **I want** criar um pedido com itens **so that** posso comprar produtos
+
+**Acceptance Criteria:**
+1. Pedido criado com status Draft
+2. Total calculado na criação
+
+**Edge Cases:** Lista de itens vazia → erro 400
+
+---
+
+## Technical Design
+
+### Stack
+| Component | Technology |
+|-----------|------------|
+| Frontend | Blazor Server |
+| Backend | .NET 10 / C# 14 |
+| Database | Azure SQL / EF Core |
+
+### Data Model
+
+#### Order
+| Column | Type | Constraints |
+|--------|------|-------------|
+| Id | Guid | PK |
+| UserId | Guid | FK (reference by ID — cross-aggregate) |
+| Status | OrderStatus | Enum |
+| CreatedAt | datetime2 | Default: GETUTCDATE() |
+| UpdatedAt | datetime2 | Nullable |
+
+#### OrderItem (owned entity)
+| Column | Type | Constraints |
+|--------|------|-------------|
+| Id | Guid | PK |
+| OrderId | Guid | FK |
+| ProductId | Guid | Reference by ID |
+| Quantity | int | > 0 |
+| UnitPrice | decimal(18,2) | > 0 |
+
+### Contracts
+> **Ref:** `framework/templates/code/dotnet/contracts/contracts-level2.cs`
+
+---
+
+## Domain Complexity
+
+**Nível:** 2 — Business Logic
+
+**Justificativa:** Order tem estados com transições controladas (Draft → Confirmed → Cancelled),
+invariants de negócio (não confirmar sem itens, não adicionar itens a pedido confirmado),
+cálculo derivado (Total), e outros módulos precisam reagir (NotificationService ao OrderConfirmed).
+
+**Padrões Aplicados:**
+- AggregateRoot com factory method estático
+- Value Objects: Money (UnitPrice, Total)
+- Domain Events: OrderCreatedEvent, OrderConfirmedEvent, OrderCancelledEvent
+- CQRS com MediatR
+
+**Padrões Omitidos:**
+- Bounded Contexts — sistema single-domain, desnecessário
+
+---
+
+## Aggregate Blueprint (Nível 2+ apenas)
+
+### Aggregate Root: Order
+
+**Invariants:**
+- Order só pode ser Confirmado se Status == Draft E tiver pelo menos 1 item
+- Order Confirmado não pode receber mais itens (AddItem lança DomainException)
+- Order Cancelado não pode ser reativado (estado terminal)
+
+**Estados e Transições:**
+```
+{Draft} → Confirm() → {Confirmed}
+{Draft} → Cancel()  → {Cancelled}
+{Confirmed} → Cancel() → {Cancelled}
+```
+
+**Domain Events:**
+- `OrderCreatedEvent` — publicado ao criar (Create factory method)
+- `OrderConfirmedEvent` — publicado ao confirmar (Confirm method)
+- `OrderCancelledEvent` — publicado ao cancelar (Cancel method)
+
+**Value Objects:**
+- `Money` — UnitPrice e Total não são decimals simples: têm validação (> 0) e operações (Add, Multiply)
+
+**Referências Cross-Aggregate (por ID):**
+- `UserId: Guid` — nunca `User User { get; }`
+- `ProductId: Guid` em OrderItem — nunca `Product Product { get; }`
+
+### Linguagem Ubíqua
+
+| Termo | Definição | Código |
+|-------|-----------|--------|
+| Order | Pedido de compra de um usuário | `Order` (AggregateRoot) |
+| Draft | Pedido criado, ainda editável | `OrderStatus.Draft` |
+| Confirmed | Pedido submetido, não editável | `OrderStatus.Confirmed` |
+| Cancelled | Pedido cancelado, estado terminal | `OrderStatus.Cancelled` |
+| Confirm | Ato de finalizar e submeter um pedido | `Order.Confirm()` |
+| OrderItem | Linha de produto dentro de um pedido | `OrderItem` (Entity owned) |
+| Total | Soma calculada de todos os itens | `Order.Total` (property calculada) |
+
+---
+
+## Flows
+
+### Confirmar Pedido
+**Trigger:** Usuário clica "Confirmar Pedido"
+1. Frontend → `POST /api/orders/{id}/confirm`
+2. API → `ConfirmOrderCommand(OrderId)`
+3. Handler → `repository.GetAsync(id)` → `order.Confirm()` → `repository.UpdateAsync(order)`
+4. `OrderConfirmedEvent` publicado → NotificationService envia email
+**End State:** Order.Status = Confirmed
+
+---
+
+## Definition of Done
+- [ ] Aggregate implementado com todos os invariants
+- [ ] Domain Events publicados e consumidos
+- [ ] Testes unitários do Aggregate (sem EF)
+- [ ] Testes de integração do Handler
+- [ ] API endpoint documentado