initial

analise_codebase.md

@@ -0,0 +1,50 @@
+# 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.