biellts/universidade-automatiza / .claude/skills/backend-criar-consulta-dapper
backend-criar-consulta-dapper
VerifiedCria a consulta de leitura de um caso de uso com Dapper e SQL explícito sobre o PostgreSQL da aplicação, qualificado pelo schema do módulo. Use quando solicitado a criar listagem, detalhe, busca, filtro ou paginação.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
SKILL.md
View on GitHub---
name: backend-criar-consulta-dapper
description: Cria a consulta de leitura de um caso de uso com Dapper e SQL explícito sobre o PostgreSQL da aplicação, qualificado pelo schema do módulo. Use quando solicitado a criar listagem, detalhe, busca, filtro ou paginação.
---
# Criar consulta Dapper
Leitura não passa pelo agregado nem pelo EF: SQL explícito, visível na revisão, executado com Dapper sobre a conexão de `IConexaoProvider`.
## Local
Dentro do slice do caso de uso:
```text
src/apps/Automatiza.Modules.{Modulo}/Features/{Entidade}s/UseCases/{CasoDeUso}/
{X}Request.cs ← record : IQuery<Result<T>>
{X}QueryHandler.cs ← abre a conexão e executa o SQL
{X}Endpoint.cs
{X}Response.cs
{X}Query.cs ← só o SQL (internal static class com const string Sql)
```
## Regras
- SQL em `public const string Sql` dentro de `internal static class {X}Query`, com raw string literal (`"""`).
- Tabelas **sempre qualificadas pelo schema do módulo** (`catalogo.trilhas`). Nunca leia tabela de outro schema nem faça `JOIN` entre schemas de módulos diferentes — use a interface pública do outro módulo.
- Colunas em `snake_case`; o Dapper casa com as propriedades PascalCase do record por `DefaultTypeMap.MatchNamesWithUnderscores = true` (já ligado em `AddDataBase`). Não precisa de alias `AS`.
- Parâmetros sempre nomeados (`@Id`, `@Publico`, `@Limite`); nunca concatenação ou interpolação de valores.
- `CommandDefinition` com `cancellationToken`.
- Conexão por `IConexaoProvider.Criar()` com `await using` (o Dapper abre a conexão sozinho).
- Enum filtrado em coluna `smallint`: envie o parâmetro como `short` (`(short?)request.Publico`), senão o PostgreSQL compara `smallint` com `integer` e não usa o índice. Na leitura, o enum `: short` casa direto.
- Datas `timestamptz` chegam em `DateTimeOffset` pelo `DateTimeOffsetTypeHandler` (já registrado). Sempre UTC; a conversão para o horário de Brasília só acontece onde a regra pede (ver skill `dotnet-timezone`).
- Paginação com `LIMIT @Limite OFFSET @Deslocamento`, ordenação determinística (`ORDER BY` + desempate por `id`) e `COUNT(*)` com o mesmo filtro no mesmo comando (`QueryMultipleAsync`), devolvendo `PaginatedResponse<T>` (`Automatiza.SeedWork.Models`). Limite o tamanho da página com uma constante no request.
- Somente `SELECT`. Nenhum `INSERT`, `UPDATE`, `DELETE` ou DDL: escrita é pelo agregado; schema é pela migration.
- Dado de tenant (quando o módulo Empresas existir): o filtro por `tenant_id` é obrigatório no SQL — o Dapper não passa pelo filtro global do EF Core.
- Nenhum registro no DI: a classe de SQL é estática e o handler é registrado pelo `AddCustomMediator`.
## Exemplo real (Catálogo — `ListarTrilhas`)
`ListarTrilhasQuery.cs`:
```csharp
namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.ListarTrilhas;
internal static class ListarTrilhasQuery
{
public const string Sql = """
SELECT COUNT(*)
FROM catalogo.trilhas
WHERE (@Publico IS NULL OR publico = @Publico);
SELECT id, titulo, publico, funcao_alvo
FROM catalogo.trilhas
WHERE (@Publico IS NULL OR publico = @Publico)
ORDER BY titulo, id
LIMIT @Limite OFFSET @Deslocamento;
""";
}
```
`ListarTrilhasQueryHandler.cs`:
```csharp
namespace Automatiza.Modules.Catalogo.Features.Trilhas.UseCases.ListarTrilhas;
public class ListarTrilhasQueryHandler(IConexaoProvider conexaoProvider)
: Handler<ListarTrilhasRequest, Result<PaginatedResponse<ListarTrilhasItemResponse>>>
{
public override async Task<Result<PaginatedResponse<ListarTrilhasItemResponse>>> OnHandle(ListarTrilhasRequest request, CancellationToken cancellationToken)
{
var tamanho = Math.Clamp(request.PageSize, 1, ListarTrilhasRequest.TamanhoMaximoPagina);
var pagina = Math.Max(request.PageIndex, 0);
await using var conexao = conexaoProvider.Criar();
// smallint no banco: o parâmetro precisa ir como short, senão o PostgreSQL compara smallint com integer sem índice.
var parametros = new
{
Publico = (short?)request.Publico,
Limite = tamanho,
Deslocamento = pagina * tamanho
};
using var leitor = await conexao.QueryMultipleAsync(
new CommandDefinition(ListarTrilhasQuery.Sql, parametros, cancellationToken: cancellationToken));
var total = await leitor.ReadSingleAsync<long>();
var itens = await leitor.ReadAsync<ListarTrilhasItemResponse>();
return new PaginatedResponse<ListarTrilhasItemResponse>(pagina, tamanho, total, itens);
}
}
```
Detalhe por Id (`ObterTrilhaPorId`): `QuerySingleOrDefaultAsync<ObterTrilhaPorIdResponse>` com `new { request.Id }`; `null` vira `TrilhaErrors.TrilhaNaoEncontrada.Format(request.Id.ToString())`, que o endpoint devolve como `404`.
```csharp
internal static class ObterTrilhaPorIdQuery
{
public const string Sql = """
SELECT id, titulo, descricao, publico, funcao_alvo, criado_em
FROM catalogo.trilhas
WHERE id = @Id
""";
}
```
## Teste
Todo SQL novo tem teste de integração via `ApplicationFactory` (Testcontainers PostgreSQL, migrations aplicadas na subida), chamando o endpoint. O banco é compartilhado pela classe de teste: crie os dados com um sufixo único (`Guid.NewGuid().ToString("N")[..8]`) e filtre por ele — nunca dependa de tabela vazia. Ver `TrilhasTests.Listar_FiltrandoPorPublico_TrazSoAsDoPublicoOrdenadasPorTitulo`. Regras gerais: `AGENTS.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |