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.

FileKindSize
SKILL.mdskill md8.1 KB
---
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`.
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: 472kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall