[openaudit-search-api] Implementar scoring/confidence + explanation (Matcher) com regras determinísticas

[4lessandrodev]

Repo: openaudit-search-api

Tags: priority:high type:feature area:matching

Visão geral

Evitar caixa-preta: o match deve ser explicável e consistente, reduzindo falso positivo e risco reputacional.

Contexto

A seleção de entidade é a parte mais frágil do sistema. O contrato exige confidence e explanation para transparência. No MVP, o matcher pode ser simples e determinístico.

Descrição

Implementar src/modules/matching/Matcher que:

• Produz confidence (0..1) baseado em sinais determinísticos:
  • match exato do normalized_name (peso alto)
  • match por tokens (peso médio)
  • match em aliases (peso médio)
  • bônus por contexto (UF/cargo/ano) se disponível
• Produz explanation[] listando sinais aplicados (ex.: "match_exact_name", "alias_hit", "uf_match").

Regras:

• Explicações devem ser curtas e técnicas.
• Evitar heurísticas opacas.

Adicionar testes:

• match exato vs parcial
• alias
• ordenação por score

Impacto

Aumenta defensabilidade do projeto e reduz erro de identificação. Melhora UX e confiança no sistema.

Referências

• https://github.com/OpenAudit-Brasil/openaudit-search-api/blob/main/README.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/ROADMAP.md

Definição de pronto

• Matcher implementado com scoring determinístico
• Explanation sempre presente e coerente
• Testes cobrindo comportamento de ranking e sinais
• Nenhum termo acusatório introduzido