feat: v1.2.0
This commit is contained in:
7
.gitignore
vendored
7
.gitignore
vendored
@@ -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
|
||||
|
||||
166
docs/docs/plataforma/arquitetura/coleta-eventos.md
Normal file
166
docs/docs/plataforma/arquitetura/coleta-eventos.md
Normal file
@@ -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<br/>(ex: PuzzleGame)"] -->|Usuário executa código| B["GameStateContext<br/>(finalizeWithSuccess/Failure)"]
|
||||
|
||||
B -->|Dispara evento| C["trackEvent<br/>plausible.js"]
|
||||
|
||||
C -->|Lê variáveis de ambiente| D{Qual ambiente?}
|
||||
|
||||
D -->|Development| E["VITE_PLAUSIBLE_API<br/>http://localhost/api/event"]
|
||||
D -->|Production| F["VITE_PLAUSIBLE_API<br/>plausible.mtst.tec.br"]
|
||||
|
||||
E --> G["Fetch com timeout 5s<br/>(AbortController)"]
|
||||
F --> G
|
||||
|
||||
G -->|Success| H["Evento registrado<br/>no Plausible"]
|
||||
|
||||
G -->|Timeout/Error| I["console.error<br/>App continua"]
|
||||
|
||||
H --> J["Dashboard Plausible<br/>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
|
||||
```
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
---
|
||||
|
||||
|
||||
72
docs/docs/releases/v1.2.0.md
Normal file
72
docs/docs/releases/v1.2.0.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user