feat: fase 4 — overhaul, docker, seguridad, métodos europeos

- Eliminada ruta duplicada /sebastian/sumas (código muerto) - Removido topic 'sumas' del engine (reemplazado por 'matematicas') - Creado docker-compose.yml (PostgreSQL + app, 1 comando install) - Dockerfile: copiado prisma CLI al runner stage para db push - APIs debug protegidas: 403 en producción (reset, state, seed) - Audit métodos europeos: 24 archivos corregidos al 100% - Montessori: matemática Francesca + Sebastián - Decroly: lectura, ortografía, historia, geografía, banderas - Borel-Maisonny: lectura inicial Isabella (ya existía) - Freinet: expresión escrita Sebastián (ya existía) - Validación prerequisitos: 0 rotos en contenido nuevo (157 ejercicios) - INSTALL.md: guía completa de instalación - fase4.md: documentación del overhaul - E2E: 2 tests corregidos, 61/61 pasan - TypeScript: exit 0, Build: exit 0
2026-07-25 22:34:05 -03:00
parent a3360ec6e4
commit 07929b6c60
36 changed files with 367 additions and 80 deletions
@@ -0,0 +1,151 @@
+# EduEasy — Instalación y Uso
+
+## Instalación rápida con Docker
+
+```bash
+# 1. Clonar el repositorio
+git clone https://gitea.cbcren.online/renato97/edueasy.git
+cd edueasy
+
+# 2. Levantar todo (app + base de datos)
+docker compose up -d
+
+# 3. Verificar que está corriendo
+curl http://localhost:3000
+```
+
+La app queda disponible en `http://localhost:3000`.
+La base de datos PostgreSQL en `http://localhost:5432`.
+
+### Variables de entorno
+
+| Variable | Default | Descripción |
+|----------|---------|-------------|
+| `DATABASE_URL` | `postgresql://edueasy:edueasy_pass@db:5432/edueasy` | URL de PostgreSQL |
+| `NEXTAUTH_SECRET` | `change-me-in-production` | Secreto para sesiones (CAMBIAR en producción) |
+| `NODE_ENV` | `production` | Entorno de ejecución |
+
+### Detener
+
+```bash
+docker compose down
+```
+
+### Detener y borrar datos
+
+```bash
+docker compose down -v
+```
+
+---
+
+## Instalación manual (sin Docker)
+
+### Requisitos
+
+- Node.js 22+
+- PostgreSQL 16+
+- espeak-ng (para TTS)
+
+```bash
+# 1. Instalar dependencias
+npm install
+
+# 2. Configurar base de datos
+createdb edueasy
+echo 'DATABASE_URL="postgresql://edueasy:edueasy_pass@localhost:5432/edueasy?schema=public"' > .env.local
+
+# 3. Aplicar schema
+npx prisma db push
+npx prisma generate
+
+# 4. Desarrollo
+npm run dev
+
+# 5. Producción
+npm run build
+npm start
+```
+
+---
+
+## Perfiles de aprendizaje
+
+| Perfil | Edad | Materias | Métodos europeos |
+|--------|------|----------|------------------|
+| **Isabella** | 4 años | Lectura (9 etapas), Números (8 etapas) | Borel-Maisonny (gesto-fonema), Montessori sensorial |
+| **Francesca** | 6 años | Matemáticas (10 etapas), Lecturas (9 etapas), Ortografía (2 etapas) | Montessori operacional, Decroly (centros de interés) |
+| **Sebastián** | 8 años | Matemáticas (11 etapas), Lectura (6 etapas), Historia (5 etapas), Geografía (3 etapas), Banderas (2 etapas) | Montessori avanzado, Decroly, Freinet (expresión) |
+
+### Cómo navegar
+
+1. Página principal (`/`) → muestra los 3 perfiles
+2. Seleccionar un perfil → va a `/francesca`, `/sebastian`, o `/child` (Isabella)
+3. Cada perfil muestra sus actividades
+4. Al tocar una actividad, empieza la sesión de ejercicios con TTS
+
+---
+
+## APIs de debug (solo desarrollo)
+
+> **Estas APIs solo funcionan en `NODE_ENV=development`**. En producción devuelven 403.
+
+### Resetear progreso de un child
+
+```bash
+curl -X POST http://localhost:3000/api/debug/reset \
+  -H "Content-Type: application/json" \
+  -d '{"childId":"..."}'
+```
+
+### Ver estado completo de un child
+
+```bash
+curl http://localhost:3000/api/debug/state?childId=...
+```
+
+### Sembrar ejercicios de prueba
+
+```bash
+curl -X POST http://localhost:3000/api/debug/seed \
+  -H "Content-Type: application/json" \
+  -d '{"childId":"...","profile":"FRANCESCA","topic":"matematicas","stages":[1,2],"markAllCorrect":true}'
+```
+
+---
+
+## Testing
+
+```bash
+# TypeScript
+npx tsc --noEmit
+
+# Build
+npm run build
+
+# E2E tests (Playwright)
+npx playwright test
+```
+
+---
+
+## Estructura del proyecto
+
+```
+curriculum/           # Datos de ejercicios (generados programáticamente)
+  lectura/            # Isabella - lectura (9 etapas)
+  numeros/            # Isabella - matemática (8 etapas)
+  francesca/          # Francesca - matemática (10 etapas)
+  francesca-lectura/  # Francesca - comprensión lectora (9 etapas)
+  francesca-ortografia/ # Francesca - ortografía (2 etapas)
+  sebastian/          # Sebastián - matemática (11 etapas)
+  sebastian-lectura/  # Sebastián - lectura y expresión (6 etapas)
+  sebastian-historia/ # Sebastián - historia argentina (5 etapas)
+  sebastian-geografia/ # Sebastián - geografía (3 etapas)
+  sebastian-banderas/ # Sebastián - banderas provinciales (2 etapas)
+
+lib/curriculum/engine.ts  # Motor: carga etapas, calcula próximo ejercicio
+app/api/                   # APIs REST
+components/                # Componentes React reutilizables
+e2e/                       # Tests E2E (Playwright)
+```