[openaudit-search-api] Implementar CatalogClient (SQLite read-only + FTS5): consulta por texto e filtros

[4lessandrodev]

Repo: openaudit-search-api

Tags: priority:high type:feature area:catalog

Visão geral

Criar o módulo de acesso ao catálogo canônico (artefato gerado pelo openaudit-entity-catalog) para retornar candidatos de forma eficiente.

Contexto

O search-api não constrói o catálogo; ele consome um catalog.sqlite com FTS5. Precisamos de queries eficientes, read-only, com paginação, e retornando dados mínimos para desambiguação.

Descrição

Implementar src/modules/catalog/ com:

• Leitura de CATALOG_DB_PATH (SQLite) em modo read-only.
• Query FTS5 pelo termo normalizado:
  • buscar por display_name, normalized_name e aliases.
• Filtros (se disponíveis no schema): context_uf, context_year, context_role.
• Paginação: limit (max 25), offset.
• Retornar campos necessários ao schema Candidate.

Regras:

• Não logar queries brutas.
• Manter conexão e preparar statements (performance).
• Respeitar limites de paginação e rate limit (anti-enumeração).

Impacto

Habilita o core do MVP: busca rápida e consistente. Sem isso o /search vira um stub e a UI não evolui.

Referências

• https://github.com/OpenAudit-Brasil/openaudit-search-api/blob/main/README.md
• https://github.com/OpenAudit-Brasil/About/blob/main/ROADMAP.md
• https://github.com/OpenAudit-Brasil/About/blob/main/METHODOLOGY.md
• https://github.com/OpenAudit-Brasil/About/blob/main/RISK_POLICY.md
• https://github.com/OpenAudit-Brasil/About/blob/main/DATA_SOURCES.md

Definição de pronto

• CatalogClient implementado com queries FTS5 e paginação
• Config via env (CATALOG_DB_PATH e CATALOG_META_PATH se aplicável)
• Testes de unidade para queries (com DB de teste pequeno)
• Sem dependência de internet/serviços externos