feat: app completa recordaLexia (fases 1-5)
App web familiar de rutinas visuales para niños con TDAH: muestra cada día el material del cole y las rutinas de tarde, con gamificación por monedas y tienda de recompensas. Multi-niño y bilingüe ES/CA. Uso doméstico/homelab. Backend (Spring Boot 3.5 / Java 21 / Gradle): - Dominio por capas, PostgreSQL + Liquibase, datos semilla. - API REST con DTOs: /today, toggle con monedas y bonos de bloque/día, monedero, tienda/canje, ajustes y CRUD del panel de padres. - Seguridad ligera por PIN (BCrypt + sesion en memoria), sin Keycloak. - Tests JUnit: generacion del dia, monedas/bonos con reversion, canje, seguridad. Frontend (Angular 19, standalone + signals): - Perfiles, Home (Tablero y Foco), Tienda y panel de padres (5 pestañas). - Tipografia OpenDyslexic conmutable (accesibilidad), i18n ES/CA, TTS y sonido. - Tokens de diseño fieles al handoff (paleta, animaciones, monedas voladoras). Empaquetado: - Docker multi-stage + docker-compose (PostgreSQL + backend + Nginx). - Decisiones de arquitectura documentadas en docs/adr.
This commit is contained in:
Jaume Garriga Maestre
140
README.md
Normal file
140
README.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user