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.
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:
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 Sqldentro deinternal 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çaJOINentre 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 porDefaultTypeMap.MatchNamesWithUnderscores = true(já ligado emAddDataBase). Não precisa de aliasAS. - Parâmetros sempre nomeados (
@Id,@Publico,@Limite); nunca concatenação ou interpolação de valores. CommandDefinitioncomcancellationToken.- Conexão por
IConexaoProvider.Criar()comawait using(o Dapper abre a conexão sozinho). - Enum filtrado em coluna
smallint: envie o parâmetro comoshort((short?)request.Publico), senão o PostgreSQL comparasmallintcomintegere não usa o índice. Na leitura, o enum: shortcasa direto. - Datas
timestamptzchegam emDateTimeOffsetpeloDateTimeOffsetTypeHandler(já registrado). Sempre UTC; a conversão para o horário de Brasília só acontece onde a regra pede (ver skilldotnet-timezone). - Paginação com
LIMIT @Limite OFFSET @Deslocamento, ordenação determinística (ORDER BY+ desempate porid) eCOUNT(*)com o mesmo filtro no mesmo comando (QueryMultipleAsync), devolvendoPaginatedResponse<T>(Automatiza.SeedWork.Models). Limite o tamanho da página com uma constante no request. - Somente
SELECT. NenhumINSERT,UPDATE,DELETEou 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:
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:
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.
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 |