# Migración: Portal Docentes — Fase 0 (Fundación)

Primera fase de la migración de `uepca/docentes/` hacia `admin_docentes/`
(ver `migracion_de_modulo_docentes.md` para el plan completo). Cubre login,
layout, home y las tres páginas de menor riesgo (perfil, carnet, horario).
Probado end-to-end contra colegio 11 (`jesistem_juanxxiii`).

## Alcance

Login compartido (decisión ya tomada: no hay `admin_docentes/login.php`) +
fundación del portal + 3 módulos.

| Origen (`uepca/`)                | Destino (`admin_docentes/` salvo nota) | Rol |
|---|---|---|
| `login.php` (rama `cargo>1`)      | `admin_alumnos/login.php` (fix)        | Calcula `maeDa`/`docDa` y redirige a `admin_docentes/home.php` |
| `docentes/sesion.php`             | — (eliminado, absorbido por login)     | Duplicaba el cálculo de `maeDa`/`docDa` |
| `docentes/encabezado1.php` + `docentes/footer1.html` | `layout/base.php` | Header/menú → sidebar SB Admin 2 |
| `docentes/index.php`              | `home.php`                             | Dashboard |
| `docentes/fichaprof.php`          | `perfil.php`                           | Ver datos personales |
| `docentes/guardarprof.php`        | `perfil-actualizar.php`                | Guardar datos + foto |
| `docentes/carnet.php`             | `carnet.php` + `procesos/carnet.php`   | Carnet de empleado en PDF |
| `docentes/horario-pdf.php`        | `horario.php` + `procesos/horario.php` | Horario de clases en PDF |

No incluidos en esta pasada: `docentes/tutorial.php`, `tutoPower.php`,
`tutoYou.php` (contenido estático, se deja para cuando se defina dónde vive
el material de tutoriales del nuevo portal — no bloquea nada).

## Decisiones de diseño

- **Login compartido, no duplicado**: se mantiene un solo formulario en
  `admin_alumnos/login.php`. Se restructuró el bloque `if ($count > 0)` para
  que el cálculo de período activo (`tablaPeriodo`/`periodoActivo`) ocurra
  primero (lo necesitan los 3 roles), y que `admin`/docente (`cargo>1`)
  salgan **antes** de todo el bloque de lógica exclusiva de alumno
  (morosidad, tareas pendientes, encuestas) — ver "Bug encontrado" abajo.
- **Slugs**: `doc-perfil`, `doc-carnet`, `doc-horario` (sin `grupo_menu` para
  perfil, `'Documentos'` para carnet/horario) — seed en
  `db/fase10-portal-docentes.sql`, ya aplicado contra `jesistem_siscev` local
  y habilitado para colegio 11.
- **`MODULOS_CON_MOROSO`**: ningún slug docente entra ahí (decisión ya
  tomada — el personal no es moroso).
- **`MODULOS_CON_PDF`**: se agregó `doc-carnet` (usa
  `cargar_formato_pdf()`, mismo mecanismo que `carnet` de alumno). `doc-horario`
  **no** se agregó: a diferencia del carnet (imágenes de fondo específicas
  del colegio), el horario docente es una grilla genérica armada 100% desde
  datos (`horario_grado`/`horario_docentes`/`horario_dias`), sin plantilla
  por colegio — vive directo en `admin_docentes/procesos/horario.php`.
- **Plantilla de carnet**: `admin_alumnos/colegios/colegiojuanxxiii/formatos/carnet-docente.php`
  (mismo patrón que `formatos/carnet.php` de alumno). Imágenes copiadas desde
  `uepca/docentes/imagenes/` a `colegiojuanxxiii/img/`: `carnet-docente.jpg`,
  `dorso-docente.jpg`, `firma.png`, `selloCole.png` (los dos primeros
  renombrados para no chocar con `carnet.jpg`/`dorso.jpg` del alumno, que ya
  existían ahí).
- **Foto del docente**: se guarda en `fotodoc/` (relativo a la raíz del
  repo, junto a `fotoalu/`/`fotorep/`) y se sirve vía
  `https://DOMINIO/fotodoc/...` — mismo patrón y mismo gap ya documentado en
  `CLAUDE.md` ("Known gap": fotos no migradas al esquema multi-tenant, sigue
  dependiendo del dominio legado de cada colegio en producción).
- **`logo_colegio_actual()`** (`core/perfil_colegio.php`) se generalizó con
  un segundo parámetro `$rutaPrefix` (default `''`, no rompe a
  `admin_alumnos`) para poder invocarse desde `admin_docentes/layout/base.php`
  con `'../admin_alumnos/'`.
- **Seguridad**: todas las queries nuevas con prepared statements. Única
  excepción deliberada: `carnet-docente.php` interpola `$cedula` de
  `$_SESSION['usuario']` directo en el SQL — igual que el `formatos/carnet.php`
  de alumno ya existente (mismo patrón, mismo origen de dato ya de por sí
  controlado por sesión, no por input de request).

