feat: EduEasy checkpoint - plan, scaffolding, pedagogia modules, components child+parent, API routes, Prisma schema, Docker infra, Better Auth

PLAN.md

@@ -0,0 +1,219 @@
+# EduEasy — Plan de Plataforma
+
+## Arquitectura General
+
+Plataforma educativa para una nena de 8 años con déficit de atención, baja abstractividad, que no sabe leer ni contar (bases malas en 1er grado). Dos caras en un mismo server:
+
+| App | Dominio | Dispositivo | Usuario |
+|-----|---------|-------------|---------|
+| **Aprendizaje** | `mate.cbcren.online` | iPad Air 4 (solo dedo) | La nena |
+| **Dashboard** | `simulacro.cbcren.online` | Poco F6 Pro | La mamá |
+
+**Stack**: Next.js 15 + React 19 + TypeScript estricto + Tailwind CSS + shadcn/ui + Better Auth + Prisma + PostgreSQL + ts-fsrs  
+**Deploy**: All-in-one Docker (un proceso Next.js + Postgres) en red `caddy` del server existente (194.163.191.200)
+
+## Decisiones de Diseño Cerradas
+
+| Decisión | Respuesta |
+|----------|-----------|
+| **Mascota** | 🐱 **Gato** — guía las sesiones con instrucciones en audio, celebra logros, da feedback en errorless learning. Sin nombre fijo aún. |
+| **Paleta** | **Calmada** — fondo `#FFF8F0` crema/beige, primario `#8CB8A0` verde salvia, secundario `#6B8FA3` azul medio, acento `#D4A574` terracota, texto `#2D3436` (no negro puro). Bajas saturaciones en todos. |
+| **Audio** | **TTS por ahora** (Web Speech API, voz es-ES femenina). Se reemplaza por grabaciones reales es-AR en Fase 4+ cuando el contenido esté validado. |
+
+---
+
+## Pedagogía (Métodos Europeos)
+
+| Área | Método | Aplicación |
+|------|--------|------------|
+| **Lectura** | Borel-Maisonny (FR) | Cada fonema tiene un gesto físico + sonido. La nena hace el gesto en el aire + traza con el dedo en la pantalla + escucha el audio. |
+| **Lectura** | Jolly Phonics (UK) adaptado | Orden de aprendizaje: no A-B-C, sino por frecuencia de uso. Vocales primero (A, E, I, O, U) + consonantes sonoras continuas (S, M, L, N). |
+| **Lectura** | Método silábico | Español = 5 vocales puras, sílabas CV, CVC, CCV. Silabeo sistemático desde el día 1. |
+| **Numeración** | CPA (Concrete-Pictórico-Abstracto) | **Concreto**: objetos (tapitas virtuales para contar). **Pictórico**: dibujos de objetos. **Abstracto**: el número símbolo. |
+| **Numeración** | Regletas Cuisenaire (Bélgica) | Cantidad como barra de color. 1=blanco, 2=rojo, 3=verde claro... La nena ve y toca la cantidad sin "contar" abstractamente. |
+| **Internalización** | Galperin (URSS) | **1. Mano**: manipular objetos. **2. Voz externa**: decir en voz alta. **3. Voz interna**: susurrar. **4. Mental**: hacerlo en la cabeza. |
+| **Errores** | Errorless learning | **Nunca** se muestra "incorrecto". Si titubea, el sistema da la pista más obvia (modelado). Si persiste el error, fadea la ayuda. |
+| **Refuerzo** | Fijo y predecible | Sin slots, sin FOMO, sin rachas ansiosas. Estrellita predecible después de cada ronda completa. |
+| **Sesiones** | Chunking estructurado | 10-15 min máximo. Temporizador visual tipo Time Timer. Micro-pausa motora cada 5 min (saltar, aplaudir). |
+
+---
+
+## Stack Técnico
+
+```
+Frontend:  Next.js 15 (App Router) + React 19 + TypeScript + Tailwind CSS
+UI Lib:    shadcn/ui (componentes base)
+Auth:      Better Auth (login mamá + QR pairing → JWT device-bound para nena)
+DB:        PostgreSQL + Prisma ORM
+Spaced Rep: ts-fsrs (Free Spaced Repetition Scheduler)
+Canvas:    perfect-freehand (trazo con dedo) + @use-gesture/react
+Audio:     Web Speech API (TTS es-ES/es-MX, confirmado: TTS por ahora → reemplazar con grabaciones reales es-AR en Fase 4+)
+Animación: framer-motion (transiciones lentas 300-500ms, sin sparkles)
+Charts:    Recharts (dashboard mamá)
+Deploy:    Docker + red caddy existente
+```
+
+### Repos reutilizados
+- `ts-fsrs` (npm) — algoritmo FSRS de repetición espaciada
+- `perfect-freehand` (npm) — trazado fluido con dedo (Excalidraw)
+- Better Auth (npm) — auth + device pairing
+- shadcn/ui (npm) — componentes base de UI
+- Math Learning Center apps — referencia UX de manipulativos virtuales (number-rack, ten-frames)
+
+---
+
+## Modelo de Datos
+
+```prisma
+model Family { id, name, created_at }
+model Parent { id, family_id, email, name, auth_provider }
+model Child { id, family_id, name, avatar, birthdate, profile_notes }
+model Device { id, child_id, device_fingerprint, paired_at, last_seen, role }
+model Session { id, child_id, started_at, ended_at, duration_sec, skills_practiced }
+model SkillAttempt { id, session_id, skill_code, prompt_level, correct, response_ms }
+model FsrsCard { id, child_id, skill_code, due_at, stability, difficulty, reps, lapses }
+model Milestone { id, child_id, skill_code, reached_at }
+```
+
+---
+
+## Estructura del Proyecto
+
+```
+/home/ren/edueasy/
+├── app/
+│   ├── globals.css
+│   ├── layout.tsx               # Raíz (fonts, metadata)
+│   ├── page.tsx                 # Redirige según host
+│   ├── child/                   # mate.cbcren.online
+│   │   ├── layout.tsx           # Layout infantil (gato, audio siempre presente)
+│   │   ├── page.tsx             # Menú principal de la nena
+│   │   ├── sesion/
+│   │   └── logros/
+│   ├── parent/                  # simulacro.cbcren.online
+│   │   ├── layout.tsx           # Layout dashboard + sidebar
+│   │   ├── page.tsx             # Dashboard principal
+│   │   ├── auth/login/
+│   │   ├── auth/pairing/
+│   │   └── configuracion/
+│   └── api/
+│       ├── auth/[...all]/       # Better Auth handler
+│       ├── pairing/             # QR pairing endpoint
+│       └── sessions/sync/       # Sync offline → server
+├── components/
+│   ├── ui/                      # shadcn/ui
+│   ├── child/                   # Componentes de la nena
+│   │   ├── gato-mascota
+│   │   ├── trazo-letra (canvas tracing)
+│   │   ├── vocal-card
+│   │   ├── cuisenaire-rod
+│   │   ├── temporizador-visual
+│   │   └── boton-grande (60-80px)
+│   └── parent/                  # Componentes del dashboard
+├── lib/
+│   ├── db.ts (Prisma client)
+│   ├── auth.ts (Better Auth server)
+│   ├── auth-client.ts
+│   ├── speech.ts (Web Speech API)
+│   ├── fsrs.ts (ts-fsrs wrapper)
+│   └── pedagogia/
+│       ├── borel-maisonny.ts (fonemas + gestos)
+│       ├── cuisenaire.ts (regletas)
+│       ├── errorless.ts (prompt fading)
+│       └── cpa-progression.ts (CPA estados)
+├── prisma/schema.prisma
+├── middleware.ts (host-based routing)
+├── Dockerfile
+├── docker-compose.yml
+├── package.json
+├── tsconfig.json
+├── next.config.ts
+├── tailwind.config.ts
+├── postcss.config.js
+├── components.json (shadcn/ui)
+└── .env.local
+```
+
+---
+
+## UX Constraints (iPad Air 4 + Dedo)
+
+- **Touch targets**: 60–80px mínimo (baselines adultos 44px no alcanzan para niños)
+- **Drag > Tap** para interacciones principales
+- **Una sola acción focal** por pantalla
+- **100% iconografía + audio** (la nena NO LEE)
+- **Sin "X roja"** nunca — sonido neutro + mascota dice "probemos juntas"
+- **Fondo claro baja saturación** (crema/beige) + acentos verde salvia + azul medio
+- **Botón "Tocá para empezar"** en cada sesión (unlock AudioContext en iOS Safari)
+- **Persistencia al backend siempre** (Safari evicta IndexedDB a 7 días)
+
+### iOS Safari Técnico
+- Audio: .m4a primario + .mp3 fallback. **NUNCA .ogg**.
+- AudioContext: requiere user gesture para desbloquear.
+- `100dvh` en vez de `100vh` (barra de Safari).
+- `touch-action: manipulation` para eliminar delay 300ms.
+- inputs con `font-size: 16px` mínimo (evita zoom automático).
+
+---
+
+## Roadmap
+
+### Fase 0 — Fundaciones (1-2 sem)
+- [x] Repositorio + package.json + configs
+- [x] Docker + docker-compose
+- [x] Prisma schema + migración
+- [x] Better Auth + QR pairing
+- [x] Design system base (gato mascota, paleta, component primitives)
+- [x] Caddy config update
+
+### Fase 1 — Lectura MVP
+- [ ] Módulo vocales: A, E, I, O, U
+- [ ] Audio TTS para cada fonema + palabra ejemplo
+- [ ] Gesto Borel-Maisonny (animación + instrucción)
+- [ ] Trazo con dedo (canvas + perfect-freehand)
+- [ ] Sesión guiada 10 min + temporizador visual
+- [ ] Errorless learning + fading automático
+- [ ] Logros por vocal completada
+
+### Fase 2 — Numeración MVP
+- [ ] Módulo cantidades 1-5 (expandir a 10)
+- [ ] CPA: objetos → imagen → símbolo
+- [ ] Regletas Cuisenaire virtuales (arrastrar, comparar)
+- [ ] Conteo one-to-one con arrastre
+- [ ] Galperin: mano → voz → cabeza
+
+### Fase 3 — Adaptativo + Dashboard
+- [ ] ts-fsrs: repaso espaciado por skill
+- [ ] Dashboard mamá: streak, tiempo, mastery %, último resumen
+- [ ] Push notifications al Poco F6 Pro
+- [ ] QR pairing funcional
+- [ ] Export de progreso
+
+### Fase 4+ (futuro)
+- [ ] Consonantes y sílabas completas
+- [ ] Números 11-100, suma/resta
+- [ ] Grabaciones de audio real (es-AR)
+- [ ] IA adaptativa (Ollama/Open WebUI)
+
+---
+
+## Diseño Visual
+
+**Mascota**: 🐱 Gato (sin nombre definido — que la nena lo nombre). 
+- Guía las sesiones, da instrucciones en audio, celebra logros.
+- Animaciones suaves (no bruscas), tamaño grande en pantalla.
+
+**Paleta**:
+- Fondo: `#FFF8F0` (crema suave)
+- Primario: `#8CB8A0` (verde salvia)
+- Secundario: `#6B8FA3` (azul medio)
+- Acento: `#D4A574` (terracota suave)
+- Texto: `#2D3436` (gris oscuro, no negro puro)
+- Correcto: `#7FB685` (verde suave, no brillante)
+
+**Tipografía**:
+- Títulos: Fredoka One (redondeada, amigable, legible)
+- Interface: Inter (sistema, para dashboard de la mamá)
+- La nena no ve texto — solo escucha. Las letras aparecen grandes, claras, bien trazadas.
+
+---