Skip to content

biellts/universidade-automatiza / .claude/skills/backend-criar-use-case

backend-criar-use-case

Verified

Cria um novo caso de uso completo no padrão Vertical Slice + CQRS do projeto. Use este skill quando solicitado a criar um novo Use Case, Command, Query, Handler ou operação CRUD em qualquer módulo.

Para criar um novo caso de uso neste projeto, siga o processo abaixo:

1. Estrutura de pastas

Crie os arquivos dentro de:

src/apps/Automatiza.Modules.{Modulo}/Features/{Entidade}s/UseCases/{NomeDoCasoDeUso}/

Os exemplos são os casos de uso reais do Catálogo: CriarTrilha (escrita), ObterTrilhaPorId e ListarTrilhas (leitura). PaginatedResponse<T>, PaginationRequest e EntityIdResponse<T> estão em Automatiza.SeedWork.Models.

Os arquivos padrão são:

  • {X}Request.cs — record implementando ICommand<Result<T>> (escrita) ou IQuery<Result<T>> (leitura)
  • {X}CommandHandler.cs (escrita) ou {X}QueryHandler.cs (leitura) — herda Handler<TRequest, TResponse>
  • {X}Endpoint.cs — implementa IUseCaseEndpoint
  • {X}Response.cs — record de resposta (listagem: {X}ItemResponse.cs)
  • {X}Query.cs — SQL Dapper (somente leitura; ver backend-criar-consulta-dapper)
  • {X}Validator.cs — validações com acesso ao banco (opcional; ver backend-criar-validator-assincrono)

Namespace: Automatiza.Modules.{Modulo}.Features.{Entidade}s.UseCases.{CasoDeUso}.

2. Request (Command ou Query)

Para operações que alteram estado, ICommand<T>. Record posicional, com Description para o Scalar:

using System.ComponentModel;
using Automatiza.Modules.Catalogo.Domain.Entities.Trilha;

namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.CriarTrilha;

public record CriarTrilhaRequest(
    [property: Description("Título da trilha (3 a 150 caracteres)")] string? Titulo,
    [property: Description("Descrição exibida ao aluno")] string? Descricao,
    [property: Description("Colaborador (interno) ou Cliente (farmácias)")] PublicoTrilha Publico,
    [property: Description("Função do aluno que recebe a trilha (ex.: Balconista)")] string? FuncaoAlvo)
    : ICommand<Result<CriarTrilhaResponse>>;

// CriarTrilhaResponse.cs
public record CriarTrilhaResponse(Guid Id);

Campos de texto chegam anuláveis (string?): quem valida é o domínio, que devolve o erro tipado.

Para leitura, IQuery<T>. Em listagens, filtros opcionais + PageSize/PageIndex e uma constante de página máxima:

public record ListarTrilhasRequest(
    [property: Description("Filtra pelo público; vazio traz todas")] PublicoTrilha? Publico = null,
    int PageSize = 10,
    int PageIndex = 0)
    : IQuery<Result<PaginatedResponse<ListarTrilhasItemResponse>>>
{
    public const int TamanhoMaximoPagina = 100;
}

public record ObterTrilhaPorIdRequest(Guid Id) : IQuery<Result<ObterTrilhaPorIdResponse>>;

O record de request ({X}Request.cs) é diferente da classe de SQL ({X}Query.cs): o primeiro é o contrato do handler; a segunda guarda o SQL.

Nomes de leitura: Listar{Entidades} (ListarTrilhas) e Obter{Entidade}PorId (ObterTrilhaPorId).

3. Handler

Escrita — o handler orquestra: chama o factory/método do agregado, adiciona ao DbContext do próprio módulo e salva uma vez.

using Automatiza.Modules.Catalogo.DataBase;
using Automatiza.Modules.Catalogo.Domain.Entities.Trilha;

namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.CriarTrilha;

public class CriarTrilhaCommandHandler(CatalogoDbContext contexto)
    : Handler<CriarTrilhaRequest, Result<CriarTrilhaResponse>>
{
    public override async Task<Result<CriarTrilhaResponse>> OnHandle(CriarTrilhaRequest request, CancellationToken cancellationToken)
    {
        var criacao = Trilha.Criar(request.Titulo, request.Descricao, request.Publico, request.FuncaoAlvo);
        if (!criacao.TryGetValue(out var trilha))
            return Result<CriarTrilhaResponse>.Fail(criacao.Errors);

        contexto.Trilhas.Add(trilha);
        await contexto.SaveChangesAsync(cancellationToken);

        return new CriarTrilhaResponse(trilha.Id);
    }
}

Alteração de agregado existente: carregue-o pelo DbContext (contexto.Trilhas.FirstOrDefaultAsync(t => t.Id == request.Id, cancellationToken)), devolva o erro {Entidade}NaoEncontrada se não existir, chame o método de domínio e salve uma vez. Quando o domínio precisa da hora atual, injete TimeProvider no handler e passe relogio.GetUtcNow() ao método — nunca DateTime.Now.

Leitura — Dapper com IConexaoProvider, nunca DbSet/LINQ do EF:

using Automatiza.Modules.Catalogo.Domain.Entities.Trilha;

namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.ObterTrilhaPorId;

public class ObterTrilhaPorIdQueryHandler(IConexaoProvider conexaoProvider)
    : Handler<ObterTrilhaPorIdRequest, Result<ObterTrilhaPorIdResponse>>
{
    public override async Task<Result<ObterTrilhaPorIdResponse>> OnHandle(ObterTrilhaPorIdRequest request, CancellationToken cancellationToken)
    {
        await using var conexao = conexaoProvider.Criar();

        var trilha = await conexao.QuerySingleOrDefaultAsync<ObterTrilhaPorIdResponse>(
            new CommandDefinition(ObterTrilhaPorIdQuery.Sql, new { request.Id }, cancellationToken: cancellationToken));

        if (trilha is null)
            return TrilhaErrors.TrilhaNaoEncontrada.Format(request.Id.ToString());

        return trilha;
    }
}

Listagem paginada (ListarTrilhasQueryHandler): ver a skill backend-criar-consulta-dapper.

Os handlers são registrados sozinhos pelo AddCustomMediator(...) do Program.cs (o assembly do módulo precisa estar lá). Não registre handler à mão.

4. Endpoint

namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.CriarTrilha;

public class CriarTrilhaEndpoint : IUseCaseEndpoint
{
    public static RouteHandlerBuilder Map(IEndpointRouteBuilder app)
    {
        return app.MapPost("/admin/tracks", async (
            CriarTrilhaRequest request,
            [FromServices] IDispatcher dispatcher,
            CancellationToken cancellationToken) =>
        {
            var result = await dispatcher.Send(request, cancellationToken);

            return result.TryGetValue(out var criada)
                ? Results.Created($"/api/v1/admin/tracks/{criada.Id}", criada)
                : Results.BadRequest(result.Errors);
        })
        .WithSummary("Criar trilha")
        .Produces<CriarTrilhaResponse>(StatusCodes.Status201Created);
    }
}

Detalhes (rotas, Produces, autorização): skill backend-criar-endpoint-minimal-api.

5. Registro no ModuleConfiguration

O ModuleConfiguration.cs de cada módulo registra um único grupo para o módulo inteiro. No Catálogo:

endpoints
    .MapDocumentedGroup(PrefixUri, "Catálogo", GruposDeDocumentacao.Catalogo)
    .MapEndoints("Automatiza.Modules.Catalogo.Features", typeof(ModuleConfiguration).Assembly);

Um caso de uso novo normalmente não exige registro adicional — MapEndoints descobre o IUseCaseEndpoint pelo namespace.

6. Mapeamento e migration

Se o caso de uso cria agregado novo ou muda colunas, crie/ajuste o mapeamento e gere a migration (skill backend-criar-mapping-ef-core). Caso de uso só de leitura não gera migration.

7. Regras obrigatórias

  • O Handler orquestra; o Domínio decide — nunca coloque regra de negócio no handler (nem cálculo de XP, nota ou aprovação).
  • Sempre retorne Result.Fail(...)/erro tipado — nunca lance exceção para erro de negócio.
  • Escrita: um único SaveChanges por operação, só no DbContext do próprio módulo — ele já é a transação.
  • Nunca leia ou grave tabela de outro módulo; para falar com outro módulo, use a interface pública dele.
  • O que vale ponto (gabarito, correção, tempo assistido, certificado) é decidido no servidor; o request nunca traz nota, XP ou resultado calculado pelo cliente, e a resposta nunca leva gabarito.
  • Endpoint retorna conforme a semântica (Ok, Created, NoContent, NotFound); erro de negócio retorna BadRequest — ver AGENTS.md → CQRS.
  • Requests e Responses são record; cada caso de uso tem os seus (não compartilhe entre slices).

Regras gerais: AGENTS.md.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall