Skip to content

biellts/universidade-automatiza / .claude/skills/backend-criar-modulo

backend-criar-modulo

Verified

Cria um novo módulo do monólito modular (Automatiza.Modules.{Modulo}) espelhando o Catálogo — projeto, DbContext com schema próprio, factory de design time, ModuleConfiguration, grupo de documentação, registro no host, solução, testes, primeira migration e pasta de documentação. Use quando solicitado a criar um módulo novo (Identidade, Empresas, Aprendizagem, Avaliação, Gamificação, Certificação, Notificações, Relatórios).

Criar módulo

Um módulo novo segue a estrutura do Catálogo (src/apps/Automatiza.Modules.Catalogo/), que é o modelo da base. Nos passos abaixo, {Modulo} é o nome em PascalCase sem acento (Gamificacao) e {modulo} é o schema/pasta em minúsculas sem acento (gamificacao).

Antes de começar

  1. O módulo precisa estar na lista do AGENTS.md (Identidade, Empresas, Catálogo, Aprendizagem, Avaliação, Gamificação, Certificação, Notificações, Relatórios). Módulo fora da lista é decisão de arquitetura: ADR antes (agent adr-generator).
  2. Leia a seção do módulo em docs/produto/arquitetura-plataforma.md e os requisitos da primeira feature que vai usá-lo.

1. Projeto

src/apps/Automatiza.Modules.{Modulo}/Automatiza.Modules.{Modulo}.csproj — igual ao do Catálogo, inclusive o Microsoft.EntityFrameworkCore.Design (necessário para o dotnet ef) na mesma versão:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.15">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\Automatiza.CrossCutting\Automatiza.CrossCutting.csproj" />
    <ProjectReference Include="..\Automatiza.CrossCutting.DataBase\Automatiza.CrossCutting.DataBase.csproj" />
  </ItemGroup>
</Project>

Confira a versão atual no Automatiza.Modules.Catalogo.csproj: ela precisa casar com o Microsoft.EntityFrameworkCore.Relational fixado em Automatiza.CrossCutting.DataBase.csproj.

Um módulo não referencia o projeto de outro módulo. A comunicação entre módulos é por interface pública ou evento — e a forma de expor essa interface ainda não existe na base: se a feature precisar, proponha antes de criar.

2. GlobalUsings

src/apps/Automatiza.Modules.{Modulo}/GlobalUsings.cs, igual ao do Catálogo:

global using Automatiza.CrossCutting.DataBase;
global using Automatiza.CrossCutting.Mediator;
global using Automatiza.CrossCutting.Mediator.Core;
global using Automatiza.CrossCutting.Modules;
global using Automatiza.SeedWork.DomainObjects;
global using Automatiza.SeedWork.Models;
global using Dapper;
global using Microsoft.AspNetCore.Builder;
global using Microsoft.AspNetCore.Http;
global using Microsoft.AspNetCore.Mvc;
global using Microsoft.AspNetCore.Routing;
global using Microsoft.Extensions.Configuration;
global using Microsoft.Extensions.DependencyInjection;

3. DbContext

src/apps/Automatiza.Modules.{Modulo}/DataBase/{Modulo}DbContext.cs:

using Automatiza.Modules.{Modulo}.Domain.Entities.{Entidade};
using Microsoft.EntityFrameworkCore;

namespace Automatiza.Modules.{Modulo}.DataBase;

public class {Modulo}DbContext(DbContextOptions<{Modulo}DbContext> options) : ModuloDbContext(options)
{
    public const string NomeSchema = "{modulo}";

    public override string Schema => NomeSchema;

    public DbSet<{Entidade}> {Entidade}s => Set<{Entidade}>();
}

O ModuloDbContext já aplica HasDefaultSchema(Schema), todos os IEntityTypeConfiguration<T> do assembly e o Ignore de Events. Não sobrescreva OnModelCreating sem necessidade.

4. Factory de design time

src/apps/Automatiza.Modules.{Modulo}/DataBase/{Modulo}DbContextFactory.cs — usada só pelo dotnet ef:

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Design;

namespace Automatiza.Modules.{Modulo}.DataBase;

/// <summary>
/// Usada só pelo <c>dotnet ef</c> para gerar migrations; a connection string não precisa apontar para um banco real.
/// </summary>
public class {Modulo}DbContextFactory : IDesignTimeDbContextFactory<{Modulo}DbContext>
{
    public {Modulo}DbContext CreateDbContext(string[] args)
    {
        var options = new DbContextOptionsBuilder<{Modulo}DbContext>();
        DataBaseConfiguration.Configurar(options, "Host=localhost;Database=universidade", {Modulo}DbContext.NomeSchema);

        return new {Modulo}DbContext(options.Options);
    }
}

5. ModuleConfiguration

src/apps/Automatiza.Modules.{Modulo}/ModuleConfiguration.cs:

using Automatiza.Modules.{Modulo}.DataBase;

namespace Automatiza.Modules.{Modulo};

public static class ModuleConfiguration
{
    public const string PrefixUri = "api/v1";

    public static IServiceCollection Add{Modulo}Module(this IServiceCollection services)
    {
        services.AddModuloDbContext<{Modulo}DbContext>({Modulo}DbContext.NomeSchema);

        return services;
    }

    public static IEndpointRouteBuilder Map{Modulo}Endpoints(this IEndpointRouteBuilder endpoints)
    {
        endpoints
            .MapDocumentedGroup(PrefixUri, "{Nome de exibição}", GruposDeDocumentacao.{Modulo})
            .MapEndoints("Automatiza.Modules.{Modulo}.Features", typeof(ModuleConfiguration).Assembly);

        return endpoints;
    }
}
  • AddModuloDbContext registra o DbContext com o NpgsqlDataSource compartilhado, a convenção snake_case, o histórico de migrations em {modulo}.__ef_migrations, o AuditoriaInterceptor, e inclui o contexto na lista que o AplicarMigracoesAsync migra na subida.
  • Enquanto o módulo Identidade não existir, use MapDocumentedGroup e mantenha o comentário do Catálogo ("Sem autorização até o módulo Identidade existir..."). Com a Identidade pronta, troque por MapAuthorizedGroup/MapPublicGroup conforme a feature.
  • Serviços do módulo que não são handlers (ex.: Validators) também são registrados em Add{Modulo}Module.

6. Grupo de documentação

Em src/apps/Automatiza.CrossCutting/Modules/OpenApiTagGroups.cs, acrescente a constante em GruposDeDocumentacao:

public static class GruposDeDocumentacao
{
    public const string Catalogo = "Catálogo";
    public const string {Modulo} = "{Nome de exibição}";
}

7. Registro no host

  1. Referência do projeto em src/apps/Automatiza.WebApi/Automatiza.WebApi.csproj:

    <ProjectReference Include="..\Automatiza.Modules.{Modulo}\Automatiza.Modules.{Modulo}.csproj" />
    
  2. Em src/apps/Automatiza.WebApi/Program.cs: using Automatiza.Modules.{Modulo};, o Add{Modulo}Module(), o assembly do módulo em AddCustomMediator (senão os handlers não são registrados) e o Map{Modulo}Endpoints():

    builder.Services
        .AddDataBase(builder.Configuration)
        .AddCatalogoModule()
        .Add{Modulo}Module()
        .AddCustomMediator(
            typeof(Automatiza.Modules.Catalogo.ModuleConfiguration).Assembly,
            typeof(Automatiza.Modules.{Modulo}.ModuleConfiguration).Assembly);
    
    // ...
    app.MapCatalogoEndpoints();
    app.Map{Modulo}Endpoints();
    

    A ordem dos Map...Endpoints é a ordem dos grupos no Scalar.

8. Solução e testes

dotnet sln src/Automatiza.Universidade.sln add --solution-folder apps src/apps/Automatiza.Modules.{Modulo}/Automatiza.Modules.{Modulo}.csproj

No src/tests/Automatiza.WebApi.UnitTests/Automatiza.WebApi.UnitTests.csproj, acrescente a referência (os testes de integração já enxergam o módulo pelo Automatiza.WebApi):

<ProjectReference Include="..\..\apps\Automatiza.Modules.{Modulo}\Automatiza.Modules.{Modulo}.csproj" />

Testes do módulo em src/tests/Automatiza.WebApi.UnitTests/{Modulo}/{Entidade}/ e src/tests/Automatiza.WebApi.IntegrationTests/{Modulo}/ (skills backend-criar-teste-unitario e csharp-xunit).

9. Primeira migration

Com o primeiro agregado e o mapeamento prontos (skills backend-criar-agregado-ddd e backend-criar-mapping-ef-core):

dotnet tool restore
dotnet ef migrations add Inicial --project src/apps/Automatiza.Modules.{Modulo} --output-dir DataBase/Migrations
dotnet ef migrations script --project src/apps/Automatiza.Modules.{Modulo}
  • Confira no SQL o CREATE SCHEMA do {modulo}, as tabelas no plural em snake_case e o histórico em {modulo}.__ef_migrations.
  • Confira que a migration e o {Modulo}DbContextModelSnapshot.cs ficaram juntos em DataBase/Migrations/. Não passe --namespace: com ele, o dotnet ef grava o snapshot numa pasta derivada do namespace.
  • Suba a API em Development ou rode os testes de integração: as migrations do módulo novo são aplicadas sozinhas (AplicarMigracoesAsync e ApplicationFactory).

10. Documentação

Crie docs/modulos/{modulo}/ com a pasta requisitos/ para os F{nnn}-*.md (template em docs/templates/requisito.md). Siga docs/README.md → "Onde registrar" para o restante.

Checklist

  • Automatiza.Modules.{Modulo}.csproj com as duas referências e o Microsoft.EntityFrameworkCore.Design
  • GlobalUsings.cs
  • {Modulo}DbContext : ModuloDbContext com NomeSchema e Schema
  • {Modulo}DbContextFactory
  • ModuleConfiguration com Add{Modulo}Module (AddModuloDbContext) e Map{Modulo}Endpoints
  • Constante em GruposDeDocumentacao
  • Referência no Automatiza.WebApi.csproj; Add{Modulo}Module, assembly em AddCustomMediator e Map{Modulo}Endpoints no Program.cs
  • dotnet sln add e referência no projeto de testes unitários
  • Migration Inicial gerada e SQL revisado
  • docs/modulos/{modulo}/
  • dotnet build src/Automatiza.Universidade.sln sem warnings novos e dotnet test src/Automatiza.Universidade.sln verde

Regras gerais: AGENTS.md.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall