# Migración: Evaluaciones en Línea (examenes-list)

Migración del módulo de exámenes en línea del lado **alumno**, desde el portal
legacy `F:\laragon\Jesistemas\uepca\` (BD `jesistem_uepca`) hacia el portal
multi-tenant `admin_alumnos/`. Probado end-to-end contra colegio 11
(`jesistem_juanxxiii`).

## Alcance

Solo se migró la vista del **estudiante** (listar, responder, ver resultados).
El lado **docente** (crear preguntas/exámenes, corregir texto libre —
`uepca/docentes/examen-*.php`) queda fuera de este trabajo: no existe todavía
un portal de docentes en este repo (igual que video/chat/tareas, ver
`CLAUDE.md` — "Known gap"). Ese flujo seguirá viniendo de una app externa que
escriba directamente en las tablas `examen_*` de la BD del colegio, tal como
hoy lo hace para `video{periodo}`, `comunica_docen`, etc.

## Archivos origen → destino

| Origen (`uepca/`)     | Destino (`admin_alumnos/`) | Rol |
|------------------------|------------------------------|-----|
| `examenes-list.php`    | `examenes-list.php`          | Listado (pendientes / resultados) |
| `examen-hacer.php`     | `examen-hacer.php`           | Responder evaluación (wizard pregunta a pregunta) |
| `examen-guarda.php`    | `examen-guarda.php`          | Procesa y guarda las respuestas |
| `examen-hecho.php`     | `examen-hecho.php`           | Ver resultados y calificación |
| `includes/funciones.php` (encriptar/desencriptar) | ya existía en `core/funciones.php` | reutilizado, no se duplicó |

No se migraron `examen-guarda-VIE.php`, `examenes-list-VIE.php`,
`examen-hacer-ORI.php`, `examen-hecho-ORI.php`, `examenes-list-ORI.php`
(variantes viejas/duplicadas del propio repo origen, sin uso vigente).

## Decisiones de diseño

- **Slug de módulo**: `examenes-list` (coincide con el nombre del archivo
  principal, mismo criterio que `cal-evaluaciones`). Se agregó al grupo de
  sidebar **Evaluaciones**, junto a Planificación Escolar y Calendario de
  Evaluaciones (`admin_alumnos/layout/base.php`).
- **Gating**: se agregó `examenes-list` a `MODULOS_CON_MOROSO` en
  `core/modulos.php` (igual que el resto de módulos académicos) y se llama
  `requiere_modulo('examenes-list')` + `verificar_no_moroso('examenes-list', true)`
  al inicio de `examenes-list.php`. Las páginas de acción
  (`examen-hacer.php`, `examen-hecho.php`, `examen-guarda.php`) solo validan
  sesión activa, igual que el patrón ya usado por `encuesta-hacer.php` /
  `encuesta-guarda.php` — se llega a ellas exclusivamente por enlace cifrado
  desde el listado.
- **Seguridad**: todas las consultas se reescribieron con *prepared
  statements* (`mysqli_prepare` + bind), incluyendo el flujo de
  `examen-guarda.php` que en el origen ya venía así (se conservó esa base) y
  el resto que en el origen usaba concatenación directa de `$_GET`/`$_POST`
  (se corrigió). Se agregó validación `ctype_digit()` sobre el `id_examen`
  desencriptado antes de usarlo en cualquier query.
- **UI/UX**: reskin completo a Bootstrap 4 + SB Admin 2 + Font Awesome,
  siguiendo el patrón exacto de `encuestas.php`/`encuesta-hacer.php` (tarjeta
  de datos del estudiante, tarjeta de contenido con `card-header` de color
  `ms-*`, `DataTable` en español, `SweetAlert2` para mensajes). No se innovó
  UI nueva — se copió la estructura ya validada en el propio `admin_alumnos`.
- **Bug corregido en la migración**: `examen-hecho.php` original leía
  `B.nombreMate` (camelCase) de `materiass{periodo}`, columna que en realidad
  es `nombremate` (minúsculas) — con collation/FS case-sensitive eso rompe.
  Se corrigió a `nombremate` en ambos archivos.
- **Imágenes de preguntas**: se sirven desde
  `https://<dominio-legacy-del-colegio>/imagen_question/<archivo>`, mismo
  patrón que ya usa el portal para `fotoalu/`/`fotorep/` (dominio legacy
  por colegio, no migrado a este repo — ver "Known gap" en `CLAUDE.md`).
  Si el módulo docente que suba imágenes de preguntas se construye a futuro,
  debe escribir ahí.

## Migración de base de datos

Archivo: **`db/fase9-evaluaciones-online.sql`** (no se tocó `fase1-esquema.sql`,
que ya está aplicado).

Tiene dos partes que se ejecutan contra bases de datos **distintas**:

### Parte A — `siscev` (una sola vez, catálogo global)

```
mysql -u root jesistem_siscev < db/fase9-evaluaciones-online.sql
```

⚠️ Este comando también intentará correr la Parte B (los `CREATE TABLE`) y
fallará en la primera sentencia de esa parte porque `siscev` no tiene esas
tablas de colegio — **es esperado**, la Parte A ya se aplicó antes de llegar
ahí. Si se prefiere evitar el error, copiar solo el bloque bajo
`-- PARTE A` y ejecutarlo aparte.

Verificar:
```sql
SELECT * FROM modulos WHERE slug='examenes-list';
```

### Parte B — BD de cada colegio que active el módulo

**Verificado que faltaban por completo en `jesistem_juanxxiii`** (no existía
ninguna tabla `examen_*` antes de esta migración — sí existían en la BD
legacy `jesistem_uepca`, de donde se copió la estructura 1:1, normalizando
collation a `utf8mb4`).

```
mysql -u root jesistem_juanxxiii < db/fase9-evaluaciones-online.sql
```

(Falla igual en la Parte A por no existir `modulos` en esa BD — igual de
esperado; las 7 tablas de la Parte B sí se crean. Para evitar el ruido,
correr solo desde `-- PARTE B` en adelante.)

Tablas creadas: `examen_varios`, `examen_pregunta`, `examen_preguntas`
(relación examen↔pregunta con su valor en puntos), `examen_opciones`,
`examen_respuesta`, `examen_notas`, `examen_vio` (registro de "visto"/abierto).

**Verificado en este ambiente**: se aplicó completo contra `jesistem_juanxxiii`,
se insertó un examen de prueba con una pregunta de cada tipo (simple, múltiple,
texto), se resolvió como alumno real (idAlum 16) a través de las 4 páginas
migradas vía HTTP, se confirmó nota calculada correctamente (20/30, con la
pregunta de texto en 0 pendiente de corrección docente) y se limpiaron los
datos de prueba al terminar.

## Activar el módulo para un colegio

1. Aplicar la Parte B de `fase9-evaluaciones-online.sql` contra la BD de ese
   colegio (si no se hizo ya).
2. En `panel_admin` → colegio → módulos → habilitar **Evaluaciones en Línea**.
   (O por SQL directo, ver comentario en la Parte A del archivo de migración.)
3. El grupo "Evaluaciones" del sidebar del alumno mostrará la nueva opción
   automáticamente vía `modulo_habilitado('examenes-list')`.

## Pendiente / fuera de este alcance

- Portal docente para crear/editar exámenes, preguntas, banco de opciones y
  corregir preguntas de texto libre (hoy en `uepca/docentes/examen-*.php`,
  externo a este repo).
- Carga de imágenes de preguntas (`imagen_question/`) — depende de dónde
  termine viviendo el módulo docente.