📋 Descrição

Melhora a estratégia de geolocalização do endpoint /api/cep/v2/{cep} sem alterar o contrato da API.

Hoje a busca de coordenadas no Nominatim/OpenStreetMap fazia apenas uma tentativa com state, city e, quando disponível, street. Nesta mudança:

• a consulta também passa a incluir postalcode quando o CEP está disponível
• quando a primeira tentativa com logradouro não encontra um resultado utilizável, é feita uma segunda tentativa sem street, mantendo city, state e postalcode
• a lógica de seleção do melhor resultado continua priorizando CEP exato e, como fallback, prefixo de 5 dígitos do CEP
• a documentação do CEP V2 foi atualizada para refletir que o CEP também é usado para refinar a busca
• foi adicionado teste automatizado para validar a segunda tentativa sem logradouro

Observação:
Esse é o primeiro PR que faço em projetos open source, já trabalho com desenvolvimento há alguns anos mas minha empresa não segue um fluxo tão natural seguido na maioria, então se cometer erros ou ter pulado etapas, agradeço pela orientação para eu aprender.

🎯 Tipo de Mudança

• 🐛 Correção de bug (mudança que corrige um problema)
• ✨ Nova funcionalidade (mudança que adiciona funcionalidade)
• 💥 Breaking change (correção ou funcionalidade que causa quebra de compatibilidade)
• 📝 Documentação (mudanças apenas em documentação)
• ♻️ Refatoração (mudança que não corrige bug nem adiciona funcionalidade)
• ⚡ Performance (mudança que melhora performance)
• ✅ Testes (adiciona ou corrige testes)
• 🔧 Configuração (mudanças em configuração ou build)

⚠️ Checklist de Compatibilidade (CRÍTICO)

• ✅ Não remove campos de respostas de API existentes
• ✅ Não renomeia campos de respostas de API existentes
• ✅ Não muda tipos de dados de campos existentes (string → number, etc.)
• ✅ Não muda o formato de URLs de endpoints existentes
• ✅ Não muda códigos de status HTTP de endpoints existentes
• ✅ Se fez mudanças incompatíveis, criei uma nova versão (v2, v3, etc.)

📚 Checklist de Documentação

• ✅ Atualizei ou criei documentação OpenAPI em /pages/docs/doc/
• ✅ Documentação inclui exemplos de requisição e resposta
• ✅ Documentação está em português
• ✅ Atualizei README.md se necessário
• ✅ N/A - Mudanças não requerem documentação

🧪 Checklist de Testes

• ✅ Criei ou atualizei testes E2E
• ✅ Todos os testes passam localmente (npm test)
• ✅ Teste de CORS funciona corretamente
• ✅ Testei casos de erro (404, 400, 500, etc.)
• ✅ Testei casos de sucesso
• ✅ N/A - Mudanças não requerem testes

💻 Checklist de Código

• ✅ Código segue os padrões do projeto (ESLint + Prettier)
• ✅ Executei npm run fix antes de commitar
• ✅ Não adicionei dependências desnecessárias ou pesadas
• ✅ Código não expõe credenciais ou informações sensíveis
• ✅ Validei todos os inputs de usuário
• ✅ Tratei erros apropriadamente
• ✅ Usei Conventional Commits

🚀 Checklist de Performance e Custos

• ✅ Não adicionei processamento pesado que aumenta custos
• ✅ Usei cache quando apropriado
• ✅ Minimizei chamadas a APIs externas
• ✅ Considerei impacto em rate limits de APIs externas
• ✅ Testei performance em casos de alto volume

🔍 Como Testar

1. Faça as requisições:
   • GET /api/cep/v2/05010000
   • GET /api/cep/v2/06655770
   • GET /api/cep/v2/06655780
2. Verifique:
   • o payload continua compatível
   • location continua presente
   • casos com coordenadas continuam funcionando
   • a busca usa o CEP para refinar a geolocalização quando disponível

📸 Screenshots (se aplicável)

📎 Issues Relacionadas

Refs #784
Refs #741

📝 Notas Adicionais

⚠️ Para Revisores

Pontos de Atenção Críticos:

1. Compatibilidade: Verifique se há quebra de contrato de API
2. Documentação: Confirme que está atualizada e completa
3. Testes: Valide cobertura de casos de sucesso e erro
4. Performance: Avalie impacto em custos e velocidade
5. Segurança: Verifique validação de inputs e exposição de dados

Lembre-se: BrasilAPI serve milhares de desenvolvedores e empresas importantes. Mudanças devem ser cuidadosamente avaliadas para garantir confiabilidade e zero downtime.