[openaudit-search-api] Implementar endpoint GET /search completo (SearchResponse) + validação do contrato

[4lessandrodev]

Repo: openaudit-search-api

Tags: priority:high type:feature area:api area:search

Visão geral

Entregar o endpoint principal do MVP: busca retorna lista de candidatos com confidence e explanation, além de metadados do catálogo.

Contexto

A Fase 1 do roadmap depende deste endpoint para desambiguação humana. Deve ser rápido, auditável e não acusatório.

Descrição

Implementar GET /search conforme core-contracts:

• Entradas:
  • q obrigatório, limit/offset opcionais.
• Processamento:
  • normalizar query, gerar hash.
  • consultar CatalogClient (SQLite FTS5).
  • montar candidates[].
  • preencher catalog com name/version/snapshot_id/source (lidos do catalog_meta.json).
• Saída:
  • JSON SearchResponse com query.normalized, query.hash, catalog, candidates.
• Headers:
  • X-Request-Id, X-Catalog-Version, X-Cache.

Regras:

• confidence e explanation devem existir para cada candidato (mesmo que simples no MVP).
• Não incluir linguagem acusatória.
• Não incluir query.raw por padrão.

Impacto

Viabiliza UI e seleção de candidato. Sem isso, o ecossistema não sai do papel.

Referências

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

Definição de pronto

• /search implementado e retornando SearchResponse
• Response valida contra JSON Schema (em test/dev)
• Headers retornados corretamente
• Testes de integração cobrindo casos: termo comum, termo sem resultado, paginação