biellts/universidade-automatiza / .claude/skills/backend-criar-validator-assincrono
backend-criar-validator-assincrono
VerifiedCria 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
SKILL.md
View on GitHub---
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`.
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 |