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).

FileKindSize
SKILL.mdskill md9.9 KB
---
name: backend-criar-modulo
description: 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:

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

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

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

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

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

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

   ```xml
   <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()`:

   ```csharp
   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

```bash
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`):

```xml
<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`):

```bash
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