biellts/universidade-automatiza / .claude/skills/backend-criar-modulo
backend-criar-modulo
VerifiedCria 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
- 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 (agentadr-generator). - Leia a seção do módulo em
docs/produto/arquitetura-plataforma.mde 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;
}
}
AddModuloDbContextregistra o DbContext com oNpgsqlDataSourcecompartilhado, a convenção snake_case, o histórico de migrations em{modulo}.__ef_migrations, oAuditoriaInterceptor, e inclui o contexto na lista que oAplicarMigracoesAsyncmigra na subida.- Enquanto o módulo Identidade não existir, use
MapDocumentedGroupe mantenha o comentário do Catálogo ("Sem autorização até o módulo Identidade existir..."). Com a Identidade pronta, troque porMapAuthorizedGroup/MapPublicGroupconforme 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
-
Referência do projeto em
src/apps/Automatiza.WebApi/Automatiza.WebApi.csproj:<ProjectReference Include="..\Automatiza.Modules.{Modulo}\Automatiza.Modules.{Modulo}.csproj" /> -
Em
src/apps/Automatiza.WebApi/Program.cs:using Automatiza.Modules.{Modulo};, oAdd{Modulo}Module(), o assembly do módulo emAddCustomMediator(senão os handlers não são registrados) e oMap{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 SCHEMAdo{modulo}, as tabelas no plural em snake_case e o histórico em{modulo}.__ef_migrations. - Confira que a migration e o
{Modulo}DbContextModelSnapshot.csficaram juntos emDataBase/Migrations/. Não passe--namespace: com ele, odotnet efgrava o snapshot numa pasta derivada do namespace. - Suba a API em
Developmentou rode os testes de integração: as migrations do módulo novo são aplicadas sozinhas (AplicarMigracoesAsynceApplicationFactory).
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}.csprojcom as duas referências e oMicrosoft.EntityFrameworkCore.Design -
GlobalUsings.cs -
{Modulo}DbContext : ModuloDbContextcomNomeSchemaeSchema -
{Modulo}DbContextFactory -
ModuleConfigurationcomAdd{Modulo}Module(AddModuloDbContext) eMap{Modulo}Endpoints - Constante em
GruposDeDocumentacao - Referência no
Automatiza.WebApi.csproj;Add{Modulo}Module, assembly emAddCustomMediatoreMap{Modulo}EndpointsnoProgram.cs -
dotnet sln adde referência no projeto de testes unitários - Migration
Inicialgerada e SQL revisado -
docs/modulos/{modulo}/ -
dotnet build src/Automatiza.Universidade.slnsem warnings novos edotnet test src/Automatiza.Universidade.slnverde
Regras gerais: AGENTS.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |