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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.1 KB |
SKILL.md
View on GitHub---
name: backend-criar-use-case
description: 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:
```csharp
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:
```csharp
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.
```csharp
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:
```csharp
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
```csharp
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:
```csharp
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`.
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: 472k | 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: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |