biellts/universidade-automatiza / .claude/skills/backend-criar-mapping-ef-core
backend-criar-mapping-ef-core
VerifiedCria o mapeamento EF Core (Npgsql, snake_case) de uma entidade de domínio no schema do módulo e gera a migration correspondente. Use quando solicitado a criar ou alterar mapeamento, IEntityTypeConfiguration, tabela, coluna, índice ou migration.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
SKILL.md
View on GitHub---
name: backend-criar-mapping-ef-core
description: Cria o mapeamento EF Core (Npgsql, snake_case) de uma entidade de domínio no schema do módulo e gera a migration correspondente. Use quando solicitado a criar ou alterar mapeamento, IEntityTypeConfiguration, tabela, coluna, índice ou migration.
---
# Criar mapeamento EF Core + migration
O banco é da aplicação (PostgreSQL 17): o mapeamento **define** a tabela, e a migration do EF Core a cria e evolui. Cada módulo tem o próprio `DbContext` (herda `ModuloDbContext`) e o próprio schema; o mapeamento só enxerga tabelas desse schema.
## Local
`src/apps/Automatiza.Modules.{Modulo}/Features/{Entidade}s/DataBase/Mapping/{Entidade}Mapping.cs`
Namespace: `Automatiza.Modules.{Modulo}.Features.{Entidade}s.DataBase.Mapping`. O exemplo usa o módulo Catálogo.
## Regras
- `ToTable("{tabela_no_plural}")` explícito, em `snake_case` (`trilhas`). O schema vem do `HasDefaultSchema` do `ModuloDbContext` — não repita o schema no `ToTable`.
- Colunas em `snake_case` pela convenção `UseSnakeCaseNamingConvention()` (já ligada em `DataBaseConfiguration.Configurar`): **não** use `HasColumnName` coluna a coluna. Exceção: a coluna de um VO mapeado com `ComplexProperty`, que sem nome explícito viraria `titulo_text`.
- Chave `Guid` gerada no domínio (`Guid.CreateVersion7()`): `HasKey` + `ValueGeneratedNever()`.
- `HasMaxLength` em todo texto, usando a constante do agregado/VO (`Trilha.DescricaoTamanhoMaximo`, `TituloTrilha.TamanhoMaximo`); `HasPrecision` em `decimal` (notas e valores).
- Enums: `HasConversion<short>()` → coluna `smallint`; o enum declara `: short`.
- Datas: `DateTimeOffset` → `timestamptz`, sempre em UTC. Nunca `DateTime`.
- Auditoria: `CriadoEm`/`ModificadoEm` são colunas reais preenchidas pelo `AuditoriaInterceptor`; `CriadoPor`/`ModificadoPor` levam `HasMaxLength(100)`. `Events` já é ignorado pelo `ModuloDbContext` — não precisa de `Ignore()`.
- VO: `ComplexProperty` (ver a skill `backend-criar-value-object`). O EF rehidrata pelo construtor privado sem parâmetros do VO, sem passar pela validação.
- Coleções do agregado: `HasMany` com `HasForeignKey` explícito e acesso pelo campo (`Navigation(...).UsePropertyAccessMode(PropertyAccessMode.Field)`); carregue com `Include` ou `AutoInclude` antes de alterar.
- Índices para as colunas filtradas pelas consultas (`HasIndex`); unicidade de negócio vira `HasIndex(...).IsUnique()` — é o banco que garante, não um `SELECT` antes do `INSERT`.
- Relacionamento só entre entidades do mesmo módulo. Referência a outro módulo é só o Id (`Guid`), sem navegação e sem FK entre schemas.
- Multiempresa (quando o módulo Empresas existir): tabela com dado de pessoa ou de empresa cliente carrega `tenant_id`, com filtro global e RLS conforme o ADR-003. Não implemente antes de o módulo e o ADR existirem.
- Sem lazy loading, sem soft delete, sem `HasData`.
## Exemplo real (`TrilhaMapping`)
```csharp
using Automatiza.Modules.Catalogo.Domain.Entities.Trilha;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;
namespace Automatiza.Modules.Catalogo.Features.Trilhas.DataBase.Mapping;
public class TrilhaMapping : IEntityTypeConfiguration<Trilha>
{
public void Configure(EntityTypeBuilder<Trilha> builder)
{
builder.ToTable("trilhas");
builder.HasKey(t => t.Id);
builder.Property(t => t.Id).ValueGeneratedNever();
builder.ComplexProperty(t => t.Titulo, titulo =>
titulo.Property(x => x.Text).HasColumnName("titulo").HasMaxLength(TituloTrilha.TamanhoMaximo).IsRequired());
builder.Property(t => t.Descricao).HasMaxLength(Trilha.DescricaoTamanhoMaximo);
builder.Property(t => t.Publico).HasConversion<short>();
builder.Property(t => t.FuncaoAlvo).HasMaxLength(Trilha.FuncaoAlvoTamanhoMaximo);
builder.Property(t => t.CriadoPor).HasMaxLength(100);
builder.Property(t => t.ModificadoPor).HasMaxLength(100);
builder.HasIndex(t => t.FuncaoAlvo);
}
}
```
Resultado no banco (migration `Inicial` do Catálogo): tabela `catalogo.trilhas` com `id uuid`, `titulo varchar(150)`, `descricao varchar(1000)`, `publico smallint`, `funcao_alvo varchar(60)`, `criado_em timestamptz`, `criado_por`, `modificado_em`, `modificado_por`, chave `pk_trilhas` e índice `ix_trilhas_funcao_alvo`.
## Registro
- O `ModuloDbContext.OnModelCreating` chama `ApplyConfigurationsFromAssembly(GetType().Assembly)`: toda `IEntityTypeConfiguration<T>` do assembly do módulo é aplicada sozinha.
- Agregado novo ganha o `DbSet` no DbContext do módulo:
```csharp
public class CatalogoDbContext(DbContextOptions<CatalogoDbContext> options) : ModuloDbContext(options)
{
public const string NomeSchema = "catalogo";
public override string Schema => NomeSchema;
public DbSet<Trilha> Trilhas => Set<Trilha>();
}
```
## Migration
Depois de criar ou alterar o mapeamento, gere **uma** migration para a mudança:
```bash
dotnet tool restore
dotnet ef migrations add {Nome} --project src/apps/Automatiza.Modules.{Modulo} --output-dir DataBase/Migrations
dotnet ef migrations script --project src/apps/Automatiza.Modules.{Modulo} # revise o SQL gerado
```
- Nome descritivo em PascalCase (`Inicial`, `AdicionaCursosNaTrilha`).
- O `{Modulo}DbContextFactory` atende o design time; não precisa de banco rodando para gerar.
- O histórico fica em `{schema}.__ef_migrations` (um por módulo).
- Revise o SQL antes do PR: schema certo, tipos (`uuid`, `smallint`, `timestamptz`, `varchar(n)`), índices e nada destrutivo inesperado (`DROP`, perda de dado).
- **Nunca edite uma migration que já está na `main`**: crie outra. Nunca use `EnsureCreated`/`EnsureDeleted` fora de teste.
- Em `Development`, a API aplica as migrations ao subir (`Database:AplicarMigracoesAoIniciar`); nos testes de integração, a `ApplicationFactory` faz o mesmo no container. Em produção, a migration roda no deploy.
## Teste
Mapeamento e migration são cobertos por teste de integração (`ApplicationFactory` + Testcontainers PostgreSQL) que grava pelo endpoint e lê de volta — nunca por mock de DbContext. Regras gerais: `AGENTS.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |