# Migración: Portal Docentes — Fase 3 (Aula Virtual)

Cuarta fase de la migración de `uepca/docentes/` hacia `admin_docentes/`
(ver `migracion_de_modulo_docentes.md` para el plan completo). Cubre la
publicación de material de clases (con tareas/fecha máxima de entrega) y de
video-clases, para Primaria y Bachillerato/Liceo. El código de esta fase ya
existía en el repo (commit `d34f5e1`, hecho en la misma sesión que el lado
alumno de Evaluaciones en Línea) pero sin verificación end-to-end ni este
documento — este trabajo cierra ese pendiente.

## Alcance

| Origen (`uepca/docentes/`) | Destino (`admin_docentes/`) | Rol |
|---|---|---|
| `archivosMateria.php`, `list-tareas.php`, `list-tareasPri.php`, `verTarea.php`, `verTareaPri.php`, `bus-gra-secMae.php` | `material.php` | Selector grado/sección(/materia en Bachillerato) + subir material con fecha de publicación/entrega + listado + eliminar |
| `videoMateriaDoc.php`, `videoListPri.php`, `videoListBach.php`, `buscarVideo.php`, `buscarVideoPri.php`, `busGraVid.php` | `video-aula.php` | Selector grado/sección(/materia) + agregar video (link embebido) + listado + eliminar |

**Consolidación de UX** (mismo criterio que Fase 2): los ~10 archivos
legacy de listar/ver/buscar se combinaron en 2 páginas por dominio
(material, video), cada una con selector + formulario + listado en la
misma vista, alternando por querystring — no hay una página de "detalle"
separada (`verTarea.php`/`verTareaPri.php`): la descripción completa ya se
muestra inline en la tabla de "Material Publicado". Si en el futuro se
necesita una vista de detalle más rica (ej. lista de quién descargó/vio el
material), es una extensión aislada, no un rediseño.

## Decisiones de diseño

- **Slugs**: `doc-material`, `doc-video-aula`, grupo de menú "Aula Virtual"
  — seed en `db/fase13-portal-docentes-aula-virtual.sql`, ya aplicado
  contra `jesistem_siscev` local y habilitado para colegio 11.
- **Gating por `maeDa`/`docDa`**: igual que Calificaciones — el sidebar
  solo muestra "Aula Virtual" si el docente tiene asignación de grado en
  `trgsp` (Primaria) o `trgsmp` (Bachillerato), además de
  `modulo_habilitado()`.
- **Verificación de propiedad antes de escribir**: tanto al subir material
  como al agregar video, se reverifica contra `trgsp`/`trgsmp` que el
  docente en sesión tiene ese grado/sección(/materia) asignado — no se
  confía en los valores del formulario. Al eliminar, el `WHERE` incluye
  `cedProf = $_SESSION['usuario']`, así que un docente no puede borrar
  material de otro aunque adivine el `idTarea`/`idVideo`.
- **Archivos de material**: se guardan en `<raíz-del-repo>/tareas/` (mismo
  directorio que ya lee `admin_alumnos/material.php` del lado alumno) y se
  sirven vía `https://DOMINIO/tareas/<archivo>` — mismo patrón/gap ya
  documentado en `CLAUDE.md` para `fotoalu/`/`fotodoc/` (dominio legado del
  colegio, no migrado al esquema multi-tenant). El nombre de archivo se
  sanea (transliteración de tildes/ñ, solo `[a-z0-9._-]`) y se le antepone
  `time() . mt_rand()` para evitar colisiones/sobrescritura.
- **Videos**: no se suben archivos, solo un link (pensado para
  `youtube.com/embed/...`); el formulario incluye una previsualización
  (`<iframe>`) que se actualiza en el evento `onblur` del campo de link.
- **Borrado físico**: al eliminar un material, se borra también el archivo
  de `tareas/` (`unlink`), no solo la fila de BD — evita basura acumulada
  en disco.

## Verificación

Cuenta de docente sintética (`90000010`, clonada de un docente real cargo=3
para heredar columnas `NOT NULL`, autorizada por el usuario, creada y
borrada al terminar) con `trgsp2526` asignado a grado 51/sección 1
(Primaria) y `trgsmp2526` a grado 61/sección 1/materia 6111 "Fundamento
Humano Cristiano" (Bachillerato) — mismos valores de prueba ya usados y
validados en Fase 1. Sin alumnos sintéticos esta vez: ninguno de los dos
módulos de esta fase escribe en tablas de alumno/notas ni dispara los
triggers de notificación Telegram, así que no aplica el riesgo de Fase 1/2.

Flujo probado de punta a punta vía HTTP (login real + cookies de sesión,
servidor `php -S` local apuntando a la raíz del repo — no había vhost
configurado para este proyecto en esta máquina):

- `material.php?grado=51` (Primaria) y `?grado=61` (Bachillerato) → 200,
  sin errores/warnings/deprecated.
- Subida de material en Primaria (multipart, con archivo) → 302 a
  `?subido=1`; verificado por `SELECT` directo que `tareaspri2526` quedó
  correcta y el archivo llegó a `tareas/` con nombre saneado.
- Listado → muestra el material recién subido con su descripción y botón
  de ver (`https://DOMINIO/tareas/...`).
- Eliminar → borra la fila de `tareaspri2526` y el archivo físico de
  `tareas/` (confirmado que ambos desaparecen).
- Mismo ciclo completo (subir → listar → eliminar) repetido en
  Bachillerato contra `tareas2526` — mismo resultado.
- **Aislamiento**: intento de subir material a una materia NO asignada al
  docente en sesión (`materia_cod=9999`, no existe en `trgsmp2526` para esa
  cédula) → no se verificó nada, ninguna fila insertada (el `$tieneAcceso`
  del código bloqueó el `INSERT` silenciosamente, igual que hace el resto
  del portal ante un intento de acceso fuera de lo asignado).
- `video-aula.php?grado=51`/`?grado=61` → 200, sin errores.
- Agregar video en Primaria y en Bachillerato → 302, verificado por
  `SELECT` directo en `videopri2526`/`video2526`.
- Listado → muestra el video con su link.
- Eliminar → borra la fila en ambos casos (no hay archivo físico que
  limpiar, solo el link).
- Los 2 archivos de esta fase (`material.php`, `video-aula.php`) y
  `layout/base.php` pasan `php -l` sin errores.

**No verificado en este ambiente**: la previsualización JS del link de
video (`onblur` → `<iframe>`) no se ejercitó con un navegador real, solo se
revisó por código. Tampoco se probó con un docente que tenga *dos*
secciones asignadas del mismo grado (para confirmar que el selector de
sección lista ambas correctamente) — se revisó por código
(`GROUP BY`/`DISTINCT` en las queries de selectores) pero la cuenta de
prueba solo tenía una sección por grado.

## Hallazgo de higiene de datos (no es un bug de código)

Durante la revisión previa a esta verificación se encontró un registro de
prueba (`video2526.idVideo = 1`, título "Prueba", fecha 2026-07-07) que
había quedado en la BD real de `jesistem_juanxxiii` — insertado con la
cédula de una **docente real** (Alexandra Lincon Baloa) en vez de una
cuenta sintética, aparentemente residuo de una prueba manual anterior a
esta sesión. El usuario autorizó borrarlo; se eliminó antes de empezar la
verificación de esta fase. Sirve como recordatorio: si se vuelve a probar
manualmente este módulo (por ejemplo desde el navegador), usar siempre una
cuenta sintética, nunca la cuenta real de un docente.

## Activar el módulo para un colegio

1. Aplicar `db/fase13-portal-docentes-aula-virtual.sql` contra `siscev` (ya
   aplicado en local; falta en producción) — no crea tablas nuevas en la BD
   del colegio, solo el seed de módulos.
2. Confirmar que `tareas{periodo}`/`tareaspri{periodo}`/`video{periodo}`/
   `videopri{periodo}` existen en la BD del colegio (ya las usa el lado
   alumno de `admin_alumnos/material.php`/`video-aula.php` — si ese módulo
   ya funciona para el colegio, estas tablas ya existen).
3. Confirmar que `<raíz-del-repo>/tareas/` es escribible por el proceso PHP
   (se crea automáticamente con `mkdir` si no existe, pero el proceso
   necesita permiso de escritura en el directorio padre).
4. En `panel_admin` → colegio → módulos → habilitar **Material de Clases**
   y **Video Aula**.

## Pendiente / fuera de este alcance

- Resto de fases (Comunicación, Reportes) — ver
  `migracion_de_modulo_docentes.md`.
- Vista de detalle enriquecida por tarea/video (quién la vio/descargó) si
  se decide que la tabla inline no basta — ver "Consolidación de UX"
  arriba.
- Previsualización JS del link de video sin ejercitar en navegador real
  (ver "No verificado" arriba).
- Selector con más de una sección asignada por grado (ver "No verificado"
  arriba).