# 14 — Plan de desarrollo por fases *(Entregable N)* > Criterio de fasificación: **cada fase termina en algo demostrable y utilizable**, no en "el 30 % del backend". > El colegio puede ver progreso real y corregir el rumbo temprano, que es cuando corregir es barato. --- ## Resumen de fases | Fase | Entregable | Dependencias | Decisiones que la bloquean | |---|---|---|---| | **0** | Cimientos técnicos | — | RG-01 | | **1** | Autenticación, roles y usuarios | 0 | DP-08 | | **2** | Institución, años, periodos, configuración | 1 | DP-09, AMB-12 | | **3** | Estructura académica | 2 | — | | **4** | Personas y matrícula | 3 | — | | **5** | Desempeños, notas y recuperaciones | 4 | DP-03, DP-04, DP-07, AMB-02, AMB-03 | | **6** | Cálculo, consolidado y dashboards | 5 | DP-01 | | **7** | Boletines PDF | 6 | DP-02, DP-05, AMB-06 | | **8** | Promoción y cierre de año | 6 | DP-06 | | **9** | Tareas y comunicados | 4 | — | | **10** | Reportes, exportaciones y afinamiento | 6 | — | **Rutas paralelizables:** la Fase 9 solo depende de la 4, por lo que puede desarrollarse en paralelo con las fases 5 a 8 si hay más de un desarrollador. Las fases 7 y 8 ambas dependen de la 6 y son independientes entre sí. ``` F0 ─► F1 ─► F2 ─► F3 ─► F4 ─┬─► F5 ─► F6 ─┬─► F7 ─┐ │ │ ├─► F10 └─► F9 ───────┴─► F8 ─┘ ``` --- ## Fase 0 · Cimientos técnicos **Objetivo:** que exista un esqueleto ejecutable con las decisiones estructurales tomadas y verificadas. **Alcance:** - Estructura de carpetas del documento 13 - Núcleo: enrutador, contenedor de dependencias, petición/respuesta, motor de plantillas con escape por defecto - Conexión PDO con configuración por entorno y validación al arrancar - Sistema de migraciones y datos iniciales - Manejo centralizado de errores + páginas 403/404/500 - Registro de eventos con rotación - Plantilla base de interfaz con Bootstrap y los tokens de diseño - Entorno de pruebas y verificación de estilo de código **Criterios de aceptación:** - [ ] La aplicación arranca y sirve una página de prueba - [ ] Sin `.env` válido, la aplicación falla con un mensaje comprensible - [ ] Una migración se aplica y se revierte correctamente - [ ] Un error no controlado produce una página limpia + registro con identificador - [ ] `ÑÁÉÍÓÚÜ` se muestran correctamente de extremo a extremo ([RG-06](00-hallazgos-y-decisiones.md#rg-06--mayúsculas-y-caracteres-del-español)) **Demostrable:** "el sistema arranca, tiene su identidad visual y su manejo de errores". --- ## Fase 1 · Autenticación, roles y usuarios **Objetivo:** que se pueda entrar al sistema con distintos roles y que los permisos funcionen de verdad. **Alcance:** - Entidades Persona, Usuario, Rol, Permiso, y sus relaciones - Login, logout, gestión de sesión con regeneración y expiración - Hash de contraseñas y verificación - **Bloqueo progresivo por intentos fallidos** (DP-08) - Generación de contraseña inicial según §11 - Los tres niveles de autorización, con el nivel 3 preparado para los ámbitos que llegarán - Protección CSRF en todos los formularios - Menú dinámico según permisos - CRUD de usuarios, asignación de roles, restablecimiento de contraseñas con jerarquía - Bitácora de accesos - Auditoría: infraestructura base + auditoría de usuarios y contraseñas **Criterios de aceptación:** - [ ] Los cinco roles inician sesión y ven menús distintos - [ ] 5 intentos fallidos bloquean la cuenta 15 minutos - [ ] Un Coordinador **no puede** restablecer la contraseña de un Superadmin - [ ] Una petición sin testigo CSRF se rechaza - [ ] La sesión expira por inactividad con aviso previo - [ ] Un restablecimiento de contraseña deja registro de auditoría **sin** el valor de la contraseña - [ ] Una persona con dos roles cambia de perfil sin volver a iniciar sesión **Demostrable:** "cinco personas distintas entran al sistema y cada una ve lo suyo". --- ## Fase 2 · Institución, años, periodos y configuración **Objetivo:** que el colegio quede configurado y exista el concepto de contexto activo. **Alcance:** - Módulo Colegio completo, con carga de logo y escudo - Entidad Sede - Años académicos con su máquina de estados - Periodos con apertura y cierre - Año y periodo predeterminados - **Selector de contexto activo** en la barra superior, con aviso visual cuando no es el predeterminado - Configuración académica: escala de desempeño con validación de bandas, notas mínima y máxima, decimales, política de recuperación, interruptores de visibilidad - **Asistente de configuración inicial** ([F-01](04-flujos-principales.md#f-01--configuración-inicial-del-sistema-una-sola-vez)) - Auditoría de configuración, años y periodos **Criterios de aceptación:** - [ ] El asistente inicial lleva de sistema vacío a sistema configurado - [ ] Una escala con huecos entre bandas se rechaza con un mensaje claro - [ ] El Coordinador ve el módulo Colegio pero no puede editarlo - [ ] Cambiar el contexto a un año cerrado pone el sistema en solo lectura y lo indica visiblemente - [ ] Cerrar y reabrir un periodo queda auditado, y la reapertura exige motivo **Demostrable:** "el colegio está configurado y el sistema sabe en qué año y periodo estamos". --- ## Fase 3 · Estructura académica **Objetivo:** que exista la estructura sobre la que colgar estudiantes y notas. **Alcance:** - Grados con orden y nivel (DP-09) - Cursos con director, jornada, grado y año - Áreas y asignaturas - Oferta de asignaturas por curso - Docentes (persona + rol + usuario) - **Asignación de docentes titulares**, con visualización de carga - **Copia de estructura del año anterior** ([F-03](04-flujos-principales.md#f-03--copiar-la-estructura-académica-del-año-anterior)) - Nivel 3 de autorización operativo para el ámbito de docente - Auditoría de toda la estructura **Criterios de aceptación:** - [ ] Se crea la estructura completa de un año - [ ] La copia de estructura reproduce el año anterior con vista previa editable - [ ] La copia es repetible sin duplicar - [ ] Un docente inactivo genera aviso al copiar y no queda asignado - [ ] Un docente ve **solo** sus asignaciones - [ ] Los cursos se ordenan por grado, no alfabéticamente **Demostrable:** "el año 2027 se crea copiando 2026 en diez minutos". --- ## Fase 4 · Personas y matrícula **Objetivo:** que el colegio pueda matricular. Es la fase de mayor valor operativo inmediato. **Alcance:** - Estudiantes con todos los campos del documento 05, con obligatoriedad diferenciada - Acudientes y relación muchos a muchos con parentesco - **Búsqueda por documento antes de crear**, tanto para estudiante como para acudiente - **Wizard de matrícula de 5 pasos** con guardado de borrador - Código de matrícula con secuencia segura - Estados de matrícula y sus transiciones - **Traslados** con análisis de impacto - Autorización de tratamiento de datos - Restricción de acceso a campos sensibles - **Importador masivo desde CSV/Excel** con validación previa y reporte de errores [RT] - Auditoría completa del módulo **Criterios de aceptación:** - [ ] Digitar un documento existente ofrece editar o matricular, no crear un duplicado - [ ] Matricular al segundo hermano reutiliza los acudientes existentes - [ ] El wizard conserva el borrador al cerrar el navegador - [ ] Dos matrículas simultáneas obtienen códigos distintos - [ ] Un traslado conserva las notas y muestra el análisis de impacto - [ ] Ninguna matrícula se puede eliminar - [ ] Un docente no ve el RH ni las observaciones médicas - [ ] El importador procesa 300 estudiantes reportando los errores fila por fila **Demostrable:** "la secretaría matricula a todo el colegio". --- ## Fase 5 · Desempeños, notas y recuperaciones **Objetivo:** que los docentes puedan calificar. Es la fase que define la aceptación del sistema. **Alcance:** - Banco de desempeños por asignatura, curso y periodo, con reutilización - **Pantalla de digitación rápida** con todas las reglas de §29 - Navegación completa por teclado y autoguardado - Validación en cliente y servidor - Nivel de desempeño en vivo - Recuperaciones con las tres políticas configurables - Observaciones de boletín en dos niveles - Bloqueo por periodo cerrado, revalidado en el servidor - Auditoría de notas, recuperaciones, desempeños y observaciones **Criterios de aceptación:** - [ ] `35` produce `3.5`; `4` produce `4.0`; `55` se rechaza - [ ] Un curso de 32 estudiantes se califica **sin tocar el ratón** - [ ] El autoguardado funciona y el guardado total también - [ ] Cerrar el periodo mientras un docente digita produce un error claro **sin perder lo digitado** - [ ] Un docente no puede calificar una asignatura ajena, ni manipulando la URL - [ ] Una recuperación conserva la nota original y calcula la definitiva según la política - [ ] Toda modificación de nota deja auditoría con valor anterior y nuevo **Demostrable:** "un docente califica su curso en cinco minutos". **Nota:** esta fase merece una **prueba con docentes reales** antes de darla por cerrada. La velocidad de digitación percibida es el factor que más influye en la adopción del sistema. --- ## Fase 6 · Cálculo, consolidado y dashboards **Objetivo:** que el sistema calcule correctamente y que cada rol vea su tablero. **Alcance:** - Servicio de cálculo académico completo (RN-CALC-01 a RN-CALC-13) - Consolidado materializado con recálculo por evento y bajo demanda - Cálculo de puestos con precisión de 4 decimales y ranking competitivo - Los cinco dashboards del documento 09 - Indicadores para familias según los interruptores de configuración (DP-01) - Gráfica de evolución en pantalla - Panel de cierre de periodo con detalle de pendientes **Criterios de aceptación:** - [ ] El ejemplo trabajado del documento 06 produce **exactamente** los valores documentados - [ ] Una asignatura sin calificar no afecta ningún promedio - [ ] 4.126, 4.125 y 4.124 producen tres puestos distintos - [ ] Dos promedios idénticos producen el mismo puesto y el siguiente salta - [ ] Cambiar una nota actualiza el consolidado del curso - [ ] El acudiente **no ve** ninguna nota individual - [ ] El dashboard del docente lleva a la digitación en un clic - [ ] Cobertura de pruebas del servicio de cálculo por encima del 95 % **Demostrable:** "cada usuario entra y ve exactamente lo que necesita, con cifras correctas". --- ## Fase 7 · Boletines PDF **Objetivo:** el entregable más visible del sistema. **Alcance:** - Integración del motor de PDF con la abstracción propia - Plantilla del boletín con los 17 elementos de §42 - Generación de la gráfica de evolución en SVG - Boletín individual - **Generación masiva por lotes con progreso** y unificación en un PDF - Bloques activables por configuración - Boletín acumulado de fin de año **Criterios de aceptación:** - [ ] Todos los criterios del documento 10 - [ ] `ÑÁÉÍÓÚÜ` correctos en todo el PDF - [ ] Los promedios del boletín coinciden **exactamente** con los de pantalla y reportes - [ ] 35 boletines se generan sin agotar tiempo ni memoria - [ ] Un colegio sin logo produce un boletín correcto - [ ] El boletín es legible impreso en blanco y negro **Demostrable:** "el colegio imprime los boletines de un curso completo". --- ## Fase 8 · Promoción y cierre de año **Objetivo:** cerrar el ciclo anual completo. **Alcance:** - Pantalla de promoción con sugerencia de curso destino y de estado - Promoción masiva y decisión individual - Todos los estados de destino: promovido, no promovido, retirado, trasladado, graduado - Creación transaccional de las matrículas del año siguiente - Cierre de año con verificación de precondiciones - Solo lectura total sobre años cerrados - Auditoría de lote y de decisiones individuales **Criterios de aceptación:** - [ ] 5°A sugiere 6°A automáticamente - [ ] 11° sugiere Graduado - [ ] Promover 32 estudiantes crea 32 matrículas nuevas en una transacción - [ ] Los acudientes se conservan en la nueva matrícula - [ ] El proceso es repetible sin duplicar - [ ] Un año cerrado no admite modificación por ningún rol - [ ] Un año cerrado sigue permitiendo boletines y reportes **Demostrable:** "el colegio cierra 2026 y arranca 2027 con los estudiantes ya matriculados". --- ## Fase 9 · Tareas y comunicados **Objetivo:** el canal de comunicación con la comunidad. *(Solo depende de la Fase 4 — paralelizable.)* **Alcance:** - Tareas por asignatura y curso, con estado calculado - Adjuntos con validación de seguridad y descarga controlada - Comunicados con destinatarios múltiples según el alcance del emisor - Vistas de consulta para estudiantes y acudientes - Centro de notificaciones - Auditoría **Criterios de aceptación:** - [ ] La fecha de asignación no es editable - [ ] El estado se calcula correctamente en los tres casos - [ ] Un comunicado llega a varios cursos simultáneamente - [ ] Un docente solo emite comunicados a sus cursos - [ ] Un archivo con extensión ejecutable se rechaza - [ ] Un adjunto no es descargable por URL directa - [ ] Estudiantes y acudientes solo consultan **Demostrable:** "el docente publica una tarea y el acudiente la ve en su celular". --- ## Fase 10 · Reportes, exportaciones y afinamiento **Objetivo:** completar y pulir. **Alcance:** - Los ~25 reportes del documento 11 - Exportación a CSV, XLSX, PDF e impresión - Reporte de integridad de datos - Consulta de auditoría con todos sus filtros y vistas - Optimización de consultas e índices - Revisión completa de accesibilidad y responsive - Lista de verificación de seguridad previa a producción - Documentación: manual de usuario por rol y manual técnico **Criterios de aceptación:** - [ ] Todos los reportes respetan filtros y ámbito de rol - [ ] La exportación coincide con lo mostrado - [ ] El CSV abre correctamente en Excel con caracteres españoles - [ ] Ninguna pantalla produce desplazamiento horizontal a 360 px - [ ] Toda la lista de verificación de seguridad en verde - [ ] Cobertura global del 80 % **Demostrable:** "el sistema está listo para producción". --- ## Hitos de validación con el colegio No basta con entregar fases: hay que validarlas con quien las va a usar. | Después de | Validar con | Qué se busca confirmar | |---|---|---| | Fase 2 | Rector / Coordinación | Que la configuración refleje el colegio real | | Fase 4 | **Secretaría** | Que el wizard de matrícula sea cómodo para digitación masiva | | Fase 5 | **2 o 3 docentes reales** | **Velocidad de digitación.** El hito de validación más importante | | Fase 6 | Coordinación | Que los cálculos coincidan con los que el colegio hace hoy | | Fase 7 | Rector / Coordinación | Diseño del boletín — es lo que sale del colegio | | Fase 10 | Todos los roles | Prueba de aceptación completa | **Validar la Fase 5 con docentes reales, y la Fase 7 con quien firma los boletines, evita las dos reescrituras más caras del proyecto.** --- ## Estrategia de puesta en marcha Recomendación: **no esperar a la Fase 10 para empezar a usar el sistema.** | Momento | Uso real posible | |---|---| | Tras la Fase 4 | El colegio ya puede **matricular** el año siguiente con el sistema | | Tras la Fase 5 | Los docentes ya pueden **calificar** un periodo de prueba | | Tras la Fase 7 | El colegio ya puede **emitir boletines** reales | | Tras la Fase 8 | Ciclo anual completo | Este uso temprano genera retroalimentación con datos reales, que es la única que descubre los problemas que ninguna especificación anticipa. --- ## Riesgos del plan | Riesgo | Mitigación | |---|---| | Las decisiones pendientes no se resuelven a tiempo | Las fases 0 a 4 solo necesitan DP-08 y RG-01. Hay margen | | DP-03 (nota única) cambia después de la Fase 5 | Se rehace la Fase 5. Por eso está marcada como bloqueante | | El diseño del boletín se rechaza en la Fase 7 | Validar la maqueta del boletín **durante la Fase 6**, antes de programarla | | El rendimiento no aparece hasta tener datos reales | Cargar datos de prueba realistas (800 estudiantes) desde la Fase 4 | | Los docentes rechazan la digitación | Validación con docentes reales al cerrar la Fase 5 | | Alcance creciente durante el desarrollo | Toda petición nueva se clasifica: ¿está en la especificación? Si no, entra a una lista de la versión siguiente |