Dutch Master

Plataforma de aprendizagem de holandês focada em contabilidade — construída com Flask, SQLAlchemy e SQLite.

O que já está incluído

• Login / registo com objetivo pessoal e tempo diário de estudo
• Painel com XP, moedas, sequência de dias (streak), gráfico semanal, progresso do curso
• Curso estruturado (A0/A1): módulos gerais + módulos de contabilidade
• 8 tipos de exercícios interativos por lição (escolha múltipla, tradução, completar frases, ordenar frases, ditado, quiz cronometrado, encontrar erro, correspondência) + jogo da memória
• Sistema de flashcards com repetição espaçada (algoritmo tipo SM-2 / Anki)
• 12 capítulos de gramática completos, com tabelas e exercícios próprios
• Gamificação: moedas, 10 badges, 6 missões diárias/semanais
• Dicionário pesquisável com 143 palavras (geral + contabilidade)
• Leituras graduais (4 histórias) com palavras clicáveis, áudio e tradução
• Diálogos temáticos (3 conversas) com balões de chat e áudio
• Career Mode (5 cenários): entrevistas, emails profissionais, formulários
• Escrita livre (5 exercícios) com checklist automático de palavras-chave
• Painel de administração (gestão de vocabulário e utilizadores)
• Dark mode
• Identidade visual própria (inspirada no De Stijl / Mondrian)

Como correr no teu computador

Precisas de ter Python 3.10+ instalado.

1. Criar um ambiente virtual (recomendado)

cd dutch_master
python3 -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate

2. Instalar as dependências

pip install -r requirements.txt

3. Popular a base de dados (primeira vez apenas)

python seed_data.py

Isto cria o ficheiro dutch_master.db (SQLite) com todo o conteúdo.

⚠️ Atenção: correr seed_data.py de novo APAGA todos os dados existentes (incluindo contas de utilizador criadas). Só corre isto uma vez, ou quando quiseres reiniciar tudo do zero.

4. Arrancar a aplicação

python app.py

Abre o browser em: http://127.0.0.1:5000

5. Painel de Administração

O primeiro utilizador que criares (registares) torna-se automaticamente administrador. Depois de criares essa conta, vai aparecer um link "⚙️ Admin" no menu — daí consegues gerir o vocabulário (adicionar/editar/eliminar palavras) e ver a lista de utilizadores.

Se quiseres tornar outra conta existente em administrador manualmente, corre isto no terminal (dentro da pasta do projeto, com o ambiente virtual ativo):

python3 -c "
from app import app
from models import db, User
with app.app_context():
    u = User.query.filter_by(username='O_TEU_USERNAME').first()
    u.is_admin = True
    db.session.commit()
    print('Admin ativado para', u.username)
"

6. Dark Mode

Clica no botão 🌙 no canto superior direito do menu para alternar entre tema claro e escuro. A preferência fica guardada no browser (localStorage), por isso mantém-se ativa da próxima vez que abrires a app.

Estrutura do projeto

dutch_master/
├── app.py                # Rotas Flask e lógica principal
├── models.py              # Modelos da base de dados (SQLAlchemy)
├── seed_data.py            # Script que popula todo o conteúdo
├── gamification.py         # Lógica de badges, missões e moedas
├── requirements.txt
├── static/
│   └── css/style.css       # Design system (De Stijl / Mondrian + dark mode)
└── templates/              # Páginas HTML (Jinja2)
    └── admin/               # Templates do painel de administração

Próximos passos sugeridos (fora do que já está construído)

• Áudio pré-gravado (atualmente usa a voz sintética do browser via SpeechSynthesis)
• Correção automática de escrita mais avançada (atualmente é um checklist de palavras-chave + resposta modelo para autoavaliação, não correção gramatical real)
• Painel de administração mais completo (atualmente cobre vocabulário; lições/leituras/diálogos/gramática ainda são geridos via seed_data.py)
• Mais níveis (A2, B1, B2) e expansão contínua do dicionário
• Ranking entre utilizadores (só faz sentido com uma base de utilizadores reais)

Notas técnicas

• Base de dados: SQLite (ficheiro local dutch_master.db), criado automaticamente
• Autenticação: Flask-Login, palavras-passe encriptadas com Werkzeug
• Não uses este servidor em produção — o Flask development server (app.run(debug=True)) é só para uso local/desenvolvimento
• A chave secreta em app.py (SECRET_KEY) deve ser alterada antes de qualquer deployment real

Como fazer deploy (colocar online) — Render.com

Esta app não funciona no Vercel ou Netlify (são para sites estáticos). Usa o Render.com, que suporta apps Flask com plano gratuito.

Passo 1 — Colocar o código no GitHub

1. Cria uma conta em github.com (se ainda não tiveres)
2. Cria um novo repositório (ex: dutch-master)
3. Faz upload da pasta dutch_master para esse repositório (podes arrastar os ficheiros diretamente na interface do GitHub, em "Add file" → "Upload files", ou usar o Git na linha de comandos se preferires)

Passo 2 — Criar a conta no Render

1. Vai a render.com e cria uma conta (podes usar login do GitHub, facilita)
2. Clica em "New +" → "Web Service"
3. Liga a tua conta do GitHub e seleciona o repositório dutch-master

Passo 3 — Configurar o serviço

O Render deve detetar automaticamente o ficheiro render.yaml incluído no projeto e preencher tudo sozinho. Se não detetar, preenche manualmente:

• Name: dutch-master (ou o que preferires)
• Runtime: Python 3
• Build Command: pip install -r requirements.txt
• Start Command: gunicorn app:app
• Plan: Free

Clica em "Create Web Service". O primeiro deploy demora alguns minutos.

Passo 4 — Popular a base de dados (só a primeira vez)

Depois do deploy terminar com sucesso:

1. No painel do Render, abre o teu serviço
2. Vai ao separador "Shell" (ou "Console")
3. Corre: python seed_data.py

Isto cria todo o conteúdo (módulos, lições, gramática, etc.) na base de dados online.

⚠️ Importante: só corras seed_data.py esta primeira vez. Se o correres de novo mais tarde, apaga tudo (incluindo contas de utilizador) e recria do zero.

Passo 5 — Aceder à app

O Render dá-te um URL tipo https://dutch-master.onrender.com — é esse o link que passas a usar.

⚠️ Aviso sobre persistência de dados (plano gratuito)

No plano gratuito do Render, o sistema de ficheiros não é garantidamente permanente entre reinícios do serviço (o que acontece, por exemplo, após um novo deploy, ou por vezes automaticamente após longos períodos de inatividade). Isto significa que a base de dados SQLite pode ocasionalmente perder dados.

Para um projeto pessoal isto é aceitável na fase inicial, mas se quiseres garantir que nunca perdes progresso, a solução mais robusta é trocar o SQLite por uma base de dados externa persistente (ex: Render Postgres, que tem um plano gratuito próprio, ou Supabase). Se chegares a esse ponto, diz-me e ajudo a fazer essa migração — exige alterar poucas linhas no app.py, porque já usamos SQLAlchemy.