desenvolvimento pre-lancamento
Commit inicial - add do repo privado para o repo NT style: changes header's logo and colors style: changes home page first session layout feat: creates about us home page section chore: creates home page section for whom chore: creates student materails home page section chore: creates teachers materials home page section chore: creates teacher materials home page section style: changes primary color style: changes color at activities page style: changes about page color style: changes name to Decoda fix: changes route to about page at footer fix: changes background color style: changes game page header colors style: changes footer colors chore: adds home page sections title style: changes main font family to Lato style: adds title font fix: changes sizes to be more responsive for mobile ajuste no build vercel atualiza regras envio homol Adiciona instrucoes de uso add JupyterLite fix solucao turtle Add Mole Mash e Modal de Falhas Add Progress Bar na pagina de Atividades fix game name chore: atualiza lockfile removendo vercel analytics inclusão de efeito ao mudar de fase add mecanismo de solução de fases em debug vite config test add BaseGame e refator do MoleMash refatoração turtle refatoração automato refatoração automato add tag bug 1 e 2 automato mostrar apenas games em homologação na pagina de atividades aumentar timeout das fases finais do Turtle fix bug scroll add video refactor semaforo arrumar ordem das cores add build docs update vercel update vercel update vercel update vercel update vercel add vercel jupyter add vercel jupyter fix deploy Vercel fix deploy Vercel fix deploy Vercel add cripto add cripto refatoração fix tour Mole Mash . remover arquivos de controle chore: adds development tag for activity card remover arquivos de status indevidamente versionados atualizar cores nas atividades add Quebra Cabeças add Quebra Cabeças add iniciativas add Iniciativas alteração de fotos pesadas fix menu mobile fix menu mobile fix menu mobile add Aspirador update icons update identidade visual documentação update jupyter add kernel python local add kernel python local add kernel python local feat: add health check feat: add primeiros passos add letramento mover letramento de lugar update path games update path games fix: ajuste clique rapido no botão executar remover dead code fix: refactor: extract shared utilities for storage, phase unlock and mobile detection stabilize context references and fix stale closure extrair GameProgressContext do GameStateContext (SRP) refactor(game): extrair usePhaser e useGameModals de GameBase + corrigir bugs descobertos refactor(game): remove todos os aliases PT/EN duplicados Remover aliases PT/EN da camada de modais refactor + tests security: add CodeSanitizer and integrate into GameInterpreter - CodeSanitizer.js: 4 built-in rules (max_length, infinite_while, infinite_for, excessive_nesting) with pluggable extra rules - GameInterpreter.executeCode: calls sanitizeCode() before js-interpreter, differentiates CodeSanitizationError (warn) from other errors (error) - 21 unit tests for CodeSanitizer (100% coverage) - 4 integration tests in GameInterpreter for sanitization paths add CodeSanitizer fix: fase 10 aspirador fix: bug semaforo teste feat: add version Ajusta a landing page para ficar mais próxima ao protótipo ajusta raio da borda do botão de Acesse nosso Laboratório pequenos ajustes de layout na página de iniciativas atualiza tabela de jogos educativos com os jogos disponíveis atualmente ajustados pequenos detalhes e informações do jogos na seção de guias pedagógicos troca nome playground para laboratório e adiciona imagens do lab adiciona documentação de conceitos básicos de programação ajustado pequenos erros de digitação adiciona tooltip com conceitos escondidos em hover na tag +N de conceitos update docs dev desativar tour setup matriz MoleMash setup matriz MoleMash fix: link update version update docs update docs mudou o layout de quem somos mudei as imgs dos icons e baixei o botao centraliza titulo com imagem e ajusta sessão com gradiente vermelho-rosa adiciona responsividade para a pagina quem somos ajusta botão de conheça nossa história ajustes ajustes na home + add. teclado update version security security feat: add tapume para telas pequenas v1.1.0 feat: decoda offline feat: doc offline offline fix: ajustes para release fix: navbar; config ordenação; versão fix: rotas docs e jupyter para pwa delete private files Co-authored-by: Indra Araujo <indra.araujo.santos@gmail.com> Co-authored-by: solange dos santos <sollangelive71@gmail.com>
This commit is contained in:
542
README.md
542
README.md
@@ -1,3 +1,541 @@
|
||||
# plataforma-edu
|
||||
# Decoda - Plataforma Educacional
|
||||
|
||||
Repositório da plataforma de Educação do Núcleo de Técnologoia
|
||||
> Plataforma para ensinar lógica de programação através de jogos educativos e blocos visuais.
|
||||
|
||||
## 📋 Índice
|
||||
|
||||
- [Sobre o Projeto](#sobre-o-projeto)
|
||||
- [Arquitetura](#arquitetura)
|
||||
- [Pré-requisitos](#pré-requisitos)
|
||||
- [Instalação e Build](#instalação-e-build)
|
||||
- [Opção 1: Docker Compose (Recomendado)](#opção-1-docker-compose-recomendado)
|
||||
- [Opção 2: Desenvolvimento Local](#opção-2-desenvolvimento-local)
|
||||
- [Estrutura do Projeto](#estrutura-do-projeto)
|
||||
- [Git Flow](#git-flow)
|
||||
- [Comandos Úteis](#comandos-úteis)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Contribuindo](#contribuindo)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Sobre o Projeto
|
||||
|
||||
O **Decoda** é uma plataforma educacional que oferece:
|
||||
|
||||
- 🎮 **Jogos educativos** interativos para aprender programação
|
||||
- 📚 **Documentação completa** para educadores e desenvolvedores
|
||||
- 🧩 **Programação visual** com blocos arrastar-e-soltar (sem necessidade de sintaxe), utilizando Blockly.
|
||||
- 🆓 **100% gratuito** e sem necessidade de cadastro
|
||||
|
||||
### Tecnologias Principais
|
||||
|
||||
- **Frontend (App):** React + Vite + Blockly
|
||||
- **Documentação:** Docusaurus
|
||||
- **Servidor Web:** Nginx
|
||||
- **Containerização:** Docker + Docker Compose
|
||||
|
||||
---
|
||||
|
||||
## Arquitetura
|
||||
|
||||
O projeto é dividido em 3 serviços principais:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Nginx Proxy (porta 80) │
|
||||
│ │
|
||||
│ /app/ → App (React/Vite) │
|
||||
│ /docs/ → Docs (Docusaurus) │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- **app/** - Aplicação React principal com os jogos
|
||||
- **docs/** - Documentação educacional e técnica
|
||||
- **proxy** - Nginx fazendo roteamento entre app e docs
|
||||
|
||||
---
|
||||
|
||||
## ✅ Pré-requisitos
|
||||
|
||||
### Para executar com Docker (Recomendado)
|
||||
|
||||
Você precisa apenas de:
|
||||
|
||||
- **Docker** (versão 20.10 ou superior)
|
||||
- **Docker Compose** (versão 2.0 ou superior)
|
||||
|
||||
> **💡 Não precisa instalar Node.js, npm ou qualquer outra ferramenta!**
|
||||
|
||||
#### Verificar se Docker está instalado
|
||||
|
||||
```bash
|
||||
docker --version
|
||||
docker compose version
|
||||
```
|
||||
|
||||
Se não tiver instalado, siga os guias oficiais:
|
||||
|
||||
- [Instalar Docker](https://docs.docker.com/get-docker/)
|
||||
- Docker Compose já vem incluído nas versões recentes do Docker
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Instalação e Build
|
||||
|
||||
### Opção 1: Docker Compose (Recomendado)
|
||||
|
||||
Esta é a forma mais simples e não requer conhecimento de React ou Node.js.
|
||||
|
||||
#### 1. Clone o repositório
|
||||
|
||||
```bash
|
||||
git clone https://git.mtst.tec.br/rui.moraes/plataforma-edu.git
|
||||
cd plataforma-edu
|
||||
```
|
||||
|
||||
#### 2. Build e execução
|
||||
|
||||
Execute um único comando para construir e iniciar tudo:
|
||||
|
||||
```bash
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
**O que esse comando faz:**
|
||||
|
||||
- `docker compose up` - Inicia os serviços
|
||||
- `--build` - Reconstrói as imagens se houver mudanças
|
||||
- `-d` - Roda em segundo plano (detached mode)
|
||||
|
||||
#### 3. Aguarde o build
|
||||
|
||||
O primeiro build pode demorar **5-10 minutos** dependendo da sua internet e máquina.
|
||||
|
||||
Você verá logs parecidos com:
|
||||
|
||||
```
|
||||
[+] Building 245.3s
|
||||
=> [app] downloading dependencies...
|
||||
=> [app] building application...
|
||||
=> [docs] downloading dependencies...
|
||||
=> [docs] building documentation...
|
||||
```
|
||||
|
||||
#### 4. Acesse a aplicação
|
||||
|
||||
Depois que o build terminar:
|
||||
|
||||
- **Aplicação:** http://localhost
|
||||
- **Documentação:** http://localhost/docs
|
||||
|
||||
#### 5. Verificar status
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
Você deve ver algo como:
|
||||
|
||||
```
|
||||
NAME STATUS PORTS
|
||||
plataforma-edu-app-1 Up 2 minutes
|
||||
plataforma-edu-docs-1 Up 2 minutes
|
||||
plataforma-edu-proxy-1 Up 2 minutes 0.0.0.0:80->80/tcp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Opção 2: Desenvolvimento Local
|
||||
|
||||
Para desenvolvedores que querem editar o código e ver mudanças em tempo real.
|
||||
|
||||
#### Pré-requisitos adicionais
|
||||
|
||||
- **Node.js** 20.x ou superior
|
||||
- **pnpm** (gerenciador de pacotes)
|
||||
|
||||
#### Instalar pnpm
|
||||
|
||||
```bash
|
||||
npm install -g pnpm
|
||||
```
|
||||
|
||||
#### Rodar App (React)
|
||||
|
||||
```bash
|
||||
cd app
|
||||
pnpm install
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
A aplicação estará disponível em http://localhost:5173
|
||||
|
||||
#### Rodar Documentação (Docusaurus)
|
||||
|
||||
Em outro terminal:
|
||||
|
||||
```bash
|
||||
cd docs
|
||||
pnpm install
|
||||
pnpm run start
|
||||
```
|
||||
|
||||
A documentação estará disponível em http://localhost:3000
|
||||
|
||||
---
|
||||
|
||||
## 📁 Estrutura do Projeto
|
||||
|
||||
```
|
||||
plataforma-edu/
|
||||
├── app/ # Aplicação React principal
|
||||
│ ├── src/ # Código fonte
|
||||
│ │ ├── pages/ # Páginas (Home, Educadores, FAQ, etc)
|
||||
│ │ ├── games/ # Jogos educativos
|
||||
│ │ ├── components/ # Componentes reutilizáveis
|
||||
│ │ └── styles/ # Estilos globais
|
||||
│ ├── public/ # Arquivos estáticos
|
||||
│ ├── Dockerfile # Build da imagem Docker
|
||||
│ ├── package.json # Dependências npm
|
||||
│ └── vite.config.js # Configuração do Vite
|
||||
│
|
||||
├── docs/ # Documentação Docusaurus
|
||||
│ ├── docs/ # Documentação para desenvolvedores
|
||||
│ ├── edu/ # Guias para educadores
|
||||
│ ├── src/ # Componentes customizados
|
||||
│ ├── Dockerfile # Build da imagem Docker
|
||||
│ ├── package.json # Dependências npm
|
||||
│ └── docusaurus.config.js # Configuração
|
||||
│
|
||||
├── docker-compose.yaml # Orquestração dos containers
|
||||
├── nginx.conf # Configuração do proxy Nginx
|
||||
└── README.md # Este arquivo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌳 Git Flow
|
||||
|
||||
### Fluxo de Desenvolvimento
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
commit
|
||||
branch develop
|
||||
checkout develop
|
||||
commit
|
||||
branch feature/nova-funcionalidade
|
||||
checkout feature/nova-funcionalidade
|
||||
commit id: "Implementa funcionalidade A"
|
||||
commit id: "Ajusta funcionalidade A"
|
||||
checkout develop
|
||||
merge feature/nova-funcionalidade
|
||||
commit id: "Prepara para um novo pacote"
|
||||
checkout main
|
||||
merge develop
|
||||
commit id: "Release v1.0"
|
||||
```
|
||||
|
||||
### Fluxo Simplificado
|
||||
|
||||
```
|
||||
1. Criar Feature
|
||||
git checkout -b feature/xyz (a partir de develop)
|
||||
↓
|
||||
2. Desenvolver e Commitar
|
||||
git commit -m "feat: descrição"
|
||||
↓
|
||||
3. Push e PR para Develop
|
||||
git push origin feature/xyz
|
||||
(Abrir PR no GitHub)
|
||||
↓
|
||||
4. Code Review + Merge em Develop
|
||||
Aprovação e merge automático
|
||||
↓
|
||||
5. PR de Develop para Main
|
||||
(Abrir PR: develop → main)
|
||||
↓
|
||||
6. Merge em Main
|
||||
Release pronta para produção
|
||||
```
|
||||
|
||||
### Regras e Configurações
|
||||
|
||||
Para informações detalhadas sobre:
|
||||
- ✅ Como criar branches (a partir de develop)
|
||||
- ✅ Padrão de commits
|
||||
- ✅ Regras de PR
|
||||
- ✅ Deploy em homologação com script
|
||||
- ✅ Variáveis de ambiente e token GitHub
|
||||
|
||||
**👉 Consulte: [README-HOMOLOGACAO.md](README-HOMOLOGACAO.md)**
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Comandos Úteis
|
||||
|
||||
### Docker Compose
|
||||
|
||||
#### Iniciar aplicação
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
#### Parar aplicação
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
#### Ver logs em tempo real
|
||||
|
||||
```bash
|
||||
# Todos os serviços
|
||||
docker compose logs -f
|
||||
|
||||
# Apenas app
|
||||
docker compose logs -f app
|
||||
|
||||
# Apenas documentação
|
||||
docker compose logs -f docs
|
||||
|
||||
# Apenas proxy
|
||||
docker compose logs -f proxy
|
||||
```
|
||||
|
||||
#### Rebuild completo (após mudanças no código)
|
||||
|
||||
```bash
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
#### Rebuild apenas um serviço
|
||||
|
||||
```bash
|
||||
docker compose up --build app -d
|
||||
```
|
||||
|
||||
#### Verificar status
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
#### Entrar dentro de um container
|
||||
|
||||
```bash
|
||||
# App
|
||||
docker compose exec app sh
|
||||
|
||||
# Docs
|
||||
docker compose exec docs sh
|
||||
```
|
||||
|
||||
#### Remover tudo (containers, volumes, imagens)
|
||||
|
||||
```bash
|
||||
docker compose down --volumes --rmi all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Erro: "port 80 already in use"
|
||||
|
||||
**Problema:** Outra aplicação está usando a porta 80.
|
||||
|
||||
**Solução:**
|
||||
|
||||
```bash
|
||||
# Linux/Mac - Ver o que está usando a porta 80
|
||||
sudo lsof -i :80
|
||||
|
||||
# Parar o serviço (exemplo com Apache)
|
||||
sudo systemctl stop apache2
|
||||
```
|
||||
|
||||
Ou edite `docker-compose.yaml` para usar outra porta:
|
||||
|
||||
```yaml
|
||||
proxy:
|
||||
ports:
|
||||
- "8080:80" # Mude para 8080 ou qualquer porta livre
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Erro: "COPY nginx-spa.conf: not found"
|
||||
|
||||
**Problema:** Arquivo `nginx-spa.conf` não está no diretório `app/`.
|
||||
|
||||
**Solução:**
|
||||
|
||||
```bash
|
||||
# Certifique-se de que o arquivo está na pasta correta
|
||||
ls app/nginx-spa.conf
|
||||
|
||||
# Se não estiver, mova da raiz
|
||||
mv nginx-spa.conf app/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Erro: "Minimum Node.js version not met"
|
||||
|
||||
**Problema:** O Dockerfile está usando Node.js 18, mas o projeto requer Node 20.
|
||||
|
||||
**Solução:** Os Dockerfiles já foram corrigidos para usar Node 20. Se ainda encontrar este erro:
|
||||
|
||||
```bash
|
||||
# Rebuild forçando recriação das imagens
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Build muito lento
|
||||
|
||||
**Dicas para acelerar:**
|
||||
|
||||
1. **Use cache de build do Docker:**
|
||||
|
||||
```bash
|
||||
# Docker irá reusar layers anteriores
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
2. **Aumente recursos do Docker:**
|
||||
|
||||
- Docker Desktop → Settings → Resources
|
||||
- Aumente CPU e Memória
|
||||
|
||||
3. **Limpe imagens antigas:**
|
||||
```bash
|
||||
docker system prune -a
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Acesso retorna 403 ao acessar /docs
|
||||
|
||||
**Problema:** Configuração incorreta do proxy Nginx.
|
||||
|
||||
**Solução:** Verifique se `nginx.conf` tem a barra final no `proxy_pass`:
|
||||
|
||||
```nginx
|
||||
location /docs/ {
|
||||
proxy_pass http://docs/;
|
||||
}
|
||||
```
|
||||
|
||||
Se necessário, rebuild:
|
||||
|
||||
```bash
|
||||
docker compose restart proxy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Mudanças no código não aparecem
|
||||
|
||||
**Problema:** Docker está usando build antigo em cache.
|
||||
|
||||
**Solução:**
|
||||
|
||||
```bash
|
||||
# Rebuild sem cache
|
||||
docker compose build --no-cache app
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Fluxo de Deploy em Produção
|
||||
|
||||
### 1. Preparação
|
||||
|
||||
```bash
|
||||
# Garantir que está na branch correta
|
||||
git checkout main
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
### 2. Build
|
||||
|
||||
```bash
|
||||
# Rebuild completo sem cache
|
||||
docker compose build --no-cache
|
||||
```
|
||||
|
||||
### 3. Deploy
|
||||
|
||||
```bash
|
||||
# Parar versão antiga
|
||||
docker compose down
|
||||
|
||||
# Iniciar nova versão
|
||||
docker compose up -d
|
||||
|
||||
# Verificar logs
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### 4. Verificação
|
||||
|
||||
```bash
|
||||
# Checar se todos os containers estão rodando
|
||||
docker compose ps
|
||||
|
||||
# Testar endpoints
|
||||
curl http://localhost
|
||||
curl http://localhost/docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Variáveis de Ambiente
|
||||
|
||||
O projeto atualmente não usa variáveis de ambiente complexas, mas se precisar:
|
||||
|
||||
Crie um arquivo `.env` na raiz:
|
||||
|
||||
```env
|
||||
# Exemplo
|
||||
APP_PORT=80
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
E referencie no `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
env_file:
|
||||
- .env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contribuindo
|
||||
|
||||
1. Fork o projeto
|
||||
2. Crie uma branch para sua feature (`git checkout -b feature/nova-funcionalidade`)
|
||||
3. Commit suas mudanças (`git commit -m 'Adiciona nova funcionalidade'`)
|
||||
4. Push para a branch (`git push origin feature/nova-funcionalidade`)
|
||||
5. Abra um Pull Request
|
||||
|
||||
---
|
||||
|
||||
## Para Educadores
|
||||
|
||||
Se você é educador e quer usar a plataforma, acesse:
|
||||
|
||||
- http://localhost/educadores - Guia de como começar
|
||||
- http://localhost/docs/edu - Documentação pedagógica completa
|
||||
|
||||
---
|
||||
|
||||
**Desenvolvido com ❤️ para educação em programação**
|
||||
|
||||
Reference in New Issue
Block a user