VdcScore/docs/05_PROGRESSO_E_ESTADO_ATUAL.md

05 - Progresso e Estado Atual

Important

Atenção IA (Agentes): Este documento é um Registo de Progresso (Living Document). É obrigação de qualquer agente de IA atualizar este ficheiro quando terminar um conjunto de tarefas com sucesso, ou caso depare-se com impedimentos, de forma a passar contexto às próximas iterações.

O que já foi alcançado (Abril 2026)

O projeto sofreu um esforço significativo na estabilização do Scraper e da interface de utilizador (UI) na App Android.

No Scraper (Java)

• Foi configurada a extração das Tabelas Classificativas (Standings) e cálculos otimizados para garantir dados precisos baseados na AFAVCD.
• Alterou-se o endpoint de single-matchday para aceder a todo o calendário de época via /jorneys (plural endpoint).
• O Scraper está apto a recolher não apenas golos, mas todos os campos vitais de um Game (Jornada, Data, Campo de Jogo e URL do Relatório), enviando-os corretamente para o Firebase.
• Iniciaram-se trabalhos nos perfis dos jogadores (PlayersScraper), com mapeamento e sincronização em curso.
• A Estrutura da class GameMatch.java foi mantida inalterada de forma propositada durante o refactoring, para não quebrar a compatibilidade com a schema na base de dados antiga.

Na App Android (VdcScore)

• Interface de "Jornadas" (Matchday Display UI) revista: Desenvolvidos cartões com visual premium (Card-style).
• O Data Binding no MatchesAdapter foi resolvido para corretamente mapear e mostrar: nomes das equipas, logótipos descarregados com Glide, os resultados (scores) e a informação de agendamento do jogo (Data/Campo).
• A Autenticação de base (Logins e Registos) está implementada usando o Firebase Authentication.

Tarefas A Decorrer / Próximos Passos (TODOs)

• Testes Finais de UI: Garantir que quando campos opcionais do Scraper regressam a null (e.g. jogos ainda não marcados não têm Data), a interface Android se comporta silenciosamente (sem Crashes e apresentando estado vazio "A Definir").
• PlayersScraper: Completar e validar a ingestão do plantel de todos os clubes para exibir no Menu de "Equipas".
• Sistema Offline: Melhorar a experiência da App permitindo o Firebase cache persistir localmente quando não há acesso à Internet.
• Push Notifications: Quando um Scraper deteta um fim de jogo (mudança de estado para 'Terminado'), explorar a hipótese de chamar Firebase Cloud Messaging para notificar a App Android.

Relatório de Intervenção (Desenvolvimento do Scraper de Jornadas)

Progresso Geral Atualizado Foi implementada a funcionalidade para recolher e sincronizar detalhadamente todas as jornadas e jogos correspondentes. O scraper agora processa todas as informações de jornadas da API da AFAVCD e insere esses dados na Firebase Realtime Database na respetiva estrutura (jornadas/{escalao}/{id_jornada}/{id_jogo}), alimentando os ecrãs da App Android.

O que foi criado ou adicionado

• Adicionada lógica de extração e formatação ao StandingsScraper.java para sincronizar as jornadas com a Firebase.
• Inclusão dos campos de cada jogo com compatibilidade direta com a classe Match.java da App Android (home_nome, away_nome, home_logo, away_logo, home_golos, away_golos, data, hora, campo, matchReportUrl).

O que foi modificado e porquê

• Modificou-se o ficheiro StandingsScraper.java para reaproveitar a chamada de rede que já estava a ser feita ao endpoint /jorneys. Optou-se por introduzir a lógica neste ficheiro, pois ele já contém o mapeamento de clubes (clubesMap) necessário para buscar nomes e logótipos através dos IDs das equipas (homeId, awayId).

O que foi removido

• Nenhuma funcionalidade ou ficheiro foi removido nesta intervenção. Apenas foi expandida a capacidade do código já existente.

Relatório de Intervenção (Desenvolvimento do Scraper de Melhores Marcadores)

Progresso Geral Atualizado Foi implementada a funcionalidade para extrair e sincronizar a lista de melhores marcadores (Top Scorers) para os escalões de Seniores e Juniores. Conseguimos identificar o endpoint de "disciplina" da AFAVCD que contém os golos marcados por cada jogador em cada jornada, permitindo calcular o total acumulado.

O que foi criado ou adicionado

• Novo Modelo: Criado TopScorer.java no projeto Scraper para espelhar a estrutura esperada pela App Android.
• Novo Scraper: Criado TopScorersScraper.java que:
  • Identifica e acede ao endpoint: https://api.afavcd.pt/teams/modality/{id}/season/33/discipline.
  • Soma os golos de cada jogador através de todas as jornadas.
  • Faz o mapeamento automático para o nome e logo do clube usando o ID da equipa.
  • Ordena os marcadores por número de golos.
  • Sincroniza os dados com o Firebase em marcadores/{escalao}.

O que foi modificado e porquê

• A estrutura de classes do projeto Scraper foi expandida para incluir modelos de dados mais granulares (TopScorer), facilitando a manutenção e a paridade com o projeto Android.

O que foi removido

• Nenhuma funcionalidade foi removida.

Relatório de Intervenção (UI das Jornadas - App Android)

Progresso Geral Atualizado As jornadas agora são carregadas e exibidas corretamente e de forma ordenada na aplicação Android (Ecrã Jornadas / GalleryFragment). A visualização dos detalhes dos jogos foi também enriquecida permitindo o acesso à "Ficha de Jogo" oficial quando o link é fornecido pelo Scraper.

O que foi criado ou adicionado

• Adicionado o botão "Ficha de Jogo" no layout item_match.xml dos cartões de jogo.
• Implementada a propriedade matchReportUrl (e respetivos getters/setters) no Model Match.java garantindo a correspondência @PropertyName com os dados guardados na Firebase.
• Criada a intenção (Intent) no MatchesAdapter.java para abrir o browser nativo e consultar o relatório da partida.

O que foi modificado e porquê

• O GalleryFragment.java foi modificado para ordenar as jornadas matchdaysList de forma numérica (Collections.sort). Isto resolveu o problema em que o Firebase devolvia as chaves ordenadas de forma alfabética (1, 10, 11, 2, 3...) baralhando a navegação sequencial no ecrã.
• O MatchesAdapter.java foi modificado para suportar a alternância de visibilidade do novo botão de "Ficha de Jogo" consoante a disponibilidade do URL na base de dados.

O que foi removido

• Nenhuma funcionalidade ou ficheiro foi removido nesta iteração, focando-se unicamente em enriquecer a experiência do utilizador.

Relatório de Intervenção (Ecrã de Melhores Marcadores - App Android)

Progresso Geral Atualizado Foi criada toda a infraestrutura base e a interface visual para acomodar os "Melhores Marcadores" da liga (Top Scorers). O ecrã foi integrado na navegação principal da App e está desenhado para alternar rapidamente entre Seniores e Juniores. Está agora perfeitamente alinhado com a árvore do Firebase melhores_marcadores/{escalao}, aguardando que o Scraper Java inicie a injeção de dados.

O que foi criado ou adicionado

• Novo Model TopScorer.java com as propriedades exatas esperadas (playerName, playerPhoto, clubName, clubLogo, goals, position).
• Interface de layout (fragment_top_scorers.xml e item_top_scorer.xml) com um design em formato de cartões premium, suportando a exibição da posição do jogador, foto circular do perfil, logótipo do clube e a contagem de golos.
• TopScorersFragment.java e TopScorersAdapter.java que tratam a lógica de escuta em tempo real do Firebase e fazem a ordenação pela quantidade de golos de forma descendente.
• Menu de navegação foi alargado (mobile_navigation.xml, activity_main_drawer.xml, MainActivity.java e strings.xml) para incluir a opção lateral visível e interativa "Melhores Marcadores".

O que foi modificado e porquê

• Adicionado ao ficheiro themes.xml o estilo auxiliar ShapeAppearanceOverlay.App.CornerSize50Percent para garantir que as fotos dos jogadores (ShapeableImageView) fiquem perfeitamente circulares sem recurso a bibliotecas externas complexas.

O que foi removido

• Nenhuma funcionalidade removida. O código consiste numa extensão (feature) 100% nova.

Relatório de Intervenção (Implementação da Secção de Notícias)

Progresso Geral Atualizado Foi implementado um novo sistema de notícias que permite à app exibir as novidades mais recentes da AFAVCD. O sistema é composto por um scraper que recolhe os dados da API oficial e uma nova interface na app Android que apresenta as notícias num formato de resumo visualmente apelativo (cards), seguindo a estética solicitada.

O que foi criado ou adicionado

• No Scraper (Java):
  • Criado o modelo News.java.
  • Criado o NewsScraper.java que extrai dados de https://api.afavcd.pt/news/1 e sincroniza-os com o nó noticias na Firebase.
• Na App Android:
  • Adicionado o modelo News.java com mapeamento para os campos da Firebase.
  • Desenvolvido o layout item_news.xml com um design premium (Imagens de destaque, títulos em cyan e resumos limpos).
  • Criado o fragment_news.xml com um cabeçalho personalizado e uma RecyclerView.
  • Implementados o NewsAdapter.java (com limpeza de tags HTML do corpo da notícia) e o NewsFragment.java.
  • Integrada a nova secção no menu lateral (activity_main_drawer.xml), no grafo de navegação (mobile_navigation.xml) e configurada como destino de topo na MainActivity.java.

O que foi modificado e porquê

• strings.xml: Adicionada a label "Notícias" para internacionalização e uso no menu.
• MainActivity.java: Atualizada a AppBarConfiguration para incluir o novo fragmento de notícias, garantindo que o menu lateral esteja disponível em vez do botão de retrocesso.
• mobile_navigation.xml e activity_main_drawer.xml: Atualizados para permitir a navegação para a nova funcionalidade.

O que foi removido

• Nenhuma funcionalidade foi removida. O projeto foi expandido com uma nova feature.

Relatório de Intervenção (Ecrã de Ínicio / Notícias)

Progresso Geral Atualizado As notícias foram promovidas a ecrã principal (Ínicio) da aplicação. A secção de notícias é agora a primeira a ser apresentada quando o utilizador abre a app e o ecrã foi sujeito a uma profunda revisão estética para apresentar uma leitura mais imersiva, moderna e limpa (Cards formatados).

O que foi criado ou adicionado

• Nenhuma class nova foi criada. O foco foi estritamente na reorganização e melhoria de UI e UX.
• Adicionada lógica de parsing e formatação da data no NewsAdapter.java para converter strings ISO complexas ("2026-04-20T20:05:01.000Z") em datas humanamente legíveis e agradáveis (e.g. 20 abr 2026).

O que foi modificado e porquê

• strings.xml: A string @string/menu_news foi alterada de "Notícias" para "Ínicio" para corresponder à semântica desejada pelo utilizador para o ecrã de entrada.
• mobile_navigation.xml: O startDestination foi alterado de nav_home (Classificações) para nav_news (Ínicio/Notícias) para garantir que a app abre logo nas notícias recentes.
• activity_main_drawer.xml: O item nav_news foi movido para o topo do menu para respeitar a hierarquia visual.
• fragment_news.xml: Removido o cabeçalho cyan ("Notícias"), integrando perfeitamente a lista com a barra de ferramentas nativa da aplicação Android.
• item_news.xml: Completamente redesenhado. Adicionado um layout MaterialCardView com cantos mais arredondados, margens e sombras otimizadas, e melhorada drasticamente a hierarquia tipográfica (cores neutras premium #1F2937 e #4B5563, e a imagem a ocupar a largura total do card).

O que foi removido

• O cabeçalho estático no ficheiro fragment_news.xml foi removido para promover um design mais nativo e espaçoso.