Skip to content

biellts/universidade-automatiza / .claude/skills/backend-criar-agregado-ddd

backend-criar-agregado-ddd

Verified

Cria um novo agregado DDD com factory estático, encapsulamento de coleções e métodos de domínio. Use este skill quando solicitado a criar uma nova entidade de domínio, agregado ou raiz de agregado.

FileKindSize
SKILL.mdskill md6.9 KB
---
name: backend-criar-agregado-ddd
description: Cria um novo agregado DDD com factory estático, encapsulamento de coleções e métodos de domínio. Use este skill quando solicitado a criar uma nova entidade de domínio, agregado ou raiz de agregado.
---

Para criar um novo agregado DDD neste projeto, siga o processo abaixo:

## 1. Localização

Crie o arquivo em:
```
src/apps/Automatiza.Modules.{Modulo}/Domain/Entities/{Entidade}/{Entidade}.cs
```
Namespace: `Automatiza.Modules.{Modulo}.Domain.Entities.{Entidade}`. `Domain/` vive na raiz do módulo, nunca dentro de `Features/{Entidade}s/`. Os exemplos usam o módulo de exemplo Catálogo (`{Modulo}` = `Catalogo`, agregado `Trilha`).

`AggregateRoot<TId>` e `Entity<TId>` estão em `Automatiza.SeedWork.DomainObjects` (já importado pelo `GlobalUsings.cs` do módulo).

## 2. Estrutura base do agregado

Agregado real do Catálogo (`Domain/Entities/Trilha/Trilha.cs`):

```csharp
namespace Automatiza.Modules.Catalogo.Domain.Entities.Trilha;

/// <summary>
/// Caminho completo para um papel ou objetivo (ex.: Trilha do Operador de Caixa). Gera certificado de trilha.
/// </summary>
public class Trilha : AggregateRoot<Guid>
{
    public const int DescricaoTamanhoMaximo = 1000;
    public const int FuncaoAlvoTamanhoMaximo = 60;

    protected Trilha() { } // EF Core

    private Trilha(Guid id, TituloTrilha titulo, string? descricao, PublicoTrilha publico, string? funcaoAlvo)
    {
        Id = id;
        Titulo = titulo;
        Descricao = descricao;
        Publico = publico;
        FuncaoAlvo = funcaoAlvo;
    }

    public TituloTrilha Titulo { get; private set; } = default!;
    public string? Descricao { get; private set; }
    public PublicoTrilha Publico { get; private set; }

    /// <summary>Função do aluno que recebe a trilha automaticamente (ex.: Balconista). Nula para trilha sem função.</summary>
    public string? FuncaoAlvo { get; private set; }

    public static Result<Trilha> Criar(string? titulo, string? descricao, PublicoTrilha publico, string? funcaoAlvo)
    {
        var erros = new List<Error>();

        var tituloResult = TituloTrilha.Criar(titulo).TryCreate(out var tituloTrilha);
        if (!tituloResult.Success)
            erros.AddRange(tituloResult.Errors);

        if (!Enum.IsDefined(publico))
            erros.Add(TrilhaErrors.PublicoInvalido);

        var descricaoNormalizada = Normalizar(descricao);
        if (descricaoNormalizada?.Length > DescricaoTamanhoMaximo)
            erros.Add(TrilhaErrors.DescricaoMuitoLonga.Format(DescricaoTamanhoMaximo.ToString()));

        var funcaoNormalizada = Normalizar(funcaoAlvo);
        if (funcaoNormalizada?.Length > FuncaoAlvoTamanhoMaximo)
            erros.Add(TrilhaErrors.FuncaoAlvoMuitoLonga.Format(FuncaoAlvoTamanhoMaximo.ToString()));

        if (erros.Count > 0)
            return erros;

        return new Trilha(Guid.CreateVersion7(), tituloTrilha, descricaoNormalizada, publico, funcaoNormalizada);
    }

    private static string? Normalizar(string? texto) =>
        string.IsNullOrWhiteSpace(texto) ? null : texto.Trim();
}
```

Pontos a reproduzir:

- Id `Guid` gerado com `Guid.CreateVersion7()` dentro do `Criar` (o mapeamento usa `ValueGeneratedNever()`).
- `Criar` acumula **todos** os erros em `List<Error>` e devolve a lista de uma vez (conversão implícita `List<Error> → Result<T>`).
- Tamanhos máximos como `const` públicas no agregado/VO: o mapeamento EF (`HasMaxLength`) e os testes reutilizam a mesma constante.
- `= default!` em VOs/referências não anuláveis: o construtor protegido do EF não as define; evita CS8618.

## 3. Enums do agregado

Enums persistidos declaram `: short` (coluna `smallint`) e começam em 1:

```csharp
/// <remarks><c>short</c> igual à coluna <c>smallint</c>: o Dapper só casa enum com coluna do mesmo tipo-base.</remarks>
public enum PublicoTrilha : short
{
    Colaborador = 1,
    Cliente = 2
}
```

Valide com `Enum.IsDefined(...)` no `Criar`: o JSON aceita números fora do enum.

## 4. Métodos de domínio

Todo método que muda estado retorna `Result` ou `Result<T>` e protege as invariantes. Esqueleto:

```csharp
public Result {Acao}(...)
{
    if (/* invariante violada */)
        return {Entidade}Errors.{Erro};

    // altera o estado com private set
    return Result.Ok();
}
```

Datas de negócio (ex.: data de conclusão) recebem o instante como parâmetro (`DateTimeOffset agora`), obtido pelo handler via `TimeProvider`; nunca `DateTime.Now`/`DateTime.UtcNow` no domínio.

Regras oficiais de pontuação, ranking e certificado (`AGENTS.md`) moram no domínio do módulo dono, com teste unitário dos exemplos da arquitetura. Ex. ilustrativo: aprovação com nota ≥ 70% e XP = nota × fator da tentativa (1,0 / 0,8 / 0,6) — 90% na 2ª tentativa = 72 XP. Não crie regra que não esteja no `AGENTS.md` ou no requisito.

## 5. Regras obrigatórias

- **Nunca** exponha `public set` em propriedades — use `private set` ou `protected set`.
- **Nunca** permita criar o agregado via construtor público — use o factory estático `Criar(...)`.
- O construtor `protected` sem parâmetros é **exclusivo do EF Core**.
- `Id` herda de `Entity<TId>` com `protected set` — nunca sete externamente.
- Todos os métodos de domínio retornam `Result` ou `Result<T>`.
- Coleções internas: `private readonly List<T> _campo = [];` + `IReadOnlyCollection<T>` público.
- Valores de nota e financeiros em `decimal`.

## 6. Herança

| Base | Inclui |
|---|---|
| `AggregateRoot<TId>` | `CriadoEm`, `CriadoPor`, `ModificadoEm`, `ModificadoPor` (`IAuditableEntity`) |
| `Entity<TId>` | `Id`, igualdade por Id, `Events` |

- `CriadoEm`/`ModificadoEm` são colunas reais (`criado_em`, `modificado_em`, `timestamptz`) preenchidas pelo `AuditoriaInterceptor` no `SaveChanges`; nunca preencha à mão. `CriadoPor`/`ModificadoPor` ficam nulos até o módulo Identidade existir.
- `Events` é ignorado automaticamente pelo `ModuloDbContext`; não precisa de `Ignore()` no mapeamento.
- Não há soft delete: não herde de outras bases.

## 7. Entidades filhas (não-raiz)

Para entidades que pertencem ao agregado mas não são raiz, mesmo padrão (construtor protegido, `Criar` com `Result<T>`, `private set`), herdando `Entity<Guid>`:

```csharp
public class {EntidadeFilha} : Entity<Guid>
{
    protected {EntidadeFilha}() { } // EF Core

    private {EntidadeFilha}(Guid id, ...) { Id = id; ... }

    internal static Result<{EntidadeFilha}> Criar(...)
    {
        var erros = new List<Error>();
        // validações
        if (erros.Count > 0)
            return erros;

        return new {EntidadeFilha}(Guid.CreateVersion7(), ...);
    }
}
```

A raiz expõe o método que adiciona a filha (`private readonly List<{EntidadeFilha}> _itens = [];`) e é o único ponto de alteração. Se a filha é agregado próprio ou parte de outro (ex.: curso dentro de trilha) é decisão do requisito/arquitetura — não decida por suposição.

Mapeamento e migration: skill `backend-criar-mapping-ef-core`. Regras gerais: `AGENTS.md`.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall