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.

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:

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:

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:

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: 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