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.

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)

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

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