recordalexia/README.md

# recordaLexia

App web familiar para niños con **TDAH**. Cada mañana, en una tablet en modo kiosko
junto a la puerta, muestra qué material llevar al cole y qué rutinas hacer por la
tarde. El niño marca cada tarea, gana monedas y las canjea en una tienda de premios.
Multi-niño y bilingüe (español / catalán).

## Características

- Pantalla "HOY" con dos modos: **Tablero** (cole + tarde a la vista) y **Foco**
  (una tarea a la vez), pensado para reducir la carga cognitiva.
- Avisos de exámenes y deberes, temporizador de salida y lectura en voz alta (TTS).
- Gamificación: monedas por tarea / bloque / día y tienda de recompensas.
- Panel de padres protegido por PIN: horario semanal, materiales, eventos, rutinas
  de tarde y recompensas.

## Stack

- **Frontend:** Angular 19 (standalone + signals), TypeScript, i18n ES/CA.
- **Backend:** Java 21, Spring Boot 3.x, Gradle 8.
- **Datos:** PostgreSQL + Liquibase.
- **Empaquetado:** Docker + docker-compose (postgres + backend + Nginx).

## Estructura del repositorio

```
recordaLexia/
├── CLAUDE.md                              # Convenciones para Claude Code
├── README.md                             # Este fichero
├── docker-compose.yml                    # Stack: postgres + backend + frontend
├── .env.example                          # Plantilla de variables (copiar a .env)
├── frontend/                             # Angular 19 (standalone + signals)
├── backend/                              # Spring Boot 3.5 + Gradle (wrapper)
├── docs/                                 # Specs de referencia (contrato)
│   ├── adr/                              # Decisiones de arquitectura (ADR)
│   ├── prompt-claude-code-recordalexia-director.md
│   ├── prompt-claude-code-backend-rutinas-tdah.md
│   └── prompt-claude-design-rutinas-tdah.md
├── artifacts/                            # Diseño de referencia (HTML autónomo)
└── app-de-rutinas-visuales-para-tdah/    # Handoff de Claude Design (solo lectura)
    ├── project/
    │   ├── Rutinas TDAH.dc.html
    │   └── support.js
    └── README.md
```

> El handoff de `app-de-rutinas-visuales-para-tdah/` es la fuente de verdad visual; no
> se edita, se usa como referencia para reconstruir la UI en Angular.

## Requisitos

- Java 21 (JDK). No hace falta instalar Gradle: el backend trae el *wrapper*.
- Node 20 LTS recomendado (Angular 19 soporta 18.19+/20/22; **Node 24 funciona
  pero Angular lo marca como no soportado** — fija 20 LTS en el homelab).
- Docker y Docker Compose.
- No hace falta instalar PostgreSQL: lo levanta docker-compose.

## Configuración previa

Copia la plantilla de variables y pon tus valores (credenciales de BD, puerto web):

```bash
cp .env.example .env
```

El `.env` real **no se versiona**. Las credenciales nunca van en el código.

## Cómo arrancar

### Todo con Docker (recomendado para probar)

```bash
docker-compose up --build
```

Levanta PostgreSQL, el backend y el frontend tras Nginx. La app queda accesible en
el puerto que defina `docker-compose.yml` (ver su salida).

### Desarrollo (servicios por separado)

```bash
# Base de datos
docker-compose up -d postgres

# Backend (necesita las credenciales de BD en el entorno)
export $(grep -v '^#' .env | xargs)
export SPRING_DATASOURCE_USERNAME=$DB_USER SPRING_DATASOURCE_PASSWORD=$DB_PASSWORD
cd backend && ./gradlew bootRun

# Frontend
cd frontend && npm install && npm start
```

## Uso en la tablet (modo kiosko)

Monta la tablet en horizontal y abre el frontend en el navegador a pantalla
completa (Chrome admite modo kiosko). Apunta a la URL del frontend en la red local
del homelab. El niño selecciona su perfil y ve directamente las tareas del día.

## Tipografía accesible (OpenDyslexic)

La app usa **OpenDyslexic** como tipografía por defecto en todo el texto, pensada
para mejorar la legibilidad. Es una **preferencia conmutable por niño** (activada
de serie); al desactivarla, la UI cae a las tipografías de marca del handoff
(Fredoka/Nunito). Las tres familias se empaquetan en local (sin CDN), así que el
kiosko funciona sin internet. Detalle de la decisión en
[`docs/adr/0002-tipografia-opendyslexic.md`](docs/adr/0002-tipografia-opendyslexic.md).

## Backend: API y datos de ejemplo

Al arrancar con la base de datos vacía se siembran los datos del prototipo (niños
Nora 🦊, Leo 🐢 y Mía 🦉, su horario, rutinas, premios y eventos). El **PIN de
padres por defecto es `1234`** (configurable; no se puede cambiar el resto del
panel sin él).

Endpoints principales (kiosko del niño, acceso libre):

- `GET  /api/children` — perfiles.
- `GET  /api/children/{id}/today` — material de mañana, rutinas de tarde, eventos,
  progreso, monedero y temporizador.
- `POST /api/tasks/{taskId}/toggle` — marca/desmarca y ajusta monedas (con bonos).
- `GET  /api/children/{id}/wallet` — saldo e historial.
- `GET  /api/children/{id}/rewards` — tienda.
- `POST /api/rewards/{rewardId}/redeem?childId=` — canje.
- `PUT  /api/children/{id}/settings` — modo de vista, sonido, TTS, idioma, hora salida.

Panel de padres (requiere sesión; `POST /api/parents/login` con el PIN devuelve un
identificador que se envía en la cabecera `X-Parent-Session`): CRUD de niños,
catálogo, horario, rutinas, eventos, premios y ajuste de gamificación.

## Despliegue en el homelab

Construye las imágenes y levanta el `docker-compose` en el VPS o la Raspberry Pi.
Recuerda persistir el volumen de PostgreSQL y exponer el frontend tras tu proxy
(Nginx Proxy Manager / Cloudflare tunnel).

## Documentación

El detalle de UX, dominio, API y plan por fases está en `docs/`. El fichero
director (`docs/prompt-claude-code-recordalexia-director.md`) conduce el desarrollo.