220 lines
9.5 KiB
Markdown
220 lines
9.5 KiB
Markdown
# 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.
|
||
|
||
---
|