Documentação

O Buscador de Academias é uma funcionalidade pública que permite a qualquer pessoa encontrar academias de Jiu-Jitsu próximas à sua localização. Funciona como um "Google do Jiu-Jitsu": o usuário digita seu CEP ou usa o GPS do dispositivo, e o sistema retorna uma lista de academias ordenadas por distância, com nome, endereço e botão de contato via WhatsApp.

Esta funcionalidade é a porta de entrada pública do aplicativo, acessível pela rota /buscador. Qualquer pessoa — logada ou não — pode buscar academias próximas sem barreira de cadastro.

• Descoberta: Alunos em viagem ou mudança encontram academias próximas sem precisar buscar no Google.
• Conexão direta: O botão de WhatsApp elimina atrito — o aluno fala diretamente com a academia em um clique.
• Visibilidade: Academias cadastradas ganham exposição pública gratuita, atraindo novos alunos.
• Dois cenários: GPS para viajantes e CEP para planejamento de mudança.

Fluxo de busca:

1. Usuário acessa a rota /buscador (página pública) e vê a barra de busca.
2. Escolhe entre GPS (botão com mira) ou CEP (campo de texto).
3. Se GPS: navegador captura latitude/longitude do dispositivo.
4. Se CEP: ViaCEP obtém o endereço, Nominatim geocodifica para coordenadas.
5. Backend busca academias com coordenadas, calcula distância (Haversine), retorna ordenado.
6. Frontend exibe cards com nome, endereço, distância e botões de contato.

Fluxo de cadastro (Admin):

1. Admin preenche o card "Dados da Academia" no painel de Configurações.
2. Ao salvar, o sistema geocodifica o endereço automaticamente (Nominatim).
3. Latitude/longitude são salvos no AppSettings.
4. A academia aparece no buscador público imediatamente.

Para Administradores:

1. Acesse Configurações → card "Dados da Academia".
2. Preencha CEP, endereço, número, bairro, cidade, estado.
3. Preencha WhatsApp e site (opcional).
4. Clique "Salvar" — geocodificação é automática.

Para Usuários:

1. Acesse a rota /buscador (página pública do aplicativo).
2. Digite o CEP ou clique no botão GPS.
3. Veja os resultados ordenados por distância.
4. Clique em "WhatsApp" para contato direto.

Plano original:

• Criar formulário separado de "Configuração de Localização".
• Criar entidade AcademyLocation para coordenadas.
• Desenvolver função de busca geoespacial.
• Desenvolver nova interface minimalista.

Plano aplicado (otimizado):

• Reutilização do card "Dados da Academia" existente — sem formulário novo.
• Campos latitude/longitude adicionados à entidade AppSettings — sem entidade nova.
• Geocodificação automática no salvamento — admin não faz nada extra.
• Função geocodeAddress (admin) + findNearbyAcademies (pública).
• Módulo compartilhado geocode.ts (ViaCEP + Nominatim + Haversine).
• Componente AcademySearch integrado à página Buscador (antiga Landing Page).
• Rota /landing agora redireciona (301) para /buscador.
• Componente EntryGuard na raiz / decide destino: autenticado → /dashboard, não autenticado → /buscador.
• Todos os links internos atualizados de /landing para /buscador.

Camada de dados:

• Entidade AppSettings: campos latitude e longitude (number).
• RLS: read para admin (próprio tenant) e user (tenant do professor); busca pública usa asServiceRole.

Camada backend:

• base44/shared/geocode.ts — geocodeWithNominatim, lookupCepBackend, buildAddressQuery, haversineDistance.
• base44/functions/geocodeAddress/entry.ts — admin-only, geocodifica e salva lat/long.
• base44/functions/findNearbyAcademies/entry.ts — pública, busca por GPS ou CEP.

Camada frontend:

• AcademySearch.jsx — barra de busca + resultados.
• AcademyCard.jsx — card de academia.
• Buscador.jsx — página pública (antiga Landing.jsx).
• EntryGuard.jsx — roteamento inteligente na raiz /.

APIs externas (gratuitas):

• ViaCEP (viacep.com.br) — lookup de CEP.
• Nominatim/OpenStreetMap — geocodificação de endereço.

Segurança:

• findNearbyAcademies retorna apenas dados públicos — nenhum tenant_id ou dado sensível.
• geocodeAddress é admin-only (verifica user.role === 'admin').
• asServiceRole usado apenas no backend, nunca no frontend.

Performance:

• Coordenadas pré-calculadas no salvamento — busca só calcula Haversine (O(1) por academia).
• Resultados limitados a 50 por padrão (até 100).
• APIs externas chamadas apenas quando necessário.
• Loading states para feedback imediato.

Objetivo: Tornar o Buscador a porta de entrada padrão do aplicativo, alinhando o funil de aquisição com a primeira tela que qualquer visitante vê.

Como funciona o EntryGuard:

1. Componente EntryGuard montado na rota raiz /.
2. Lê o estado de autenticação (useAuth) e aguarda a sessão carregar.
3. Autenticado → redireciona para /dashboard.
4. Não autenticado → redireciona para /buscador.
5. Decisão client-side, instantânea, sem chamada extra ao backend.

Mapeamento de rotas:

• / → EntryGuard (decide destino).
• /buscador → Buscador.jsx (página pública, sem auth).
• /landing → redirecionamento 301 para /buscador (compatibilidade).
• Rotas de painel → ProtectedRoute (exige autenticação).