decoda/README.md

# Decoda - Plataforma Educacional

> 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
```

#### Build com Google Analytics 4 (GA4)

Para ativar analytics em produção, use argumentos de build:

**Com variáveis de ambiente:**

Crie um arquivo `.env` na raiz do projeto:

```bash
GIT_COMMIT_HASH=abc1234
VITE_ANALYTICS_PROVIDER=ga4
VITE_GA4_ID=G-SEU_ID_GA4
VITE_GA4_DEBUG=false
```

Então execute:

```bash
docker compose build app
docker compose up -d
```

**Ou diretamente via argumentos:**

```bash
docker compose build \
  --build-arg GIT_COMMIT_HASH=$(git rev-parse --short HEAD) \
  --build-arg VITE_ANALYTICS_PROVIDER=ga4 \
  --build-arg VITE_GA4_ID=SEU_ID_AQUI \
  app

docker compose up -d
```

**Para desabilitar analytics (desenvolvimento):**

```bash
docker compose build --build-arg VITE_ANALYTICS_PROVIDER=noop app
docker compose up -d
```

> 📊 **Nota:** Obtém seu ID do GA4 em [https://analytics.google.com](https://analytics.google.com) → Administração → Data Streams → Copie o ID de medição (formato: G-XXXXXXXXXX)

Para mais detalhes, veja: [Documentação de Analytics](docs/docs/plataforma/arquitetura/analytics.md)

---

### 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**