# 1. Análisis técnico y requisitos

## Objetivo

Evolucionar el módulo SIRGILA de la IE hacia una plataforma web capaz de consolidar los tres últimos años, calcular tendencias y brechas, proponer metas editables, aprobar versiones, generar planes de mejora y ofrecer reportes PDF/XLSX sin perder trazabilidad.

## Estado actual verificado

- Aplicación PHP con front controller en `public/index.php` y MVC propio.
- Persistencia multiinstitución por base tenant mediante `Database` y `TenantService`.
- Rutas SIRGILA ya disponibles para índice, nivel, histórico, plantilla, importación y metas.
- Matriz histórica persistida en `ie_sirgila_historico_matriz` como encabezados y filas JSON.
- Metas persistidas en `ie_sirgila_meta_aprendizaje` por año, nivel, grado y competencia.
- Importación XLSX implementada sin dependencia del Microsoft Excel instalado.
- Seguridad base: sesión, CSRF, normalización de rutas, headers, consultas preparadas y auditoría general.
- Las áreas se filtran actualmente para excluir Castellano y diferenciar el orden de Primaria/Secundaria.

## Brechas técnicas

| Tema | Situación actual | Estado objetivo |
|---|---|---|
| Histórico | Matriz ancha JSON | Resultados verticales 3FN por contexto, competencia y nivel de logro |
| Metas | Un único registro mutable | Versiones, escenarios, estado y auditoría antes/después |
| Algoritmo | Cálculo embebido en la vista | Servicio PHP determinista, configurable y probado |
| Repositorios | `ComanoRepository` concentra decenas de módulos | Repositorios SIRGILA especializados |
| Esquema | Tablas creadas en tiempo de ejecución | Migraciones SQL versionadas |
| Validación | Validación parcial al guardar | Previsualización, errores por fila, suma 100 y consistencia curricular |
| Auditoría | Auditoría genérica | Auditoría funcional de importaciones, metas y aprobaciones |
| Reportes | Exportadores aislados | Servicios PDF/XLSX desacoplados y reutilizables |
| Dependencias | `vendor` sin manifiesto Composer en raíz | Composer como fuente declarativa de dependencias |

## Requisitos funcionales priorizados

1. Ventana histórica dinámica: para el año objetivo `Y`, usar `Y-3`, `Y-2` y `Y-1`.
2. Importar XLSX mediante plantilla oficial, validar y previsualizar antes de confirmar.
3. Mantener inmutables los lotes históricos confirmados; las correcciones crean una nueva revisión.
4. Calcular por competencia y agregados por área, grado, nivel e institución.
5. Conservar AD/A/B/C con suma 100 %, donde `LOGRO = AD + A` y `RIESGO = B + C`.
6. Producir escenarios conservador, recomendado y desafiante.
7. Permitir edición manual de las metas sugeridas, con justificación y auditoría.
8. Gestionar estados `PROPUESTA`, `AJUSTADA`, `APROBADA` y `RECHAZADA`.
9. Mostrar KPIs, histórico, tendencia, brecha, prioridad, variabilidad y confianza.
10. Generar plan de mejora con acciones, responsable, fechas, indicador y estado.
11. Exportar PDF y XLSX con los mismos filtros de la consulta.
12. Aplicar RBAC: administración, dirección, especialista y consulta.

## Reglas de negocio

- Pesos históricos por defecto: 20 %, 30 % y 50 % desde el año más antiguo al más reciente.
- Tendencia: `0.40 × T1 + 0.60 × T2`.
- Brecha: `100 - (AD + A del último año)`.
- Incremento recomendado: `brecha × 0.15 + tendencia positiva × 0.50`.
- Incremento limitado por defecto entre 2 y 8 puntos porcentuales.
- Distribución del incremento: 35 % a AD y 65 % a A.
- B y C disminuyen proporcionalmente según su participación en el riesgo vigente.
- La suma final debe ser exactamente 100 % con tolerancia de cálculo de 0.1 pp.
- Cuando faltan años, el servicio puede calcular una proyección provisional, pero reduce la confianza y debe mostrar la advertencia.

## Requisitos no funcionales

- PHP 8.1 o superior; MySQL/MariaDB con InnoDB y `utf8mb4`.
- Interfaces responsivas con Bootstrap/AdminLTE y gráficos Chart.js.
- Sin dependencia de Microsoft Office ni componentes instalados en el servidor.
- Consultas preparadas, CSRF, escape de salida, control de archivos y límites de carga.
- Índices para filtros por institución, año, nivel, grado, área y competencia.
- Exportaciones y agregaciones grandes ejecutadas por lotes o servicios de aplicación.
- Logs sin datos sensibles y auditoría que no bloquee la transacción principal.

## Criterios de aceptación de la primera versión funcional

- Un histórico válido de tres años genera exactamente tres escenarios por competencia.
- Cada escenario suma 100 % y cumple monotonicidad AD/A al alza y B/C a la baja cuando es matemáticamente posible.
- Una meta editada conserva propuesta original, valor final, usuario, fecha y justificación.
- Los filtros nunca mezclan Personal Social con DPCC/Ciencias Sociales en un nivel incorrecto.
- Castellano como Segunda Lengua no aparece en consultas, importaciones, metas ni reportes.
- La misma consulta produce cifras coherentes en pantalla, PDF y XLSX.