VdcScore/memories/repo/vdcscore-overview.md

VdcScore - Visão Geral do Projeto

O que é

App Android (Java) chamada VdcScore que exibe dados de campeonatos locais de futebol (AFAVCD) em tempo real.

Arquitetura

• Scraper Java (projeto separado scrapper/): Aplicaçãp autónoma que faz scraping da API HTML/JSON da AFAVCD, processa os dados e escreve no Firebase Realtime Database.
• Firebase Realtime Database: Centraliza todos os dados (Single Source of Truth).
• App Android VdcScore: Cliente de leitura que consome os dados do Firebase em tempo real via ValueEventListener.

Estrutura de Dados no Firebase

Senior/
  standings/     - Tabelas classificativas por clube
  journeys/      - Jornadas com jogos (homeTeam, awayTeam, scores, date, field, matchReportUrl)
  players/       - Plantéis de cada equipa
  melhores_marcadores/ - Top scorers (Seniores e Juniores)
  noticias/      - Notícias da AFAVCD
  live_matches/  - Jogos preparados para acompanhamento em direto
Users/
  UID/           - Utilizadores (email, favoriteClub)

Componentes Principais da App Android

• models/: Club, Game/Match, Jornada, Player, TopScorer, News
• ui/: Fragments + ViewModels para cada secção
  • home/ - Classificações
  • gallery/ - Jornadas/Jogos (MatchesAdapter, Match.java)
  • livegames/ - Jogos em direto
  • clubs/ - Equipas/Plantéis
  • top_scorers/ - Melhores Marcadores
  • news/ - Notícias (ecrã principal por defeito)
  • definicoes/ - Definições
• Autenticação: LoginActivity, CriarContaActivity, RecuperarPasswordActivity, MainActivity

Tecnologias

• Scraper: JSoup, GSON, Firebase Admin SDK, Gradle
• Android: ViewBinding, Glide, Firebase Auth, Firebase Realtime Database, Navigation Component, RecyclerView

Estado Atual

• Scraper de Standings/Jornadas: ✅ Funcional
• Scraper de Melhores Marcadores: ✅ Funcional
• Scraper de Notícias: ✅ Funcional
• Scraper de Plantéis (PlayersScraper): 🔄 Em desenvolvimento
• UI Jornadas: ✅ Cartões premium com Glide, Ficha de Jogo
• UI Melhores Marcadores: ✅ Ecrã completo
• UI Notícias: ✅ No ecrã principal (Ínicio)
• UI Classificações: ✅ Funcional
• Autenticação Firebase: ✅ Implementada
• Live Matches: ✅ Preparação de jogos futuros

Tarefas Pendentes

• Completar PlayersScraper (plantéis completos)
• Sistema Offline (Firebase cache local)
• Push Notifications (FCM)
• Testes finais de UI para campos opcionais null

Convenções Importantes

• Models Android devem bater certo com models Scraper (nomes de atributos)
• Valores numéricos vêm como String da API - fazer parse para Integer
• Campos opcionais podem vir vazios (matchReportUrl, data) - UI deve lidar com null
• Chaves Firebase em minúsculas (standings, journeys, players)
• Serviços: service-account.json nunca no version control