🧭 Guardrails de Geocoding (OpenCage)

Contexto

Usuários podem perceber que o ponto exibido no Google Maps “não bate” com o endereço digitado.

As causas mais comuns são:

• 🌍 Geocoding por texto: quando o GPS não está disponível, usamos geocoding forward. Se a consulta for ambígua ou pouco precisa, o provedor pode retornar um ponto aproximado.

Nota: a opção de GPS no cadastro foi removida (ver mudança específica), então o cadastro depende do endereço para obter latitude/longitude.

Decisão

• Adicionar um limite mínimo de confiança do OpenCage (confidence) para aceitar resultados.
• Melhorar a UX do cadastro para deixar explícito que GPS = localização atual.

Alternativa descartada (por ora):

• Implementar seleção manual em mapa (mais esforço e UI complexa).

Implementação

• OpenCage client passa a rejeitar resultados com confidence abaixo de um limiar configurável.
• Configuração exposta via OPENCAGE_MIN_CONFIDENCE (default 7).
• UI do cadastro explica o comportamento do GPS e oferece botão para limpar coordenadas.

Passos (configuração)

• Defina (opcional) no .env:
  • OPENCAGE_MIN_CONFIDENCE=7

Validação

• Conclua o cadastro: o sistema usa OpenCage para preencher latitude/longitude quando faltarem.
• Se o ponto ainda ficar impreciso, verifique se o endereço tem número e CEP corretos.

Impacto

• Ajustes em OpenCageGeocodingClient para aplicar guardrail por confiança.
• Ajustes na tela de cadastro para explicitar GPS e permitir “Limpar GPS”.