recordalexia/docs/prompt-claude-code-backend-rutinas-tdah.md

Backend de recordaLexia (app de rutinas para niños con TDAH) — Spring Boot 3 / Java 21

Objetivo

Implementa el backend de una app web familiar (uso doméstico, homelab) que presenta a niños con TDAH sus tareas del día: material para el cole por la mañana y rutinas de la tarde, con gamificación por monedas y tienda de recompensas. Los padres configuran horario, eventos y premios. Es MULTI-NIÑO y BILINGÜE (español / catalán).

Trabajas en LOCAL. No despliegues en nube ni asumas infraestructura corporativa.

Stack (NADA corporativo: ni Keycloak, ni Gravitee, ni Camunda, ni K8s, ni Jenkins)

• Java 21, Spring Boot 3.x, Gradle 8.
• PostgreSQL (Liquibase para el esquema).
• Spring Web (REST), Spring Data JPA, Spring Security (auth ligera, ver abajo).
• Arquitectura limpia por capas (controller / service / repository / domain). No hace falta hexagonal completa, pero mantén el dominio aislado de JPA donde sea razonable.
• Docker multi-stage + docker-compose (postgres + backend; deja hueco para el frontend Angular tras Nginx).
• Comenta el código en español, sobre todo la lógica de negocio.

i18n (requisito derivado del diseño)

La UI es ES/CA. Todos los textos visibles para el niño (materiales, actividades, rutinas, premios, tipos de evento) deben almacenarse con sus dos variantes: campos labelEs y labelCa (o una tabla de traducciones, a tu criterio). La API devuelve ambas y el frontend elige según el idioma activo.

Modelo de dominio

• Child: id, name, mascot (emoji), accentColor, age, coins (saldo), departureTime (hora de salida de la mañana, para el temporizador), y ajustes: viewMode (BOARD | FOCUS), soundEnabled, ttsEnabled, language (ES | CA).
• ParentUser: credenciales del panel de padres (PIN configurable, no hardcodeado).
• Activity (actividad del cole, p. ej. "Gimnasia"): id, labelEs, labelCa, icon (emoji), color.
• MaterialItem: id, labelEs, labelCa, icon (emoji), color, categoría. Relación N:M con Activity (Gimnasia -> equipación, zapatillas, toalla, agua).
• WeeklyTemplateEntry: plantilla recurrente. childId, dayOfWeek (LUN–VIE), slot (MORNING | AFTERNOON), referencia a Activity (mañana) o a una rutina de tarde, order (para reordenar), coinsReward. Define "lo normal" de cada día.
• AfternoonRoutine: rutina de tarde recurrente. childId, dayOfWeek, labelEs, labelCa, icon, color, order. (Reordenables en el panel de padres.)
• SpecialEvent: childId, date, type (EXAM | HOMEWORK), titleEs, titleCa, icon, color.
• DailyTask: INSTANCIA de un día. childId, date, slot, labelEs, labelCa, icon, color, status (PENDING | DONE), coinsReward, completedAt, origen (plantilla o evento).
• CoinTransaction: childId, date, amount (positivo al ganar, negativo al canjear), motivo.
• Reward: premio canjeable. labelEs, labelCa, icon, color, cost (monedas), active.
• RewardRedemption: childId, rewardId, date, cost.

Lógica de negocio clave

• Generación del día: al pedir el día de hoy (o vía scheduler matutino), si no existen DailyTask para childId+fecha, se generan desde (a) WeeklyTemplateEntry y rutinas del dayOfWeek y (b) SpecialEvent de esa fecha. Idempotente.
• Marcar DailyTask como DONE: cambiar estado, registrar completedAt, sumar coinsReward, crear CoinTransaction. Si se desmarca, revertir de forma coherente.
• Bono por completar bloque (mañana/tarde) y por completar el día entero: aplica coinsPerBlock / coinsPerDay configurables (ver gamificación).
• Tienda: al canjear, validar saldo suficiente, descontar, crear CoinTransaction (negativa) y RewardRedemption. Si no llega, devolver error claro ("te faltan N").
• Progreso del día por slot y global, por niño.
• Zona horaria fija (Europe/Madrid) para decidir qué es "hoy".
• Conservar histórico de DailyTask y canjes (no borrar al pasar el día).

Gamificación (configurable)

Parámetros por niño (o globales con override por niño): coinsPerTask (def. 5), coinsPerBlock (def. 10), coinsPerDay (def. 20). Expónlos para que el panel de padres los edite.

API REST (orientativa, ajústala con criterio)

• GET /api/children -> perfiles (con mascot, color, edad, coins).
• GET /api/children/{id}/today -> { morning[], afternoon[], specialEvents[], progress, wallet, timer } (timer derivado de departureTime).
• POST /api/tasks/{taskId}/toggle -> marca/desmarca y ajusta monedas.
• GET /api/children/{id}/wallet -> saldo + historial.
• GET /api/children/{id}/rewards -> tienda visible para ese niño.
• POST /api/rewards/{rewardId}/redeem -> canje (valida saldo, descuenta).
• PUT /api/children/{id}/settings -> viewMode, sound, tts, language, departureTime.
• Panel de padres (requiere auth):
  • CRUD de Child.
  • CRUD de Activity y MaterialItem (con icon, color, labelEs/labelCa, asociaciones).
  • CRUD de WeeklyTemplateEntry (horario por niño).
  • CRUD de AfternoonRoutine (con order).
  • CRUD de SpecialEvent.
  • CRUD de Reward.
  • PUT de parámetros de gamificación.

Seguridad (ligera, doméstica)

• Modo kiosko (niño): lectura + marcar tareas + canjear, sin login molesto (token de dispositivo o sesión persistente del kiosko).
• Panel de padres: protegido por PIN configurable. Roles CHILD y PARENT.
• Sin Keycloak/OAuth2 en esta fase; déjalo encapsulado por si se externaliza luego.

Datos semilla (reproducir el prototipo de Claude Design)

• Niños: Nora 🦊 (#F2A65A, 7, 42 monedas), Leo 🐢 (#5BC0BE, 9, 28), Mía 🦉 (#A78BD0, 6, 55).
• Material de cole (ES/CA): estuche/estoig ✏️, libro de mates/llibre de mates 📘, flauta 🎵, ropa de gimnasia/roba d'EF 👕, zapatillas/sabatilles 👟, almuerzo/esmorzar 🍎.
• Rutinas de tarde: deshacer la mochila/buidar la motxilla 🎒, merendar/berenar 🥪, hacer los deberes/fer els deures 📝, practicar piano 🎹, recoger la mesa/parar taula 🍽️.
• Actividades: Gimnasia 🤸 (equipación, zapatillas, toalla, agua), Música 🎵 (flauta, libreta), Matemáticas 📘 (libro, regla, estuche), Lengua 📖 (lectura, cuaderno).
• Premios (ES/CA): 30 min tablet/tauleta 🎮 (20), peli en familia/pel·lícula 🍿 (50), tarde en el parque/tarda al parc 🛝 (40), elijo la cena/trio el sopar 🍕 (30), 30 min más despierto/més despert 🌙 (60), sorpresa dino 🦖 (80).
• Una semana de plantilla de ejemplo y un par de eventos (Examen de Lengua 📋, Ficha de mates 📎) para poder probar /today al arrancar.
• PIN de padres por defecto 1234 (configurable).

Entregables

• Proyecto Gradle compilable, estructura por capas.
• Entidades JPA + Liquibase + datos semilla anteriores.
• Controladores REST con DTOs (no exponer entidades), con labelEs/labelCa.
• Tests unitarios de generación del día, marcado/monedas (incl. bonos de bloque/día) y canje de premios (JUnit 5 + Mockito; integración con MockMvc en endpoints clave).
• Dockerfile multi-stage + docker-compose.yml (postgres + backend).
• README breve: arranque local y notas para el homelab.