2026-01-18_cpf-cep-gps-foundation
Documentação KOLOS
← Índice docs Início

2026-01-18_cpf-cep-gps-foundation

🧭 Contexto

Você pediu três pilares para o cadastro e evolução do KOLOS:

  • Cadastro com CPF para reduzir perfis fake e dar base para regras de nível.
  • Endereço por CEP com preenchimento automático (só número manual).
  • Preparar o sistema para geolocalização (GPS), para filtros “perto de mim” e descoberta.

✅ Decisão

  1. CPF (anti-fake / base de identidade)
  • Adicionamos coluna cpf (11 dígitos) em users, com unique.
  • O Value Object Kolos\Shared\ValueObjects\Cpf já valida dígitos verificadores.
  • Observação: CPF não comprova posse sozinho; validação forte (KYC) pode ser adicionada depois (ex.: verificação por provedor/Serpro). Aqui garantimos formato + unicidade.
  1. CEP (autocompletar endereço)
  • Criamos um cliente ViaCepClient (integração simples com ViaCEP) e um endpoint GET /api/cep/{cep} para o front (Livewire/Alpine) consumir e preencher rua/bairro/cidade/UF.
  1. GPS / Geolocalização
  • Iniciamos suporte de lat/lng no módulo Venue (campos latitude/longitude), para receber coordenadas do navegador (quando UI existir) ou geocoding posterior.
  • Por enquanto usamos decimal(10,7) (sem PostGIS). Se/quando precisarmos de busca geoespacial avançada, avaliamos PostGIS.

🛠️ Passos (comandos via Sail)

  • sail artisan migrate
  • sail artisan test

🧪 Validação

  • GET http://localhost/api/cep/01001000 deve retornar JSON com logradouro/bairro/cidade/uf.
  • users.cpf aceita apenas 11 dígitos e é único (por DB).
  • Tabela venues existe com campos de endereço e latitude/longitude.

📦 Impacto

  • Base preparada para cadastro “realista” (CPF + endereço por CEP) e features de localização.
  • Próximo passo natural: implementar Player/Venue flows (Onda 2) consumindo GET /api/cep/{cep}.