release: merge develop into main for v3.5.0

Author: jdsalasca

AGENTS.md

@@ -15,6 +15,7 @@ Mantener y evolucionar una plataforma educativa que transforma libros en aventur
 - Arquitectura por capas backend: `domain`, `engine`, `persistence`, `service`, `api`.
 - Estructura monorepo: `apps/backend`, `apps/frontend`, `docs`, `scripts`.
 - No mezclar entrada/salida con reglas de dominio.
+- Priorizacion vigente y criterios de revision interna: `docs/PRIORITY_REQUIREMENTS.md`.
 
 ## Flujo de ramas
 - `main`: produccion.
@@ -24,6 +25,7 @@ Mantener y evolucionar una plataforma educativa que transforma libros en aventur
 
 ## Definicion de terminado
 - Backend `mvn test` en verde.
+- Frontend `npm run test` en verde.
 - Frontend `npm run build` en verde.
 - CI sin fallos.
 - Documentacion actualizada para cambios de UX/arquitectura.

README.md

@@ -50,10 +50,11 @@ Abrir: `http://localhost:5173`
 4. Para continuar luego, usa `Cargar sesion` con el `sessionId` (tambien se recuerda automaticamente en el navegador).
 
 ## Release desktop
-- Release publico actual: `v3.4.0`
+- Release publico actual: `v3.5.0`
 - Incluye `AutoBookQuest-win64.zip` (portable con `AutoBookQuest.exe`).
 - Para instalador `.exe` tipo setup con `jpackage`, se requiere WiX v3 instalado.
 - El workflow `release` publica tambien `latest.json` para auto-update.
+- Notas del release: `docs/RELEASE_NOTES_v3.5.0.md`.
 
 ## Calidad
 - Backend: `mvn test`

apps/backend/README.md

@@ -11,6 +11,7 @@ mvn spring-boot:run
 
 ## API
 - `GET /api/health`
+- `POST /api/auth/login` body: `{ "username": "...", "password": "..." }`
 - `GET /api/books`
 - `POST /api/books/import` body: `{ "path": "file:///C:/.../libro.pdf" }`
 - `POST /api/game/start` body: `{ "playerName": "Juan", "bookPath": "C:/.../libro.pdf" }`
@@ -28,7 +29,29 @@ mvn spring-boot:run
 - `GET /api/teacher/classrooms/{classroomId}/assignments`
 - `POST /api/teacher/attempts/link`
 - `GET /api/teacher/classrooms/{classroomId}/dashboard`
-- `GET /api/teacher/classrooms/{classroomId}/report.csv`
+- `GET /api/teacher/classrooms/{classroomId}/dashboard?from=YYYY-MM-DD&to=YYYY-MM-DD`
+- `GET /api/teacher/classrooms/{classroomId}/report.csv?from=YYYY-MM-DD&to=YYYY-MM-DD`
+
+### Seguridad API (P0)
+- Recomendado: `Authorization: Bearer <accessToken>` emitido por `/api/auth/login`.
+- Compatibilidad legacy opcional: `X-Api-Token` (controlado por `app.security.allow-legacy-token`).
+- Tokens por rol configurables en `application.properties`:
+  - `app.security.student-token`
+  - `app.security.teacher-token`
+  - `app.security.admin-token`
+- Credenciales por rol para login:
+  - `app.security.student-username` / `app.security.student-password`
+  - `app.security.teacher-username` / `app.security.teacher-password`
+  - `app.security.admin-username` / `app.security.admin-password`
+- Firma y expiracion del token bearer:
+  - `app.security.jwt-secret`
+  - `app.security.jwt-previous-secret` (ventana de rotacion)
+  - `app.security.jwt-ttl-seconds`
+  - `app.security.allow-legacy-token`
+- Rate limit basico configurable:
+  - `app.rate-limit.window-seconds`
+  - `app.rate-limit.max-requests`
+  - `app.rate-limit.teacher-max-requests`
 
 ## Arquitectura
 - `domain`: entidades de juego.
@@ -44,4 +67,8 @@ mvn spring-boot:run
 - El frontend empaquetado se copia a `src/main/resources/static` solo durante build desktop.
 - El pipeline narrativo incluye normalizacion de texto, memoria de entidades, grafo de relaciones y nivel cognitivo por escena.
 - Persistencia docente sobre JDBC + Flyway (`classrooms`, `students`, `assignments`, `attempts`).
+- Persistencia runtime de sesiones de juego sobre JDBC + Flyway (`game_sessions`).
+- Vinculacion de intentos docente protegida contra duplicados (`student_id + assignment_id + session_id`).
+- Dashboard docente incluye tiempo efectivo y abandono por actividad real.
 - Default local con H2 file DB; PostgreSQL habilitado por variables de entorno Spring datasource.
+- Importacion de libros restringida a `.txt` y `.pdf` con limite configurable (`app.import.max-bytes`, default 25MB).

apps/backend/src/main/java/com/juegodefinitivo/autobook/api/ApiInterceptorsConfig.java

@@ -0,0 +1,25 @@
+package com.juegodefinitivo.autobook.api;
+
+import com.juegodefinitivo.autobook.security.ApiAuthInterceptor;
+import com.juegodefinitivo.autobook.security.RateLimitInterceptor;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+public class ApiInterceptorsConfig implements WebMvcConfigurer {
+
+    private final ApiAuthInterceptor apiAuthInterceptor;
+    private final RateLimitInterceptor rateLimitInterceptor;
+
+    public ApiInterceptorsConfig(ApiAuthInterceptor apiAuthInterceptor, RateLimitInterceptor rateLimitInterceptor) {
+        this.apiAuthInterceptor = apiAuthInterceptor;
+        this.rateLimitInterceptor = rateLimitInterceptor;
+    }
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        registry.addInterceptor(apiAuthInterceptor).addPathPatterns("/api/**");
+        registry.addInterceptor(rateLimitInterceptor).addPathPatterns("/api/**");
+    }
+}

apps/backend/src/main/java/com/juegodefinitivo/autobook/api/AuthController.java

@@ -0,0 +1,49 @@
+package com.juegodefinitivo.autobook.api;
+
+import com.juegodefinitivo.autobook.api.dto.LoginRequest;
+import com.juegodefinitivo.autobook.api.dto.LoginResponse;
+import com.juegodefinitivo.autobook.security.AuthService;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.util.Map;
+
+@RestController
+@RequestMapping("/api/auth")
+public class AuthController {
+
+    private final AuthService authService;
+
+    public AuthController(AuthService authService) {
+        this.authService = authService;
+    }
+
+    @PostMapping("/login")
+    public LoginResponse login(@RequestBody LoginRequest request) {
+        return authService.login(request.username(), request.password())
+                .map(result -> new LoginResponse(
+                        result.token(),
+                        "Bearer",
+                        result.role().name(),
+                        result.expiresAtEpochSeconds()
+                ))
+                .orElseThrow(() -> new IllegalArgumentException("Credenciales invalidas."));
+    }
+
+    @ExceptionHandler(IllegalArgumentException.class)
+    @ResponseStatus(HttpStatus.UNAUTHORIZED)
+    public Map<String, String> onUnauthorized(IllegalArgumentException ex) {
+        return Map.of("error", ex.getMessage());
+    }
+
+    @ExceptionHandler(Exception.class)
+    public void onError(Exception ex) {
+        throw new ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Error interno", ex);
+    }
+}

apps/backend/src/main/java/com/juegodefinitivo/autobook/api/CorsConfig.java

@@ -10,6 +10,7 @@ public class CorsConfig implements WebMvcConfigurer {
     public void addCorsMappings(CorsRegistry registry) {
         registry.addMapping("/api/**")
                 .allowedOrigins("http://localhost:5173", "http://127.0.0.1:5173")
-                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS");
+                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
+                .allowedHeaders("*");
     }
 }

apps/backend/src/main/java/com/juegodefinitivo/autobook/api/TeacherController.java

@@ -12,15 +12,22 @@
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.ResponseStatus;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
 
 import java.nio.charset.StandardCharsets;
+import java.time.LocalDate;
 import java.util.List;
+import java.util.Map;
 
 @RestController
 @RequestMapping("/api/teacher")
@@ -68,16 +75,35 @@ public void linkAttempt(@RequestBody LinkAttemptRequest request) {
     }
 
     @GetMapping("/classrooms/{classroomId}/dashboard")
-    public ClassroomDashboardResponse getDashboard(@PathVariable String classroomId) {
-        return workspaceService.getDashboard(classroomId);
+    public ClassroomDashboardResponse getDashboard(
+            @PathVariable String classroomId,
+            @RequestParam(required = false) LocalDate from,
+            @RequestParam(required = false) LocalDate to
+    ) {
+        return workspaceService.getDashboard(classroomId, from, to);
     }
 
     @GetMapping(value = "/classrooms/{classroomId}/report.csv", produces = "text/csv")
-    public ResponseEntity<byte[]> exportCsv(@PathVariable String classroomId) {
-        String csv = workspaceService.exportClassroomCsv(classroomId);
+    public ResponseEntity<byte[]> exportCsv(
+            @PathVariable String classroomId,
+            @RequestParam(required = false) LocalDate from,
+            @RequestParam(required = false) LocalDate to
+    ) {
+        String csv = workspaceService.exportClassroomCsv(classroomId, from, to);
         return ResponseEntity.ok()
                 .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"classroom-" + classroomId + "-report.csv\"")
                 .contentType(new MediaType("text", "csv", StandardCharsets.UTF_8))
                 .body(csv.getBytes(StandardCharsets.UTF_8));
     }
+
+    @ExceptionHandler(IllegalArgumentException.class)
+    @ResponseStatus(HttpStatus.BAD_REQUEST)
+    public Map<String, String> onBadRequest(IllegalArgumentException ex) {
+        return Map.of("error", ex.getMessage());
+    }
+
+    @ExceptionHandler(Exception.class)
+    public void onError(Exception ex) {
+        throw new ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Error interno", ex);
+    }
 }

apps/backend/src/main/java/com/juegodefinitivo/autobook/api/dto/ActivityAbandonmentView.java

@@ -0,0 +1,8 @@
+package com.juegodefinitivo.autobook.api.dto;
+
+public record ActivityAbandonmentView(
+        String eventType,
+        int activeAttempts,
+        int activeRatePercent
+) {
+}

apps/backend/src/main/java/com/juegodefinitivo/autobook/api/dto/ClassroomDashboardResponse.java

@@ -8,6 +8,12 @@ public record ClassroomDashboardResponse(
         String teacherName,
         int students,
         int assignments,
+        int activeAttempts,
+        int completedAttempts,
+        int abandonmentRatePercent,
+        int totalEffectiveReadingMinutes,
+        int averageEffectiveMinutesPerAttempt,
+        List<ActivityAbandonmentView> abandonmentByActivity,
         List<StudentProgressView> studentProgress
 ) {
 }

apps/backend/src/main/java/com/juegodefinitivo/autobook/api/dto/LoginRequest.java

@@ -0,0 +1,7 @@
+package com.juegodefinitivo.autobook.api.dto;
+
+public record LoginRequest(
+        String username,
+        String password
+) {
+}