🎮 CodeQuest - Plataforma Gamificada de Aprendizado Python

Uma plataforma interativa e gamificada para aprender Python através de desafios progressivos, com execução de código no navegador e sistema de XP/níveis/conquistas.

✨ Características Principais

• 🐍 Execução Python no Navegador: Usando Pyodide (Python WASM) - sem backend necessário
• 📝 Editor de Código Profissional: CodeMirror 6 com syntax highlighting, tabs e autocomplete
• 🎯 Sistema de Validação Tripla:
  • Validação de output (exact_match, regex, contains)
  • Validação de código-fonte (previne hardcoding)
  • Liberdade criativa (usuários escolhem nomes de variáveis)
• 🏆 Gamificação Completa: Sistema de XP, níveis (baseado em level = floor(xp/100) + 1), e conquistas
• 📚 6 Módulos de Aprendizado: 25+ exercícios progressivos (50-200 XP cada)
• 🎨 UI Pixel Retro-Tech: Estilo único com pixel shadows, cores vibrantes e fonte IBM Plex Mono
• 👤 Gerenciamento de Usuários: Scripts completos para reset/delete de progresso

🚀 Stack Tecnológico

• Frontend: Next.js 16, React 19, TypeScript
• Backend: Supabase (PostgreSQL + Auth + RLS)
• Execução Python: Pyodide v0.24.1
• Editor: CodeMirror 6 com Python support
• UI: shadcn/ui + TailwindCSS
• Notificações: Sonner (toast notifications)

📊 Conteúdo

Módulos Implementados (835 XP Total)

1. Olá, Mundo! (50 XP) - 3 exercícios
2. Variáveis e Números (185 XP) - 7 exercícios
3. Condições: if e else (100 XP) - 3 exercícios
4. Loops: for (125 XP) - 3 exercícios
5. Listas (175 XP) - 3 exercícios
6. Funções e Métodos (200 XP) - 3 exercícios

Cada módulo inclui:

• 📖 Material teórico interativo (teoria, exemplos, dicas, pontos-chave)
• 💪 Exercícios progressivos com dificuldade crescente
• 💡 Sistema de dicas expandíveis
• ✅ Validação inteligente e feedback em tempo real

🛠️ Setup Local

Pré-requisitos

• Node.js 18+
• Conta Supabase (free tier funciona)

Instalação

# Clone o repositório
git clone git@github.com:seu-usuario/code-quest.git
cd code-quest

# Instale dependências
npm install

# Configure variáveis de ambiente
cp .env.example .env.local
# Adicione suas credenciais Supabase em .env.local:
# NEXT_PUBLIC_SUPABASE_URL=sua_url_aqui
# NEXT_PUBLIC_SUPABASE_ANON_KEY=sua_key_aqui

Configuração do Banco de Dados

Execute os scripts SQL em ordem no Supabase SQL Editor:

Core (obrigatório):

1. scripts/001_create_tables.sql - Tabelas base + RLS
2. scripts/002_create_profile_trigger.sql - Auto-criação de perfil
3. scripts/003_seed_modules.sql - 6 módulos
4. scripts/007_create_module_exercises.sql - Tabelas de exercícios
5. scripts/008_seed_module_exercises.sql - Exercícios base

Melhorias (recomendado):

• scripts/013_fix_loops_listas_xp.sql - Correção de XP
• scripts/014_add_functions_achievement.sql - Conquista "Arquiteto de Código"
• scripts/015_add_variaveis_exercises.sql - 4 exercícios extras
• scripts/018_add_flexible_validation.sql - Sistema de validação flexível
• scripts/019_add_code_validation.sql - Validação de código-fonte
• scripts/021_remove_variable_name_restrictions.sql - Liberdade de nomes
• scripts/022_fix_variaveis_code_validation.sql - Fix validações

Utilitários (opcional):

• scripts/016_reset_user_progress.sql - Reset de usuário
• scripts/017_delete_user_completely.sql - Deleção completa

Veja scripts/CLAUDE.md para documentação completa dos scripts.

Executar o Projeto

npm run dev

Acesse http://localhost:3000

🎓 Sistema de Validação Inovador

CodeQuest usa um sistema de validação em 3 camadas que equilibra rigor educacional com liberdade criativa:

1. Validação de Output

-- Exact match
expected_output = '42'

-- Regex pattern
validation_type = 'regex'
validation_pattern = '^Meu nome é .+$'  -- Aceita qualquer nome

-- Contains
validation_type = 'contains'
validation_pattern = 'Python'  -- Deve conter "Python"

2. Validação de Código

-- Deve usar operadores
code_must_contain = ARRAY['+', '/', 'print(']

-- Não pode hardcode
code_must_not_contain = ARRAY['print(9.0)']

3. Liberdade Criativa

• Usuários escolhem nomes de variáveis
• Múltiplas soluções válidas
• Foco no conceito, não em sintaxe específica

📈 Sistema de Gamificação

• XP: Ganho por exercício completado (15-90 XP)
• Níveis: Fórmula level = floor(xp / 100) + 1
  • Nível 1: 0-99 XP
  • Nível 2: 100-199 XP
  • Nível 3: 200-299 XP
  • E assim por diante...
• Conquistas: Desbloqueadas automaticamente ao atingir XP necessário
• Progressão: Módulos e exercícios desbloqueiam sequencialmente

📁 Estrutura do Projeto

code-quest/
├── app/                      # Next.js 16 App Router
│   ├── dashboard/           # Dashboard do usuário
│   ├── modules/             # Listagem e páginas de módulos
│   ├── achievements/        # Sistema de conquistas
│   └── auth/               # Páginas de autenticação
├── components/              # Componentes React
│   ├── ui/                 # shadcn/ui components
│   ├── code-editor.tsx     # Editor CodeMirror
│   ├── exercise-card.tsx   # Card de exercícios
│   ├── learning-section.tsx # Material teórico
│   └── navbar.tsx          # Navegação principal
├── lib/                     # Utilitários
│   ├── supabase/           # Clientes Supabase
│   ├── pyodide-loader.ts   # Loader do Pyodide
│   └── types.ts            # TypeScript types
└── scripts/                 # Migrations SQL (001-022)

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/NovaFeature)
3. Commit suas mudanças (git commit -m 'feat: adiciona NovaFeature')
4. Push para a branch (git push origin feature/NovaFeature)
5. Abra um Pull Request

Padrões de Commit

Usamos Conventional Commits:

• feat: - Nova funcionalidade
• fix: - Correção de bug
• docs: - Mudanças na documentação
• style: - Formatação (não afeta código)
• refactor: - Refatoração de código
• test: - Testes
• chore: - Manutenção

📝 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

• Desenvolvido com Claude Code
• UI inspirada em estilo "Pixel Learning UI"
• Python WASM powered by Pyodide

---

Status: ✅ Produção Ready | 6 Módulos | 25+ Exercícios | 835 XP Total

Desenvolvido por: Vinicius Machado