biellts/universidade-automatiza / .claude/skills/backend-criar-agregado-ddd
backend-criar-agregado-ddd
VerifiedCria 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
Guidgerado comGuid.CreateVersion7()dentro doCriar(o mapeamento usaValueGeneratedNever()). Criaracumula todos os erros emList<Error>e devolve a lista de uma vez (conversão implícitaList<Error> → Result<T>).- Tamanhos máximos como
constpú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 setem propriedades — useprivate setouprotected set. - Nunca permita criar o agregado via construtor público — use o factory estático
Criar(...). - O construtor
protectedsem parâmetros é exclusivo do EF Core. Idherda deEntity<TId>comprotected set— nunca sete externamente.- Todos os métodos de domínio retornam
ResultouResult<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/ModificadoEmsão colunas reais (criado_em,modificado_em,timestamptz) preenchidas peloAuditoriaInterceptornoSaveChanges; nunca preencha à mão.CriadoPor/ModificadoPorficam nulos até o módulo Identidade existir.Eventsé ignorado automaticamente peloModuloDbContext; não precisa deIgnore()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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |