quiz-ius/analise_codebase.md

Análise do Codebase do Quiz

Documento de Definições e Informações Pertinentes

Esta é uma visão geral sobre a arquitetura e os escopos do projeto "Quiz".

1. Tecnologias Utilizadas

• HTML5, CSS3, JavaScript: Linguagens base do projeto.
• AngularJS (v1.x): Framework lógico principal da aplicação.
• Ionic Framework (v1): Utilizado para construção da interface (UI) e navegação.
• Local Storage: Usado para persistência local dos dados (pontuações e estatísticas do jogo) diretamente no navegador.
• http-server (Node.js): Utilizado para servir o projeto em ambiente local (via o script Iniciar_Quiz.bat).

2. Estrutura de Diretórios e Arquivos

• /audio: Contém os arquivos de som do jogo (acertos, erros, transições, vitórias).
• /css & /lib: Arquivos de folhas de estilo (custom.css, utilitários do Ionic e transições) além das bibliotecas base.
• /dados: Diretório crucial contendo os JSONs de parametrização:
  • config.json: Arquivo de sistema "whitelabel". Ele define paletas de cores (injetadas via propriedades customizadas no CSS), textos de botões, logotipo e background.
  • perguntas.json: A integridade dos dados do jogo (lista de perguntas e suas respectivas alternativas com a indicação da resposta correta).
• /img: Recursos estáticos e assets visuais em geral (ex: fundo-patrocinador.png, logo-ius.png).
• /js: Coração lógico da aplicação (Angular).
  • app.js: Iniciação do módulo principal Angular (app), manipulação e registro de eventos principais (ex: tratamento de plugins caso rode via Cordova, diretivas utilitárias).
  • controllers.js: Arquivo central onde está a lógica do Quiz (pageCtrl). Gerencia a busca do JSON, injeção das variáveis de paleta do tema, embaralhamento das perguntas (shuffleArray), cálculo da pontuação, manipulações do DOM de suporte e a persistência de estatísticas no LocalStorage.
  • routes.js, services.js, directives.js: Arquivos auxiliares que formam o ecossistema AngularJS dessa aplicação.
• index.html: Ponto de entrada que carrega os scripts, o bundle do Ionic AngularJS e inicia o componente <ion-nav-view>.
• Iniciar_Quiz.bat: Batch script de conveniência no Windows destinado a iniciar rapidamente um servidor web local (http-server -p 8080) no diretório, evitando problemas de política de CORS ao tentar acessar os recursos JSON locais diretamente no navegador.

3. Funcionamento e Ciclo de Vida

1. Inicialização do Tema e Dados: Quando o módulo controlador do layout base carrega, ele chama dados/config.json usando $http.get e mapeia dinamicamente essas propriedades em Variáveis CSS (--cor-fundo-principal, etc) diretamente na raiz (document.documentElement). Em paralelo, carrega perguntas.json.
2. Ciclo de Partida (S.startGame):
   • Uma lista de 5 perguntas e suas alternativas é separada e rigorosamente embaralhada de forma aleatória e sem repetição.
   • O jogador interage respondendo; o sistema aplica transições visuais dinâmicas usando CSS para trocar de pergunta, reproduz o áudio correspondente (acerto/erro) e pontua na variável local da sessão ($scope.quiz.pontuacao).
3. Avaliação (S.chamaResultado):
   • Após 5 perguntas, os resultados são avaliados.
   • O placar define as condições de vitória (>= 3 acertos) com comportamentos especiais para 100% de acerto (5 de 5).
4. Persistência de Dados (S.salvarDadosJogos): Toda vitória, derrota, total de acertos, jogos e erros são persistidos na chave quiz_dadosjogos do localStorage, garantindo que um F5 (atualização da página) não elimine o histórico de partidas do dispositivo que roda a aplicação.

4. Customização e Autoria (Whitelabel)

A natureza whitelabel da aplicação permite uma personalização completa sem necessidade de programar. Veja abaixo como alterar:

1. Textos e Textos de Interface: O arquivo dados/config.json (objeto "tema") controla títulos, botões e as mensagens de "Parabéns" ou "Derrota".
2. Cores: Integrado via Variáveis CSS no :root. Alterando o objeto "cores" no config.json, é possível modificar instantaneamente:
   • Fundo principal e fundo secundário/escuro.
   • Cores de texto primárias e títulos.
   • Cores de destaque nos botões e nas alternativas (A, B, C, D).
3. Imagens e Assets Visuais: As chaves "fundo_padrao" e "logo_patrocinador" no "config.json" determinam os caminhos para o logo e fundo do app (arquivos estes normalmente localizados na pasta img/).
4. Perguntas e Respostas: Integradas no dados/perguntas.json. Suportam a definição do texto da pergunta e um array de respostas, com um flag booleano "correta": true para validar a escolha do jogador.

5. Conclusão da Análise

A base de código trata-se de um sistema do tipo "Quiz" focado no ambiente Web Local, migrado ou estruturado a partir de um projeto em Cordova/Ionic. Possui uma base solidamente parametrizável (whitelabel) através do seu config.json, sendo inteiramente adaptável para outras marcas, fundos e perguntas, sem necessitar de alteração direta ou recombilação do código fonte HTML/JS. Em vez de backend estruturado, usa armazenamento flexível e offline via LocalStorage.