FutStats — acompanhamento de futebol
PWA em HTML, CSS e JavaScript para jogos do dia, partidas ao vivo, ligas, times, jogadores, comparação, escalações e alertas Web Push. Dados esportivos vêm da API-Football por proxies do servidor; cobertura e disponibilidade variam por competição.
Desenvolvimento
Use Node.js 22 ou 24. Copie .env.example para .env.local e preencha as variáveis somente no arquivo local.
npm ci
npm run dev
npm run build
Servidor local: http://127.0.0.1:4173. Serve public/ e executa os handlers reais, sem agendar alertas. Consultas exigem banco configurado: sem a chave de serviço ou RPCs, retornam 503 por segurança.
npm test executa testes Node e PostgreSQL embarcado (PGlite), sem alterar o banco remoto. npm run check verifica sintaxe, compatibilidade dos scripts globais, assets, ícones, dependências e alguns padrões conhecidos de segredos (não substitui um scanner completo). O build executa ambas as verificações e gera somente assets públicos em dist/. A CI repete esse build a cada push/PR.
Arquitetura
| Diretório | Responsabilidade |
|---|
public/app.js | Inicialização, rotas e atualização periódica |
public/js/ | Cache, modelos, notificações, acessibilidade e telas por domínio |
public/css/, public/style.css | Estilos e acessibilidade |
public/sw.js | Cache offline limitado aos assets conhecidos |
api/ | Proxies esportivos, imagens, notícias, assinaturas e cron |
lib/ | Limites distribuídos, HTTP limitado e serviços de push |
supabase/ | Migrações, RLS, reservas de envio e agendador |
tests/ | Regressões de frontend/backend e SQL |
docs/prototypes/ | Protótipos de referência, fora da publicação |
Scripts do navegador usam defer em ordem explícita no HTML; não são módulos ES. Lógica pura também é importável pelos testes. O navegador não acessa tabelas diretamente nem recebe chave de serviço. Não adicione fallback anônimo para erros do servidor.
Configuração
| Variável do servidor | Uso |
|---|
FOOTBALL_API_KEY | Credencial API-Sports/API-Football |
SUPABASE_URL | URL do projeto |
SUPABASE_SERVICE_ROLE_KEY | RPCs e tabelas protegidas; nunca enviar ao navegador |
RATE_LIMIT_SECRET | Segredo aleatório independente, >=32 caracteres, para HMAC do IP |
FOOTBALL_DAILY_BUDGET | Teto global diário de chamadas pagas; padrão conservador: 100 |
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT | Chaves Web Push e contato do operador |
CRON_SECRET | Segredo aleatório >=32 caracteres para autorização do cron |
A chave VAPID pública é entregue por GET /api/subscribe. SUPABASE_ANON_KEY não é necessária ao aplicativo corrigido. Preserve o par VAPID existente para não invalidar assinaturas.
Teto sugerido nesta instalação: 7.000 chamadas, com reserva frente à cota de 7.500 verificada em 10/09/2026. Ajuste se o plano mudar. O contador usa dias UTC; o ciclo do fornecedor pode ser diferente. Limites por IP e orçamento global são compartilhados entre instâncias por operações atômicas no banco. Falha no controle retorna 503; limite excedido retorna 429.
Publicação e alertas
Siga docs/operations.md antes de publicar. A ordem de migração, segredos e agendador importa. vercel.json define build, pasta dist, duração do cron e cabeçalhos de segurança.
Supabase Cron é o único agendador automático previsto. O workflow GitHub é somente manual e exige o secret CRON_SECRET. O header x-vercel-cron não autentica chamadas. Alterações de assinaturas exigem suas chaves correspondentes; erros de banco não são sucesso.
Reservas persistentes evitam envios duplicados do mesmo evento ao dispositivo. Entrega com resultado incerto não é repetida automaticamente: evita duplicatas, mas pode perder um alerta. Polling, cotas, cobertura e disponibilidade dos provedores impedem prometer entrega imediata ou exatamente uma vez.
Interpretação dos dados
Comparações usam uma heurística, não probabilidades calibradas ou previsões garantidas. H2H é considerado quando disponível; o bônus de mando pertence à pontuação interna, não equivale a seis pontos percentuais. Notas estimadas e mapas simulados são estimativas/ilustrações, não medições oficiais. Transmissões sugeridas devem ser confirmadas no canal ou serviço.
O frontend atualiza telas ativas periodicamente e reaproveita consultas em andamento. Jogadores por partida e escalações têm cache curto; dados estáveis podem ter validade maior. Falhas e dados ausentes são apresentados na interface. Cache offline não fornece novos resultados ao vivo.
Dados locais
Favoritos, preferências, escalações e configurações são persistidos no navegador. Limpar os dados do site remove o estado local. Não há login de usuário. Web Push persiste endpoint, chaves técnicas, favoritos e preferências no Supabase. Desligar alertas utiliza exclusão autenticada da assinatura; apagar só o armazenamento local não garante excluir o registro remoto.
O controle de tráfego armazena identidade HMAC derivada do IP, não IP bruto. Contadores vencidos são limpos incrementalmente; registros de deduplicação são limpos após 30 dias durante seu uso. O operador deve definir política de retenção e tratamento de pedidos dos usuários.
Backup anterior às correções
backups/pre-correcoes-20260909-212041.tar.gz contém o estado completo anterior, incluindo .git, dependências e .env.local.
SHA256: B2BC873BF0E1A4FEA3806633C66083B08F1EF629D08C7EAE46146E4B07791342.
Contém credenciais: mantenha privado, fora do Git e deploy. Para recuperar, extraia em uma pasta separada e compare antes de substituir arquivos. Este backup não contém o banco remoto. Não reative segredos revogados ao restaurar arquivos.