## Bugs encontrados y corregidos durante la verificación end-to-end

No estaban en el alcance original de "migrar 3 páginas", pero bloqueaban
por completo el login de cualquier docente real a través del login
compartido — se corrigieron porque sin esto la Fase 0 no funciona:

1. **`admin_alumnos/login.php` rompía para todo `cargo>1`**: el bloque de
   morosidad/tareas/encuestas (pensado solo para alumnos) corría *antes* de
   la rama docente, usando `$periodoAlum` (derivado del campo `Periodo` del
   alumno) y `$grado` — ambos son `NULL` en `alumcer` para el personal
   docente. Eso generaba `notaprimaria` (nombre de tabla vacío, sin sufijo de
   período) → `Fatal error: Table 'notaprimaria' doesn't exist`. Se
   restructuró el bloque para que el período activo se calcule primero y
   `admin`/docente salgan (`exit`) antes de tocar esa lógica exclusiva de
   alumno. También se guardó `substr($periodo ?? '', ...)` (línea ~49) que
   generaba un *deprecated notice* con `$periodo` nulo.
2. **`utf8_decode()` deprecado rompía la generación de PDF**: en PHP 8.2+
   genera un *deprecated notice* que se imprime antes de que FPDF pueda
   enviar el header `Content-Type: application/pdf`, y `FPDF::Output()`
   lanza `Exception: Some data has already been output, can't send PDF
   file`. Se reemplazó por un helper local `_latin1()` con
   `mb_convert_encoding(..., 'ISO-8859-1', 'UTF-8')` en `carnet-docente.php`
   y `procesos/horario.php`. **Nota**: el `formatos/carnet.php` de alumno
   (ya en producción) tiene el mismo patrón `utf8_decode()` sin corregir —
   no se tocó por estar fuera del alcance de esta migración, pero es el
   mismo bug latente si corre en PHP 8.2+.

## Verificación

Cuenta de prueba sintética (autorizada explícitamente por el usuario,
creada y borrada al terminar — nunca se usó ni expuso una contraseña real)
contra `jesistem_juanxxiii`, clonada desde un docente real (`cargo=3`,
maestro de primaria) para heredar todas las columnas `NOT NULL`, con
`trgsp2526` asignado a un grado para forzar `maeDa='S'`:

- Login (`?c=<token>` + POST credenciales) → redirige correctamente a
  `admin_docentes/home.php`, sin errores/warnings PHP.
- `home.php` → 200, muestra el nombre del docente.
- `perfil.php` → 200; `perfil-actualizar.php` → guarda y persiste
  correctamente en `alumcer` (verificado por SELECT directo).
- `carnet.php` → 200; `procesos/carnet.php` → `Content-Type: application/pdf`,
  PDF válido.
- `horario.php` → 200; `procesos/horario.php` → `Content-Type:
  application/pdf`, PDF válido (sin secciones asignadas en el período de
  prueba, la grilla sale vacía pero no hay error).
- Sin sesión → `admin_docentes/home.php` responde 403 (aislamiento
  multi-tenant vía `resolver_tenant()`, igual que `admin_alumnos`).
- Los 10 archivos nuevos/modificados pasan `php -l` sin errores.

No verificado en este ambiente (pendiente para cuando se dé de alta un
colegio adicional): comportamiento con más de una asignación de grado/sección
por docente en el horario, ni el flujo de subida de foto (`multipart/form-data`)
de `perfil-actualizar.php` — la lógica se revisó por código pero no se
ejercitó con un archivo real en esta pasada.

## Activar el módulo para un colegio

1. Aplicar `db/fase10-portal-docentes.sql` contra `siscev` (ya aplicado en
   local; falta en producción).
2. En `panel_admin` → colegio → módulos → habilitar **Mi Perfil (Docente)**,
   **Carnet de Empleado**, **Mi Horario**.
3. Si el colegio no es Juan XXIII: crear su propia plantilla
   `colegios/<carpeta>/formatos/carnet-docente.php` (copiar la de
   `colegiojuanxxiii/` y ajustar imágenes) y configurar `ruta_formato_pdf`
   para `doc-carnet` en `colegio_modulo_config`. Sin esa configuración,
   `cargar_formato_pdf()` devuelve 404 controlado (no error crudo).

## Pendiente / fuera de este alcance

- Resto de fases (Calificaciones, Evaluaciones en línea, Aula Virtual,
  Comunicación, Reportes) — ver `migracion_de_modulo_docentes.md`.
- Tutoriales (`tutorial.php`/`tutoPower.php`/`tutoYou.php`).
- Aplicar `db/fase10-portal-docentes.sql` en producción y probar con un
  docente real (no sintético) antes de anunciar el portal a los colegios.
- El mismo bug de `utf8_decode()` sigue latente en
  `admin_alumnos/colegios/colegiojuanxxiii/formatos/carnet.php` (alumno) —
  no corregido aquí por estar fuera de alcance, queda anotado para quien
  lo toque.