merge: feature/p0-p1-hardening-analytics-v3.5.0 into develop

Author: jdsalasca

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

@@ -33,8 +33,8 @@ mvn spring-boot:run
 - `GET /api/teacher/classrooms/{classroomId}/report.csv?from=YYYY-MM-DD&to=YYYY-MM-DD`
 
 ### Seguridad API (P0)
-- Header requerido para endpoints `/api/**` (excepto `/api/health`): `X-Api-Token`.
-- Alternativa recomendada: `Authorization: Bearer <accessToken>` emitido por `/api/auth/login`.
+- 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`
@@ -45,7 +45,9 @@ mvn spring-boot:run
   - `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`
@@ -67,5 +69,6 @@ mvn spring-boot:run
 - 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/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

@@ -11,6 +11,9 @@ public record ClassroomDashboardResponse(
         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/StudentProgressView.java

@@ -8,6 +8,7 @@ public record StudentProgressView(
         int averageScore,
         int averageCorrectAnswers,
         int averageProgressPercent,
+        int averageEffectiveMinutes,
         String dominantDifficulty
 ) {
 }

apps/backend/src/main/java/com/juegodefinitivo/autobook/persistence/game/GameSessionRuntimeRepository.java

@@ -13,6 +13,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.stream.Collectors;
 
 @Repository
 public class GameSessionRuntimeRepository {
@@ -132,7 +133,7 @@ public Optional<StoredSession> load(String sessionId) {
                         SELECT session_id, player_name, book_path, book_title, current_scene,
                                life, knowledge, courage, focus, score, correct_answers,
                                discoveries, completed, inventory_json, narrative_memory_json,
-                               challenge_attempts, challenge_correct, last_message
+                               challenge_attempts, challenge_correct, last_message, updated_at
                         FROM game_sessions
                         WHERE session_id = ?
                         """,
@@ -157,14 +158,34 @@ public Optional<StoredSession> load(String sessionId) {
                             fromJson(rs.getString("narrative_memory_json")),
                             rs.getInt("challenge_attempts"),
                             rs.getInt("challenge_correct"),
-                            rs.getString("last_message")
+                            rs.getString("last_message"),
+                            rs.getTimestamp("updated_at").toInstant()
                     );
                 },
                 sessionId
         );
         return rows.stream().findFirst();
     }
 
+    public Map<String, Instant> findLastUpdatedAt(List<String> sessionIds) {
+        if (sessionIds == null || sessionIds.isEmpty()) {
+            return Map.of();
+        }
+        String placeholders = sessionIds.stream().map(id -> "?").collect(Collectors.joining(", "));
+        String sql = "SELECT session_id, updated_at FROM game_sessions WHERE session_id IN (" + placeholders + ")";
+        return jdbcTemplate.query(
+                sql,
+                (rs) -> {
+                    Map<String, Instant> bySession = new LinkedHashMap<>();
+                    while (rs.next()) {
+                        bySession.put(rs.getString("session_id"), rs.getTimestamp("updated_at").toInstant());
+                    }
+                    return bySession;
+                },
+                sessionIds.toArray()
+        );
+    }
+
     private String toJson(Map<String, Integer> value) {
         try {
             return objectMapper.writeValueAsString(value == null ? Map.of() : value);
@@ -197,7 +218,8 @@ public record StoredSession(
             Map<String, Integer> narrativeMemory,
             int challengeAttempts,
             int challengeCorrect,
-            String lastMessage
+            String lastMessage,
+            Instant updatedAt
     ) {
     }
 }

apps/backend/src/main/java/com/juegodefinitivo/autobook/security/ApiAuthInterceptor.java

@@ -62,6 +62,9 @@ private ApiRole resolveRole(HttpServletRequest request) {
                 return verified.get().role();
             }
         }
+        if (!properties.allowLegacyToken()) {
+            return null;
+        }
         String token = request.getHeader(TOKEN_HEADER);
         if (token == null || token.isBlank()) {
             return null;

apps/backend/src/main/java/com/juegodefinitivo/autobook/security/ApiSecurityProperties.java

@@ -17,7 +17,9 @@ public class ApiSecurityProperties {
     private final String adminUsername;
     private final String adminPassword;
     private final String jwtSecret;
+    private final String jwtPreviousSecret;
     private final long jwtTtlSeconds;
+    private final boolean allowLegacyToken;
 
     public ApiSecurityProperties(
             @Value("${app.security.enabled:true}") boolean enabled,
@@ -31,7 +33,9 @@ public ApiSecurityProperties(
             @Value("${app.security.admin-username:admin}") String adminUsername,
             @Value("${app.security.admin-password:admin-pass}") String adminPassword,
             @Value("${app.security.jwt-secret:change-this-secret-in-production}") String jwtSecret,
-            @Value("${app.security.jwt-ttl-seconds:28800}") long jwtTtlSeconds
+            @Value("${app.security.jwt-previous-secret:}") String jwtPreviousSecret,
+            @Value("${app.security.jwt-ttl-seconds:28800}") long jwtTtlSeconds,
+            @Value("${app.security.allow-legacy-token:true}") boolean allowLegacyToken
     ) {
         this.enabled = enabled;
         this.studentToken = studentToken == null ? "" : studentToken.trim();
@@ -44,7 +48,9 @@ public ApiSecurityProperties(
         this.adminUsername = adminUsername == null ? "" : adminUsername.trim();
         this.adminPassword = adminPassword == null ? "" : adminPassword.trim();
         this.jwtSecret = jwtSecret == null ? "" : jwtSecret.trim();
+        this.jwtPreviousSecret = jwtPreviousSecret == null ? "" : jwtPreviousSecret.trim();
         this.jwtTtlSeconds = Math.max(300, jwtTtlSeconds);
+        this.allowLegacyToken = allowLegacyToken;
     }
 
     public boolean enabled() {
@@ -94,4 +100,12 @@ public String jwtSecret() {
     public long jwtTtlSeconds() {
         return jwtTtlSeconds;
     }
+
+    public String jwtPreviousSecret() {
+        return jwtPreviousSecret;
+    }
+
+    public boolean allowLegacyToken() {
+        return allowLegacyToken;
+    }
 }

apps/backend/src/main/java/com/juegodefinitivo/autobook/security/AuthTokenService.java

@@ -10,6 +10,7 @@
 import java.security.MessageDigest;
 import java.time.Instant;
 import java.util.Base64;
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 
@@ -28,6 +29,9 @@ public AuthTokenService(ApiSecurityProperties properties, ObjectMapper objectMap
 
     public IssuedToken issue(String username, ApiRole role) {
         try {
+            if (properties.jwtSecret().isBlank()) {
+                throw new IllegalStateException("JWT secret vacio. Configura app.security.jwt-secret.");
+            }
             long issuedAt = Instant.now().getEpochSecond();
             long expiresAt = issuedAt + properties.jwtTtlSeconds();
             Map<String, Object> payload = Map.of(
@@ -57,8 +61,7 @@ public Optional<VerifiedToken> verify(String token) {
             }
             String payloadEncoded = parts[0];
             String signature = parts[1];
-            String expected = sign(payloadEncoded);
-            if (!MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), signature.getBytes(StandardCharsets.UTF_8))) {
+            if (!verifySignature(payloadEncoded, signature)) {
                 return Optional.empty();
             }
             byte[] payloadBytes = Base64.getUrlDecoder().decode(payloadEncoded);
@@ -76,9 +79,30 @@ public Optional<VerifiedToken> verify(String token) {
         }
     }
 
+    private boolean verifySignature(String payloadEncoded, String signature) throws Exception {
+        for (String secret : candidateSecrets()) {
+            if (secret.isBlank()) {
+                continue;
+            }
+            String expected = sign(payloadEncoded, secret);
+            if (MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), signature.getBytes(StandardCharsets.UTF_8))) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private List<String> candidateSecrets() {
+        return List.of(properties.jwtSecret(), properties.jwtPreviousSecret());
+    }
+
     private String sign(String payloadEncoded) throws Exception {
+        return sign(payloadEncoded, properties.jwtSecret());
+    }
+
+    private String sign(String payloadEncoded, String secret) throws Exception {
         Mac mac = Mac.getInstance("HmacSHA256");
-        SecretKeySpec key = new SecretKeySpec(properties.jwtSecret().getBytes(StandardCharsets.UTF_8), "HmacSHA256");
+        SecretKeySpec key = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
         mac.init(key);
         byte[] digest = mac.doFinal(payloadEncoded.getBytes(StandardCharsets.UTF_8));
         return Base64.getUrlEncoder().withoutPadding().encodeToString(digest);

apps/backend/src/main/java/com/juegodefinitivo/autobook/service/TeacherWorkspaceService.java

@@ -1,11 +1,13 @@
 package com.juegodefinitivo.autobook.service;
 
 import com.juegodefinitivo.autobook.api.dto.AssignmentView;
+import com.juegodefinitivo.autobook.api.dto.ActivityAbandonmentView;
 import com.juegodefinitivo.autobook.api.dto.ClassroomDashboardResponse;
 import com.juegodefinitivo.autobook.api.dto.ClassroomView;
 import com.juegodefinitivo.autobook.api.dto.GameStateResponse;
 import com.juegodefinitivo.autobook.api.dto.StudentProgressView;
 import com.juegodefinitivo.autobook.api.dto.StudentView;
+import com.juegodefinitivo.autobook.persistence.game.GameSessionRuntimeRepository;
 import com.juegodefinitivo.autobook.persistence.teacher.TeacherWorkspaceRepository;
 import org.springframework.stereotype.Service;
 
@@ -24,10 +26,16 @@ public class TeacherWorkspaceService {
 
     private final TeacherWorkspaceRepository repository;
     private final GameFacadeService gameFacadeService;
+    private final GameSessionRuntimeRepository runtimeRepository;
 
-    public TeacherWorkspaceService(TeacherWorkspaceRepository repository, GameFacadeService gameFacadeService) {
+    public TeacherWorkspaceService(
+            TeacherWorkspaceRepository repository,
+            GameFacadeService gameFacadeService,
+            GameSessionRuntimeRepository runtimeRepository
+    ) {
         this.repository = repository;
         this.gameFacadeService = gameFacadeService;
+        this.runtimeRepository = runtimeRepository;
     }
 
     public List<ClassroomView> listClassrooms() {
@@ -122,10 +130,15 @@ public ClassroomDashboardResponse getDashboard(String classroomId, LocalDate fro
         List<TeacherWorkspaceRepository.StudentRow> students = repository.listStudents(classroomId);
         List<TeacherWorkspaceRepository.AssignmentRow> assignments = repository.listAssignments(classroomId);
         List<TeacherWorkspaceRepository.AttemptRow> attempts = loadAttempts(classroomId, from, to);
+        Map<String, Instant> runtimeUpdatesBySession = runtimeRepository.findLastUpdatedAt(
+                attempts.stream().map(TeacherWorkspaceRepository.AttemptRow::sessionId).toList()
+        );
 
         List<StudentProgressView> progressViews = new ArrayList<>();
         int totalAttempts = 0;
         int totalCompletedAttempts = 0;
+        int totalEffectiveMinutes = 0;
+        Map<String, Integer> activeByActivity = new LinkedHashMap<>();
         for (TeacherWorkspaceRepository.StudentRow student : students) {
             List<TeacherWorkspaceRepository.AttemptRow> studentAttempts = attempts.stream()
                     .filter(attempt -> attempt.studentId().equals(student.id()))
@@ -141,8 +154,20 @@ public ClassroomDashboardResponse getDashboard(String classroomId, LocalDate fro
             int avgProgress = (int) states.stream().mapToInt(this::progressPercent).average().orElse(0);
             int completed = (int) states.stream().filter(GameStateResponse::completed).count();
             String difficulty = dominantDifficulty(states);
+            int totalMinutesByStudent = studentAttempts.stream()
+                    .mapToInt(attempt -> effectiveMinutes(attempt, runtimeUpdatesBySession))
+                    .sum();
+            int avgEffectiveMinutes = studentAttempts.isEmpty() ? 0 : totalMinutesByStudent / studentAttempts.size();
             totalAttempts += studentAttempts.size();
             totalCompletedAttempts += completed;
+            totalEffectiveMinutes += totalMinutesByStudent;
+
+            for (GameStateResponse state : states) {
+                if (!state.completed()) {
+                    String eventType = state.currentScene() == null ? "UNKNOWN" : state.currentScene().eventType();
+                    activeByActivity.merge(eventType, 1, Integer::sum);
+                }
+            }
 
             progressViews.add(new StudentProgressView(
                     student.id(),
@@ -152,6 +177,7 @@ public ClassroomDashboardResponse getDashboard(String classroomId, LocalDate fro
                     avgScore,
                     avgCorrect,
                     avgProgress,
+                    avgEffectiveMinutes,
                     difficulty
             ));
         }
@@ -160,6 +186,15 @@ public ClassroomDashboardResponse getDashboard(String classroomId, LocalDate fro
         int abandonmentRatePercent = totalAttempts == 0
                 ? 0
                 : (int) ((activeAttempts / (double) totalAttempts) * 100);
+        int averageEffectiveMinutesPerAttempt = totalAttempts == 0 ? 0 : totalEffectiveMinutes / totalAttempts;
+        List<ActivityAbandonmentView> abandonmentByActivity = activeByActivity.entrySet().stream()
+                .map(entry -> new ActivityAbandonmentView(
+                        entry.getKey(),
+                        entry.getValue(),
+                        activeAttempts == 0 ? 0 : (int) ((entry.getValue() / (double) activeAttempts) * 100)
+                ))
+                .sorted((left, right) -> Integer.compare(right.activeAttempts(), left.activeAttempts()))
+                .toList();
 
         return new ClassroomDashboardResponse(
                 classroom.id(),
@@ -170,6 +205,9 @@ public ClassroomDashboardResponse getDashboard(String classroomId, LocalDate fro
                 activeAttempts,
                 totalCompletedAttempts,
                 abandonmentRatePercent,
+                totalEffectiveMinutes,
+                averageEffectiveMinutesPerAttempt,
+                abandonmentByActivity,
                 progressViews
         );
     }
@@ -181,7 +219,7 @@ public String exportClassroomCsv(String classroomId) {
     public String exportClassroomCsv(String classroomId, LocalDate from, LocalDate to) {
         ClassroomDashboardResponse dashboard = getDashboard(classroomId, from, to);
         StringBuilder csv = new StringBuilder();
-        csv.append("classroom_id,classroom_name,teacher,student_id,student_name,attempts,completed_attempts,avg_score,avg_correct_answers,avg_progress_percent,dominant_difficulty")
+        csv.append("classroom_id,classroom_name,teacher,student_id,student_name,attempts,completed_attempts,avg_score,avg_correct_answers,avg_progress_percent,avg_effective_minutes,dominant_difficulty")
                 .append('\n');
         for (StudentProgressView view : dashboard.studentProgress()) {
             csv.append(csv(dashboard.classroomId())).append(',')
@@ -194,9 +232,25 @@ public String exportClassroomCsv(String classroomId, LocalDate from, LocalDate t
                     .append(view.averageScore()).append(',')
                     .append(view.averageCorrectAnswers()).append(',')
                     .append(view.averageProgressPercent()).append(',')
+                    .append(view.averageEffectiveMinutes()).append(',')
                     .append(csv(view.dominantDifficulty()))
                     .append('\n');
         }
+        csv.append('\n');
+        csv.append("summary_metric,summary_value").append('\n');
+        csv.append("active_attempts,").append(dashboard.activeAttempts()).append('\n');
+        csv.append("completed_attempts,").append(dashboard.completedAttempts()).append('\n');
+        csv.append("abandonment_rate_percent,").append(dashboard.abandonmentRatePercent()).append('\n');
+        csv.append("total_effective_reading_minutes,").append(dashboard.totalEffectiveReadingMinutes()).append('\n');
+        csv.append("average_effective_minutes_per_attempt,").append(dashboard.averageEffectiveMinutesPerAttempt()).append('\n');
+        csv.append('\n');
+        csv.append("abandonment_activity,active_attempts,active_rate_percent").append('\n');
+        for (ActivityAbandonmentView activity : dashboard.abandonmentByActivity()) {
+            csv.append(csv(activity.eventType())).append(',')
+                    .append(activity.activeAttempts()).append(',')
+                    .append(activity.activeRatePercent())
+                    .append('\n');
+        }
         return csv.toString();
     }
 
@@ -298,6 +352,13 @@ private String dominantDifficulty(List<GameStateResponse> states) {
                 .orElse("UNKNOWN");
     }
 
+    private int effectiveMinutes(TeacherWorkspaceRepository.AttemptRow attempt, Map<String, Instant> runtimeUpdatesBySession) {
+        Instant updated = runtimeUpdatesBySession.getOrDefault(attempt.sessionId(), attempt.createdAt());
+        long seconds = Math.max(0L, updated.getEpochSecond() - attempt.createdAt().getEpochSecond());
+        int minutes = (int) Math.max(1, seconds / 60);
+        return Math.min(minutes, 240);
+    }
+
     private List<TeacherWorkspaceRepository.AttemptRow> loadAttempts(String classroomId, LocalDate from, LocalDate to) {
         if (from == null || to == null) {
             return repository.listAttemptsForClassroom(classroomId);