Mapa SMCC — guia do projeto

Catálogo digital dos espaços do Santa Mônica Clube de Campo: lista de locais com busca, filtros e ficha de cada espaço. Um painel administrativo permite à secretaria manter tudo sem um desenvolvedor.

1. O que é

Um site público de uma única página (/) e um painel administrativo (/admin).

Stack

2. Onde está cada coisa

mapa-smcc/
├── app/
│   ├── Console/Commands/OtimizarImagens.php   comando mapa:otimizar-imagens
│   ├── Filament/
│   │   ├── Resources/Locals/                  CRUD de locais (formulário e tabela)
│   │   ├── Resources/Categorias/              CRUD de categorias
│   │   ├── Resources/MapVersions/             plantas do clube + âncora geográfica
│   │   └── Widgets/                           ResumoClube, LocaisMaisVistos (dashboard)
│   ├── Http/Controllers/
│   │   ├── MapaController.php                 página /, ficha /locais/{slug}
│   │   └── MetricaController.php              contador de visualizações
│   ├── Models/                                Local, Categoria, LocalHorario, LocalView, MapVersion, User
│   ├── Observers/                             LocalObserver (calcula lat/lng), MapVersionObserver (1 planta ativa), ...
│   ├── Services/
│   │   ├── MapaService.php                    monta o payload (cache de 1 h)
│   │   └── OtimizadorImagem.php               conversão para WebP
│   └── Support/GoogleMapsLocal.php            formata/valida as coordenadas do admin
├── config/mapa.php                            contato, logo, origem padrão, reservas  ← ajustes do clube
├── database/
│   ├── migrations/                            estrutura das tabelas
│   ├── seeders/ClubeSeeder.php                dados iniciais (locais, categorias, planta)
│   └── database.sqlite                        banco local (SQLite)
├── docs/
│   ├── api-locais.md                          documentação da API pública
│   └── guia-do-projeto.html                   este guia
├── public/                                    o que o navegador acessa diretamente
│   ├── css/app.css                            design do site (tokens de cor no topo, :root)
│   ├── js/app.js                              busca, filtro, ficha, compartilhar, beacon
│   ├── storage/ → storage/app/public          link simbólico criado por storage:link
│   └── index.php                              entrada da aplicação
├── resources/views/
│   ├── components/layouts/app.blade.php       layout base (fontes, CSS, JS)
│   ├── locais/index.blade.php                 página principal
│   ├── locais/partials/                       header, card, ficha, footer
│   └── filament/mapa-picker.blade.php         seletor visual da planta (ver seção 11)
├── routes/web.php                             todas as rotas do site
├── storage/app/public/                        fotos, planta, logo (o que vai para o ar)
├── tests/Feature/                             AdminTest, MapaTest, MetricaTest
├── .env                                       configuração do ambiente (não versionar)
└── .env.example                               modelo do .env

Tabela de respostas rápidas

3. Como funciona

Uma visita à página principal percorre este caminho:

Por que não tem AJAX na busca?

Os 47 locais chegam junto com a página, dentro de um <script type="application/json" id="mapa-payload">. Filtrar é só alternar hidden nos cards. Isso mantém o site rápido no 4G do clube e indexável pelo Google.

Ficha do local

A ficha é um <dialog> nativo. Ao abrir, a URL muda para /locais/{slug} (sem recarregar), e a ficha só conta como visualização se ficar aberta por 2 segundos. O envio é um sendBeacon para POST /locais/{slug}/view, limitado a 60 chamadas por minuto por IP.

Cache e atualização

O payload do banco fica em cache por 1 hora. Os observers de Local, Categoria, LocalHorario e MapVersion apagam essa chave ao salvar, então a secretaria vê a mudança na hora. Já o que vem de config/mapa.php é mesclado a cada requisição, de fora do cache.

Imagens

Cada foto vira duas versões WebP: 1200 px para a ficha e 400 px para o card. A planta vira WebP de 2400 px. O comando precisa ser rodado sempre que uma foto for trocada pelo painel.

4. Configurar

Requisitos

• PHP 8.3 com as extensões usuais do Laravel (incluindo pdo, gd, mbstring, sqlite3 ou mysql).
• Composer 2.
• Node.js (opcional: o site não usa npm).

Passo a passo (ambiente novo)

1. Copiar o ambiente: copy .env.example .env (no Linux/macOS: cp).
2. Gerar a chave: php artisan key:generate.
3. Ajustar o .env (tabela abaixo).
4. Instalar dependências PHP: composer install.
5. Criar o banco e os dados: php artisan migrate --seed. O seeder é idempotente: pode rodar de novo sem duplicar nada.
6. Criar o link da pasta pública: php artisan storage:link.
7. Otimizar as imagens: php artisan mapa:otimizar-imagens.
8. Criar um usuário do painel: veja a seção 8.

Variáveis do .env que importam

Ajustes do clube: config/mapa.php

Como config/ não dispara os observers, mudanças aqui aparecem na hora. Se o servidor usar php artisan config:cache, rode php artisan config:clear depois de editar.

5. Rodar

Desenvolvimento local

php artisan serve            # http://localhost:8000
php artisan test            # roda os testes

• Site: http://localhost:8000
• Painel: http://localhost:8000/admin

Se mudar a porta, mude o APP_URL junto. Senão as fotos quebram.

Em produção

O site responde em https://servicos2.santamonica.rec.br/mapa-online-smcc/. O script test_deploy_check.sh (na raiz) faz uma checagem rápida: página principal, redirecionamento de /mapa-online-smcc e o título no HTML.

Comandos do dia a dia

6. Os dois números: x/y e latitude/longitude

Um local tem duas coordenadas de natureza diferente. Entender a diferença é a chave para o resto do sistema:

A conversão (x/y → lat/lng)

Implementada em MapVersion::coordenada(). A planta ativa define o centro e a extensão:

latitude  = base_lat + (50 - y) / 100 × span_lat
longitude = base_lng + (x - 50) / 100 × span_lng

Com a planta atual (base_lat -22.741900, base_lng -47.312600, span_lat 0.0072, span_lng 0.0087): o centro da planta (x=50, y=50) cai exatamente em -22.741900, -47.312600. O y cresce para baixo na tela, por isso o sinal é invertido na latitude.

Experimente

Digite um x e um y e veja o ponto na planta e a latitude/longitude correspondente. Use os mesmos valores do banco.

As duas coordenadas do Google Maps

O campo "Coordenadas" no formulário do local é outra coisa. Ele guarda o link google_maps_url, usado no botão "Como chegar" da ficha. Não é o mesmo par que x/y e não atualiza a latitude/longitude automaticamente. O formato esperado é latitude, longitude (com vírgula), e o sistema monta o link de rota a pé a partir dele.

7. Como ajustar

Adicionar um local

1. No painel, em Locais, clique em Criar.
2. Digite o nome. O slug (usado na URL) é preenchido sozinho. Ele não muda depois de criado, porque links compartilhados dependem dele.
3. Escolha a categoria e preencha resumo, destaque e descrição.
4. Em Horários, adicione as faixas (ex.: "Terça a sexta" / "10h às 20h").
5. Envie a foto e rode php artisan mapa:otimizar-imagens.

Desativar sem apagar

Desligue o toggle ativo. O local some da lista, mas o histórico de visualizações é preservado. A página /locais/{slug} dele passa a responder 404.

Mudar a ordem da lista

Campo ordem (menor aparece primeiro) ou arraste na tabela do painel.

Trocar a planta do clube

1. Em Plantas do clube, envie a nova imagem.
2. Marque ativa. As outras são desativadas automaticamente (só pode haver uma).
3. Ajuste a âncora (latitude/longitude do centro e extensões em graus) se necessário. Mudar isso move o destino de "Como chegar" de todos os locais que dependem de x/y.
4. Rode php artisan mapa:otimizar-imagens.

Mudar cores e fontes

Tokens de cor no topo de public/css/app.css, dentro de :root (--brand: #0F2091, --ink, etc.). A fonte é Plus Jakarta Sans, carregada do Google Fonts no layout resources/views/components/layouts/app.blade.php.

8. Painel administrativo

Acesso em /admin. Só entra quem tem admin = true na tabela users. Sem isso, o login é aceito mas a conta recebe 403.

Criar um usuário

php artisan tinker --execute="App\Models\User::create(['name'=>'Secretaria','email'=>'secretaria@exemplo.com','password'=>bcrypt('uma-senha-forte'),'admin'=>true]);"

Seções do painel

9. API e rotas

A documentação completa do JSON, com exemplos e campos, está em docs/api-locais.md. Não há endpoint de escrita: edição só pelo painel.

10. Testes e manutenção

php artisan test

Testes em tests/Feature/: AdminTest (acesso ao painel), MapaTest (página, API, coordenadas, cache, idempotência do seeder) e MetricaTest (contador de visualizações).

Rotina sugerida

• Backup diário do banco e de storage/app/public.
• Após trocar foto ou planta: php artisan mapa:otimizar-imagens.
• Após atualizar código no servidor: php artisan migrate --force e php artisan config:clear.
• Logs em storage/logs/. Com APP_DEBUG=false, erros aparecem só no log.

11. Atenção: divergências encontradas

Ao montar este guia, comparei o que o README descreve com o código. Estes pontos merecem ação:

12. Pendências antes do go-live

Lista do README, para acompanhar:

• Trocar a senha do usuário provisionado
• Substituir os telefones por local pelos ramais reais
• Preencher endereço, posição e foto das 33 churrasqueiras
• Definir o canal de reserva (reservas.url)
• Corrigir a âncora geográfica da planta, ou manter a geolocalização desligada
• Conferir com a secretaria os textos e horários
• HTTPS (sem TLS, não há geolocalização nem compartilhamento nativo)
• Definir APP_URL de produção
• Auto-hospedar a fonte e fechar a política de conteúdo (hoje vem do Google Fonts)
• Backup diário do banco e de storage/app/public
• Páginas 404 e 500 com a identidade do clube
• Resolver as divergências da seção 11