Skip to content

biellts/universidade-automatiza / .claude/skills/backend-criar-validator-assincrono

backend-criar-validator-assincrono

Verified

Cria um Validator para validações assíncronas que requerem acesso ao banco de dados. Use este skill quando solicitado a criar validações de existência, unicidade ou consistência que precisam consultar o banco antes de executar um command.

FileKindSize
SKILL.mdskill md4.7 KB
---
name: backend-criar-validator-assincrono
description: Cria um Validator para validações assíncronas que requerem acesso ao banco de dados. Use este skill quando solicitado a criar validações de existência, unicidade ou consistência que precisam consultar o banco antes de executar um command.
---

Para criar um Validator assíncrono neste projeto, siga o processo abaixo:

## 1. Quando usar um Validator

Use um `Validator` separado quando as validações precisam de acesso ao banco:
- Verificar se um registro do **próprio módulo** existe (ex.: a trilha informada existe)
- Verificar consistência entre entidades do próprio módulo

Para validações puramente síncronas de domínio (formato, obrigatoriedade, tamanho), use os VOs e o factory do agregado.

**Unicidade não se garante no Validator:** consultar e depois inserir tem corrida entre requisições concorrentes. A garantia é uma restrição única no banco (`HasIndex(...).IsUnique()` + migration), como a restrição do extrato de XP em (user_id, origem, origem_id). O Validator pode antecipar uma mensagem amigável, mas o handler ainda precisa tratar a violação da restrição como erro de negócio (ou como operação idempotente, conforme o requisito).

**Dado de outro módulo** não se valida com SQL no schema dele: use a interface pública do outro módulo. Nunca `JOIN` entre schemas.

## 2. Localização

Crie o arquivo em:
```
src/apps/Automatiza.Modules.{Modulo}/Features/{Entidade}s/UseCases/{NomeDoCasoDeUso}/{X}Validator.cs
```

O Catálogo ainda não tem Validator. O exemplo abaixo é **ilustrativo**: um caso de uso futuro do Catálogo que precisa confirmar que a trilha existe antes de gravar (`{CasoDeUso}` e `{X}Request` são placeholders).

## 3. Estrutura do Validator

A leitura do Validator é Dapper com `IConexaoProvider` e SQL qualificado pelo schema, nunca `DbSet`/LINQ do EF Core:

```csharp
namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.{CasoDeUso};

public class {CasoDeUso}Validator(IConexaoProvider conexaoProvider)
{
    private const string SqlTrilhaExiste = """
        SELECT EXISTS (SELECT 1 FROM catalogo.trilhas WHERE id = @TrilhaId)
        """;

    public async Task<Result> ValidarAsync({CasoDeUso}Request request, CancellationToken cancellationToken)
    {
        await using var conexao = conexaoProvider.Criar();

        var existe = await conexao.ExecuteScalarAsync<bool>(
            new CommandDefinition(SqlTrilhaExiste, new { request.TrilhaId }, cancellationToken: cancellationToken));

        if (!existe)
            return TrilhaErrors.TrilhaNaoEncontrada.Format(request.TrilhaId.ToString());

        return Result.Ok();
    }
}
```

## 4. Uso no Handler

Injete o Validator no Handler via construtor primário e chame-o antes da lógica de domínio:

```csharp
public class {CasoDeUso}CommandHandler(CatalogoDbContext contexto, {CasoDeUso}Validator validator)
    : Handler<{CasoDeUso}Request, Result<{CasoDeUso}Response>>
{
    public override async Task<Result<{CasoDeUso}Response>> OnHandle({CasoDeUso}Request request, CancellationToken cancellationToken)
    {
        // 1. Pré-condições no banco (Dapper)
        var validacao = await validator.ValidarAsync(request, cancellationToken);
        if (!validacao.Success)
            return Result<{CasoDeUso}Response>.Fail(validacao.Errors);

        // 2. Domínio decide
        // var resultado = {Agregado}.Criar(...) ou agregado.{Acao}(...)

        // 3. Persistência: um único SaveChanges no DbContext do módulo
        await contexto.SaveChangesAsync(cancellationToken);

        return new {CasoDeUso}Response(...);
    }
}
```

## 5. Registro no DI

O Validator **não** é descoberto pelo `AddCustomMediator` (que só registra handlers): registre-o como `Scoped` no `Add{Modulo}Module` do `ModuleConfiguration.cs`:

```csharp
public static IServiceCollection AddCatalogoModule(this IServiceCollection services)
{
    services.AddModuloDbContext<CatalogoDbContext>(CatalogoDbContext.NomeSchema);
    services.AddScoped<{CasoDeUso}Validator>();

    return services;
}
```

## 6. Regras obrigatórias

- O Validator **nunca** contém regra de negócio — apenas verifica pré-condições de dados.
- Consulta via `IConexaoProvider.Criar()` + Dapper, com `CommandDefinition`, parâmetros nomeados e `cancellationToken`.
- SQL só no schema do próprio módulo, tabela qualificada (`catalogo.trilhas`).
- Dado de tenant (quando existir): filtre por `tenant_id` no SQL — o Dapper não passa pelo filtro global do EF.
- Retorne `Result.Ok()` ao final quando todas as validações passam.
- Encerre na primeira falha (fail-fast), a menos que o requisito peça todos os erros de uma vez.
- Nunca lance exceção — use `Result.Fail(...)`/erro tipado.

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