@polymorphism-tech/morph-spec 8.46.0 → 8.47.0

package/framework/standards/backend/api/validation.md

@@ -1,91 +1,179 @@
-# Status Validation Pattern
+# Request Validation — DTO Validation in the Slice
 
 > **Scope:** universal
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `csharp-standards` ao editar `**/*.cs`/`**/*.csproj`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** validation, fluent, dto, modelstate, fluentvalidation
 > **Load When:** always
 
-**Verified against:** .NET 10 (pure state-validation pattern — no external package). Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + FluentValidation 12.1.1 + EF Core 10.0.12. The validator, `OrderStatus`, `OrderErrors` and state-check handler blocks compile with `TreatWarningsAsErrors` over the `Result`/`Error`/`ValidationError` of `result-pattern.md`. Last-verified: 2026-10-03.
 
 ---
 
-**MORPH-SPEC Standard** — Validate what is INVALID, not what is valid.
+**MORPH-SPEC Standard** — every request DTO is validated in its own slice, before the handler runs, and a failure leaves as a `Result`, never as an exception.
 
-## Problem
+## Where each check lives
 
-Validations assuming a single flow break when new flows are added.
+| Check | Lives in | Fails as | HTTP (via `error.ToHttpResult()`) |
+|-------|----------|----------|-----------------------------------|
+| Request **shape**: required, length, range, format, enum, CPF/CNPJ | `{Verb}{Entity}Validator : AbstractValidator<TRequest>` in the slice folder | `ValidationError` (aggregated `Error.Validation` items) from the `ValidationDecorator` | 400 ProblemDetails with `errors[]` |
+| Needs the database: entity exists, unique value | The handler, after loading | `Error.NotFound` / `Error.Conflict` | 404 / 409 |
+| Entity **state** allows the operation (order not completed, not cancelled) | The handler (see *State checks in the handler*) | `Error.Failure` / `Error.Conflict` | 400 / 409 |
 
+`ModelState` does not exist in minimal APIs, and DataAnnotations on the request plus FluentValidation would be two validators disagreeing about the same DTO: the stack uses FluentValidation through the decorator, only.
+
+## FluentValidation Validator in the Slice
+
+```csharp
+// Features/OrderFeature/CreateOrder/CreateOrderValidator.cs
+using FluentValidation;
+
+public sealed record CreateOrderItem(Guid ProductId, int Quantity);
+public sealed record CreateOrderRequest(Guid CustomerId, string? CouponCode, IReadOnlyList<CreateOrderItem> Items);
+
+public sealed class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
+{
+    public CreateOrderValidator()
+    {
+        RuleFor(r => r.CustomerId).NotEmpty();
+
+        RuleFor(r => r.CouponCode)
+            .MaximumLength(32)
+            .Matches("^[A-Z0-9-]+$").WithMessage("Coupon code must be upper-case letters, digits or '-'.")
+            .When(r => r.CouponCode is not null);
+
+        RuleFor(r => r.Items)
+            .NotEmpty().WithMessage("An order needs at least one item.");
+
+        RuleForEach(r => r.Items).ChildRules(item =>
+        {
+            item.RuleFor(i => i.ProductId).NotEmpty();
+            item.RuleFor(i => i.Quantity).InclusiveBetween(1, 100);
+        });
+    }
+}
 ```
-Original: Created → PendingPayment → Processing → Completed → EmailSent
-Free:     Created → Processing → Completed → EmailSent  (skips payment)
+
+- One validator per request, `sealed`, next to the handler; no validator for a request without input (GetAll).
+- Validate the **shape** only. "Does this customer exist?" needs the database and is the handler's job (a validator with a `DbContext` runs a query per rule and still cannot see a concurrent write).
+- Time-dependent rules take `TimeProvider` and read it inside the rule (`LessThanOrEqualTo(_ => timeProvider.GetUtcNow().Year)`), never `DateTime.UtcNow`.
+
+## How a failure reaches HTTP
+
+```
+request ─→ ValidationDecorator ─→ any failure? ─yes─→ Result.Failure(new ValidationError([...])) ─→ endpoint: error.ToHttpResult() ─→ 400 + errors[]
+                                      │
+                                      no
+                                      ↓
+                                   handler ─→ Result<T>
 ```
 
-```csharp
-// ❌ Assumes single flow — breaks free flow
-if (order.Status != OrderStatus.PendingPayment)
-    throw new InvalidOperationException("Must be pending payment");
+The decorator, its registration (`AddValidatorsFromAssembly` before `AddHandlersFromAssembly`) and the `ValidationFailure` → `Error.Validation` conversion are in `backend/dotnet/fluent-validation-vsa.md`; the `ValidationError` record and `ErrorHttpMapping.ToHttpResult()` (which puts the items in the ProblemDetails `errors` extension) are in `backend/dotnet/result-pattern.md`. The endpoint never inspects the error itself.
+
+## Validation Patterns
+
+| Rule | Why |
+|------|-----|
+| Validate in the slice's validator, never in the endpoint lambda | One place per request; the endpoint only maps HTTP |
+| Return `Result`, never `throw` (`ValidationException`, `ArgumentException`) | Exceptions as flow are forbidden; the decorator already short-circuits with a `ValidationError` |
+| Aggregate all failures | The client fixes every field in one round-trip |
+| Message per rule that the UI can show | `errors[].description` is what the form displays |
+| Shape in the validator, existence/uniqueness/state in the handler | The validator has no reliable view of the database |
 
-// ✅ Validates invalid states — works for all flows
-if (order.Status >= OrderStatus.Completed || order.Status == OrderStatus.Failed)
-    throw new InvalidOperationException("Order already completed or failed");
+## State checks in the handler
+
+Some operations depend on the entity's **state**, not the request's shape. That check lives in the handler, after loading the entity, and returns a `Result`. The rule: validate what is INVALID, not what is valid, so a new flow does not break existing checks.
+
+```
+Original: Created → PendingPayment → Processing → Completed → EmailSent
+Free:     Created → Processing → Completed → EmailSent  (skips payment)
 ```
 
-## Enum Design
+`if (order.Status != OrderStatus.PendingPayment)` assumes the single original flow and rejects every free order; `if (order.Status >= OrderStatus.Completed)` blocks what is actually invalid and works for both flows.
+
+### Enum Design
 
 ```csharp
 public enum OrderStatus
 {
     Created = 0, PendingPayment = 1, Processing = 2, Completed = 3, EmailSent = 4,
-    // Error states (separated range)
     Failed = 100, Cancelled = 101, Refunded = 102
 }
 ```
 
-## Validation Patterns
+Progress states are ordered; error states sit in a separate range (100+), so `status >= OrderStatus.Completed` covers "finished or failed" in one comparison.
+
+### State Check Patterns
 
 | Pattern | When | Example |
 |---------|------|---------|
-| Final state check | Block after completion | `if (status >= OrderStatus.Completed)` |
-| Error state list | Block specific errors | `if (new[] { Failed, Cancelled, Refunded }.Contains(status))` |
-| Range comparison | Block finalized + errors | `if (status >= Completed \|\| status >= Failed)` |
+| Final state check | Block after completion (includes the 100+ error range) | `if (status >= OrderStatus.Completed)` |
+| Error state list | Block specific errors only | `if (status is OrderStatus.Failed or OrderStatus.Cancelled or OrderStatus.Refunded)` |
+| Error range | Block every error state | `if (status >= OrderStatus.Failed)` |
 
-## Anti-Patterns
-
-| Anti-Pattern | Problem | Fix |
-|-------------|---------|-----|
-| `if (status != Expected)` | Assumes single flow | Validate invalid states instead |
-| Exhaustive switch on valid states | Must modify for each new status | Validate only invalid states |
-| Business logic in state validator | Mixed concerns | Separate state validation from business rules |
-
-## Complete Example
+### Complete Example
 
 ```csharp
-public async Task<Result> ProcessOrderAsync(Guid orderId, CancellationToken ct)
+// Features/OrderFeature/OrderErrors.cs
+public static class OrderErrors
 {
-    var order = await _db.Orders.FindAsync([orderId], ct);
-    if (order == null) return Result.Failure("Order not found");
+    public static Error NotFound(Guid orderId) =>
+        Error.NotFound("Orders.NotFound", $"The Order with Id '{orderId}' was not found");
+    public static readonly Error AlreadyFinished =
+        Error.Conflict("Orders.AlreadyFinished", "The order is already completed or in an error state.");
+    public static readonly Error PaymentRequired =
+        Error.Failure("Orders.PaymentRequired", "The order must be paid before processing.");
+}
+```
 
-    // State validation (invalid states)
-    if (order.Status >= OrderStatus.Completed) return Result.Failure("Already completed");
-    if (order.Status == OrderStatus.Failed) return Result.Failure("Cannot process failed order");
-    if (order.Status == OrderStatus.Cancelled) return Result.Failure("Cannot process cancelled order");
+```csharp
+// Features/OrderFeature/ProcessOrder/ProcessOrderHandler.cs
+using Microsoft.EntityFrameworkCore;
 
-    // Business validation (separate)
-    if (order.RequiresPayment && !order.IsPaid) return Result.Failure("Payment required");
+public sealed record ProcessOrderRequest(Guid OrderId);
 
-    order.MarkAsProcessing();
-    await _db.SaveChangesAsync(ct);
-    return Result.Success();
+public sealed class ProcessOrderHandler(ApplicationDbContext db) : IHandler<ProcessOrderRequest, Result>
+{
+    public async Task<Result> HandleAsync(ProcessOrderRequest request, CancellationToken cancellationToken)
+    {
+        var order = await db.Orders.FirstOrDefaultAsync(o => o.Id == request.OrderId, cancellationToken);
+        if (order is null)
+            return OrderErrors.NotFound(request.OrderId);
+
+        if (order.Status >= OrderStatus.Completed)
+            return OrderErrors.AlreadyFinished;
+
+        if (order.RequiresPayment && !order.IsPaid)
+            return OrderErrors.PaymentRequired;
+
+        order.Status = OrderStatus.Processing;
+        await db.SaveChangesAsync(cancellationToken);
+        return Result.Success();
+    }
 }
 ```
 
+The state check (`>= Completed`) and the business rule (`RequiresPayment && !IsPaid`) stay separate lines with separate errors: the free flow passes the first and skips the second.
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| `throw new ValidationException(...)` / `throw new InvalidOperationException(...)` for bad input or state | Exceptions as flow; bypasses the `Result` mapping | Validator → `ValidationError`; handler → typed `Error` |
+| Validation inside the endpoint lambda | Logic leaks out of the slice, not reusable by jobs | `AbstractValidator<TRequest>` in the slice |
+| DataAnnotations + FluentValidation on the same DTO | Two sources of truth | FluentValidation only |
+| `Result.Failure("message")` with a bare string | Does not compile against the `Error` record and has no code/type | Typed `{Entity}Errors` factories |
+| `if (status != Expected)` | Assumes single flow | Validate invalid states instead |
+| Exhaustive switch on valid states | Must modify for each new status | Validate only invalid states |
+| Business rules mixed into the state check | Mixed concerns | Separate state check from business rules |
+
 ## Checklist
 
-- [ ] Validates INVALID states (not valid)?
-- [ ] Uses ordered enum comparison where possible?
-- [ ] Error states treated separately (100+ range)?
-- [ ] All flows documented in decisions.md?
-- [ ] Tested with all possible flows?
+- [ ] Every request with input has a `sealed` validator in its slice folder?
+- [ ] Validator checks shape only (no `DbContext`)?
+- [ ] Failures come back as `ValidationError` → 400 ProblemDetails with `errors[]`, never an exception?
+- [ ] Existence / uniqueness / state checks in the handler, returning typed `Error`s?
+- [ ] State checks validate INVALID states, with the error range at 100+?
+- [ ] All flows documented in decisions.md and tested?
 
 ---
 

package/framework/standards/backend/database/postgresql/database.md

@@ -5,7 +5,7 @@
 > **Keywords:** postgresql, postgres, sql, neon, database schema
 > **Load When:** neon or postgresql keywords detected
 
-**Verified against:** PostgreSQL 16/17 + EF Core 10 + @neondatabase/serverless. Last-verified: 2026-05-20.
+**Verified against:** PostgreSQL 16/17 + EF Core 10.0.12 (Npgsql provider 10.0.3) + @neondatabase/serverless. The EF Core query blocks compile with `TreatWarningsAsErrors` inside a wrapper method over stand-in entities; the SQL is documentary. Last-verified: 2026-10-03.
 
 ---
 
@@ -21,7 +21,7 @@ Database schema design, migrations, and Row Level Security (RLS) patterns for Ne
 |---------|-----------|---------|
 | **Tables** | snake_case, plural | `users`, `user_profiles`, `order_items` |
 | **Columns** | snake_case | `created_at`, `user_id`, `is_active` |
-| **Primary Keys** | `id` | `id uuid primary key default gen_random_uuid()` |
+| **Primary Keys** | `id` | `id uuid primary key` -- value set by the app with `Guid.CreateVersion7()`, no column default |
 | **Foreign Keys** | `{table}_id` | `user_id`, `order_id` |
 | **Timestamps** | `created_at`, `updated_at` | Always include |
 | **Boolean** | `is_` or `has_` prefix | `is_active`, `has_verified_email` |
@@ -29,9 +29,11 @@ Database schema design, migrations, and Row Level Security (RLS) patterns for Ne
 
 ### Standard Table Template
 
+Application ids are generated by the .NET handler with `Guid.CreateVersion7()` (time-ordered, index-friendly), so the column has **no** `default gen_random_uuid()`: one generator per id (the app), and random v4 values would scatter the B-tree index that v7 keeps append-mostly. A row inserted outside the app (seed script, SQL console) passes an explicit id.
+
 ```sql
 create table public.users (
-  id uuid primary key default gen_random_uuid(),
+  id uuid primary key,
   email text unique not null,
   full_name text,
   avatar_url text,
@@ -135,7 +137,7 @@ dotnet ef migrations script --idempotent
 ```sql
 -- Create table
 create table if not exists public.example_table (
-  id uuid primary key default gen_random_uuid(),
+  id uuid primary key,
   name text not null,
   created_at timestamptz default now() not null
 );
@@ -164,7 +166,7 @@ create index if not exists idx_example_table_name
 
 ```sql
 create table public.posts (
-  id uuid primary key default gen_random_uuid(),
+  id uuid primary key,
   author_id uuid references public.users(id) on delete cascade,
   title text not null,
   content text,
@@ -274,7 +276,7 @@ var users = await db.Users
 ### Insert (EF Core)
 
 ```csharp
-var user = new User { Name = "John", Email = "john@example.com" };
+var user = new User { Id = Guid.CreateVersion7(), Name = "John", Email = "john@example.com" };
 db.Users.Add(user);
 await db.SaveChangesAsync(ct);
 ```
@@ -310,7 +312,9 @@ var posts = await db.Posts
     .ToListAsync(ct);
 ```
 
-### Direct SQL via Npgsql (Next.js / serverless)
+### Direct SQL from a Node runtime (@neondatabase/serverless)
+
+In the baked stack the Next.js frontend reads data through the .NET API (proxy + TanStack Query), not from the database. This driver is for Node-side tooling (seed scripts, one-off jobs) where there is no .NET API in the path:
 
 ```typescript
 import { neon } from '@neondatabase/serverless';