biellts/universidade-automatiza / .claude/skills/backend-criar-use-case
backend-criar-use-case
VerifiedCria 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 implementandoICommand<Result<T>>(escrita) ouIQuery<Result<T>>(leitura){X}CommandHandler.cs(escrita) ou{X}QueryHandler.cs(leitura) — herdaHandler<TRequest, TResponse>{X}Endpoint.cs— implementaIUseCaseEndpoint{X}Response.cs— record de resposta (listagem:{X}ItemResponse.cs){X}Query.cs— SQL Dapper (somente leitura; verbackend-criar-consulta-dapper){X}Validator.cs— validações com acesso ao banco (opcional; verbackend-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
SaveChangespor 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 retornaBadRequest— verAGENTS.md→ CQRS. - Requests e Responses são
record; cada caso de uso tem os seus (não compartilhe entre slices).
Regras gerais: AGENTS.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |