Skip to content

biellts/universidade-automatiza / .claude/skills/backend-criar-mapping-ef-core

backend-criar-mapping-ef-core

Verified

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.

FileKindSize
SKILL.mdskill md6.1 KB
---
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`.
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall