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.

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):

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:

/// <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:

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

BaseInclui
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>:

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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall