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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.9 KB |
SKILL.md
View on GitHub---
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`.
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: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |