diff --git a/.gitignore b/.gitignore index 85e3640..a86aee7 100644 --- a/.gitignore +++ b/.gitignore @@ -73,13 +73,6 @@ web_modules/ # Yarn Integrity file .yarn-integrity -# dotenv environment variable files -.env -.env.development.local -.env.test.local -.env.production.local -.env.local - # parcel-bundler cache (https://parceljs.org/) .cache .parcel-cache diff --git a/docs/docs/plataforma/arquitetura/coleta-eventos.md b/docs/docs/plataforma/arquitetura/coleta-eventos.md new file mode 100644 index 0000000..6863b15 --- /dev/null +++ b/docs/docs/plataforma/arquitetura/coleta-eventos.md @@ -0,0 +1,166 @@ +--- +sidebar_position: 10 +title: "Coleta de Eventos (Analytics)" +--- + +# Coleta de Eventos com Plausible + +Sistema de rastreamento de eventos educacionais através do Plausible Community Edition, permitindo análise de padrões de aprendizagem sem invasão de privacidade. + +## Fluxo de coleta + +```mermaid +graph TD + A["Atividade de Programação
(ex: PuzzleGame)"] -->|Usuário executa código| B["GameStateContext
(finalizeWithSuccess/Failure)"] + + B -->|Dispara evento| C["trackEvent
plausible.js"] + + C -->|Lê variáveis de ambiente| D{Qual ambiente?} + + D -->|Development| E["VITE_PLAUSIBLE_API
http://localhost/api/event"] + D -->|Production| F["VITE_PLAUSIBLE_API
plausible.mtst.tec.br"] + + E --> G["Fetch com timeout 5s
(AbortController)"] + F --> G + + G -->|Success| H["Evento registrado
no Plausible"] + + G -->|Timeout/Error| I["console.error
App continua"] + + H --> J["Dashboard Plausible
Análise de métricas"] +``` + +## Componentes principais + +### 1. **GameStateContext** (`contexts/GameStateContext.jsx`) + +Gerencia o ciclo de execução das atividades e dispara eventos: + +```javascript +// Quando a atividade tem sucesso +const finalizeWithSuccess = () => { + trackEvent('Activity Success', { + activity: gameConfig.gameId, + phase: currentPhase, + blocks: currentBlockCount, + attempts: attemptCount, // Total de tentativas + failures: failureCount, // Total de falhas + durationSeconds: Math.round((Date.now() - phaseStartTime) / 1000) + }); +}; + +// Quando a atividade falha +const finalizeWithFailure = () => { + trackEvent('Activity Failure', { + activity: gameConfig.gameId, + phase: currentPhase, + blocks: currentBlockCount, + error: failureMessage + }); +}; +``` + +Também rastreia: +- **Tentativas**: `attemptCount` incrementado a cada execução +- **Falhas**: `failureCount` incrementado a cada erro +- **Tempo**: `phaseStartTime` registrado ao mudar de fase + +### 2. **Serviço Plausible** (`services/plausible.js`) + +Abstração para envio de eventos com timeout e tratamento de erro: + +```javascript +const sendEvent = (payload) => { + const controller = new AbortController(); + const timeout = setTimeout(() => controller.abort(), 5000); + + fetch(PLAUSIBLE_API, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(payload), + signal: controller.signal, + }) + .catch((e) => console.error('Plausible error:', e)) + .finally(() => clearTimeout(timeout)); +}; +``` + +**Características**: +- ✅ Timeout de 5 segundos (não bloqueia a aplicação) +- ✅ Requisição não-bloqueante (não-await) +- ✅ Tratamento de erro silencioso (log no console, app continua) +- ✅ Configurável via variáveis de ambiente + +### 3. **Rastreamento de Page View** (`App.jsx`) + +Dispara `trackPageView` quando a rota muda: + +```javascript +useEffect(() => { + trackPageView(location.pathname); +}, [location.pathname]); +``` + +Registra visitas às páginas principais da plataforma. + +## Estrutura de dados + +### Payload enviado ao Plausible + +```json +{ + "domain": "myapp-dev", // ou https://decoda.mtst.tec.br (prod) + "url": "http://localhost/#/atividades/programacao/puzzle", + "referrer": "http://localhost/#/atividades", + "screenWidth": 1920, + "name": "Activity Success", + "props": { + "activity": "programacao/puzzle", + "phase": "3", + "blocks": "5", + "attempts": "4", + "failures": "2", + "durationSeconds": "127" + } +} +``` + +## Configuração por ambiente + +| Variável | Development | Production | +|----------|-------------|-----------| +| `VITE_PLAUSIBLE_API` | `http://localhost/api/event` | Variável de ambiente (prod) | +| `VITE_PLAUSIBLE_DOMAIN` | `myapp-dev` | `https://decoda.mtst.tec.br` | +| **Arquivo** | `app/.env` | `app/.env.production` | + +## Tratamento de falhas + +Se o servidor de analytics não estiver disponível: + +1. ✅ **Timeout (5s)**: Requisição é automaticamente cancelada +2. ✅ **Erro de conexão**: Capturado pelo `.catch()` e logado no console +3. ✅ **Sem impacto**: A aplicação continua funcionando normalmente +4. ✅ **Usuário não vê nada**: Erro não é exibido na UI + +## Privacidade e LGPD + +O Plausible CE foi escolhido porque: + +- 🔒 **Sem cookies**: Não usa rastreamento persistente +- 🔒 **Sem IP**: Não armazena endereço IP completo +- 🔒 **Dados educacionais apenas**: Coleta apenas métricas de uso da aplicação +- 🔒 **Sem rastreamento cross-site**: Não segue usuários fora da aplicação +- 📜 **Conformidade LGPD**: Alinhado com legislação brasileira de proteção de dados +- 🔓 **Software livre**: Código aberto, auditável, hospedado localmente + +## Fluxo de dados + +``` +Atividade → GameStateContext → trackEvent() → plausible.js → + ↓ + Fetch com timeout + ↓ + Plausible API ← erro/timeout → console.error (não bloqueia) + ↓ + Dashboard Plausible → Análise pedagógica +``` diff --git a/docs/docs/releases/v1.0.0.md b/docs/docs/releases/v1.0.0.md index a706ca9..63985ab 100644 --- a/docs/docs/releases/v1.0.0.md +++ b/docs/docs/releases/v1.0.0.md @@ -5,7 +5,7 @@ title: "1.0.0 — Lançamento inicial" # 1.0.0 — Lançamento inicial -**Data de lançamento:** 07/07/2026 +**Data de lançamento:** 07/05/2026 Esta é a versão inicial de lançamento público da plataforma Decoda. Ela consolida o desenvolvimento da trilha de letramento digital, da trilha de programação visual por blocos e do laboratório de Python, além da infraestrutura de implantação e da documentação. diff --git a/docs/docs/releases/v1.1.0.md b/docs/docs/releases/v1.1.0.md index 4bef4d8..2700c3b 100644 --- a/docs/docs/releases/v1.1.0.md +++ b/docs/docs/releases/v1.1.0.md @@ -5,7 +5,7 @@ title: "1.1.0" # 1.1.0 -**Data de lançamento:** 14/07/2026 +**Data de lançamento:** 14/05/2026 --- diff --git a/docs/docs/releases/v1.2.0.md b/docs/docs/releases/v1.2.0.md new file mode 100644 index 0000000..d24257b --- /dev/null +++ b/docs/docs/releases/v1.2.0.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 1 +title: "1.2.0" +--- + +# 1.2.0 + +**Data de lançamento:** 13/06/2026 + +--- + +## Adicionado + +### Analytics com Plausible Community Edition + +Implementação de rastreamento de eventos e métricas de uso da plataforma através do [Plausible Community Edition](https://plausible.io/). Os dados coletados permitem entender como os estudantes interagem com as atividades, identificar gargalos de aprendizagem e melhorar continuamente a experiência educacional. + +#### Por que Plausible CE? + +A escolha pelo Plausible Community Edition é motivada por: + +- **Sem cookies**: Plausible não usa cookies de rastreamento, mantendo a privacidade dos usuários +- **Sem coleta invasiva**: Coleta apenas dados vinculados ao uso da aplicação — não rastreia histórico de navegação, dados pessoais ou comportamento fora do contexto educacional +- **Conformidade com LGPD**: Alinhado com as regulamentações brasileiras de proteção de dados +- **Software livre**: Pode ser hospedado localmente (Community Edition), oferecendo transparência e controle total + +#### Eventos rastreados nas atividades de programação + +Cada atividade de programação rastreia os seguintes eventos de aprendizagem: + +| Evento | Descrição | Propriedades | +|---|---|---| +| **Activity Success** | Estudante completou uma fase com sucesso | `activity`, `phase`, `blocks`, `attempts`, `failures`, `durationSeconds` | +| **Activity Failure** | Estudante encontrou um erro durante a execução | `activity`, `phase`, `blocks`, `error` | + +##### Detalhes das propriedades + +- **activity**: Identificador da atividade (ex: `programacao/puzzle`, `programacao/aspirador`) +- **phase**: Número da fase dentro da atividade +- **blocks**: Quantidade de blocos/linhas de código utilizados +- **attempts**: Número total de tentativas até o sucesso +- **failures**: Número de erros antes de conseguir sucesso +- **durationSeconds**: Tempo total gasto (em segundos) para completar a fase +- **error**: Mensagem de erro fornecida ao estudante (apenas em caso de falha) + +#### Análise pedagógica + +Essas métricas permitem: + +- Identificar fases com alta dificuldade (muitas tentativas/falhas antes do sucesso) +- Entender padrões de aprendizagem por atividade +- Medir o tempo médio de resolução de cada desafio +- Orientar decisões de redesign de atividades baseado em dados reais de uso + +--- + +## Técnico + +Arquivos de configuração: + +- `app/.env` (desenvolvimento) +- `app/.env.production` (produção) + +### Timeout de requisições + +Requisições para o Plausible possuem timeout de 5 segundos. Caso o servidor de analytics não responda no prazo, a requisição é automaticamente cancelada para não impactar a experiência do usuário. A aplicação funciona normalmente independente da disponibilidade do serviço de analytics. + +--- + +## Notas de migração + +Nenhuma ação necessária. O rastreamento é transparente para o usuário e não interfere na funcionalidade existente da plataforma.