# 2. Arquitectura propuesta

## Enfoque

Se conserva el MVC actual y se introduce una capa de aplicación gradual. La lógica de negocio deja de residir en vistas y repositorios generales.

```mermaid
flowchart LR
    UI["Vistas Bootstrap / AdminLTE"] --> C["Controladores SIRGILA"]
    C --> V["Validadores de solicitud e importación"]
    C --> A["Servicios de aplicación"]
    A --> D["Servicios de dominio"]
    A --> R["Repositorios SIRGILA"]
    R --> DB[("MySQL / MariaDB")]
    A --> X["Exportadores PDF / XLSX"]
    A --> AU["Auditoría"]
    D --> GP["Motor de proyección de metas"]
    D --> PA["Generador de plan de mejora"]
```

## Capas y responsabilidades

### Presentación

- Recibe filtros y muestra resultados ya calculados.
- No calcula metas ni modifica porcentajes.
- Escapa toda salida y utiliza componentes compartidos.
- Chart.js consume DTOs serializados por el controlador.

### Controladores

- Autenticación, autorización, CSRF y validación de forma.
- Orquestación del caso de uso.
- Redirecciones y mensajes flash.
- No contienen SQL ni fórmulas de negocio.

### Servicios de aplicación

- Importar histórico, confirmar lote, proyectar metas, guardar ajustes, aprobar metas y construir reportes.
- Abren y cierran transacciones en operaciones compuestas.
- Invocan auditoría después de confirmar la transacción funcional.

### Dominio

- `ResultDistributionValidator`: AD/A/B/C, rango, suma y normalización.
- `GoalProjectionService`: histórico ponderado, tendencia, brecha, escenarios y confianza.
- Futuro `ImprovementPlanService`: priorización y acciones sugeridas.
- Ninguna dependencia de HTTP, sesión, PDO o vistas.

### Persistencia

- Repositorios pequeños por agregado:
  - `SirgilaHistoricalRepository`
  - `SirgilaGoalRepository`
  - `SirgilaCatalogRepository`
  - `SirgilaImprovementPlanRepository`
- PDO y consultas preparadas.
- El adaptador legado traduce temporalmente las matrices JSON al modelo vertical.

## Integración con el proyecto existente

1. Mantener las rutas públicas existentes para no romper marcadores ni menús.
2. Extraer progresivamente métodos SIRGILA de `ComanoRepository`.
3. Inyectar servicios en `EvaluationController` mediante constructores con valores por defecto durante la transición.
4. Activar el modelo nuevo por institución mediante configuración o feature flag.
5. Migrar datos JSON a lotes normalizados y comparar conteos antes de cambiar la lectura principal.

## Multiinstitución

- Toda entidad analítica raíz incluye `id_institucion`.
- El tenant activo determina la conexión; `id_institucion` mantiene trazabilidad interna y permite consolidación futura.
- Ninguna consulta acepta `id_institucion` directamente desde el navegador sin validarlo contra la sesión.

## Seguridad

- RBAC por permiso funcional, no solo por nombre de rol.
- Importaciones: extensión, MIME, tamaño, ZIP seguro, número máximo de filas/columnas y carpeta fuera de `public`.
- Evitar fórmulas peligrosas en XLSX exportado ante valores que comiencen con `=`, `+`, `-` o `@`.
- Consultas preparadas con emulación desactivada cuando sea compatible con el despliegue.
- Auditoría de importación, cálculo, edición, aprobación, rechazo y exportación.

## Observabilidad

- Identificador de correlación por importación y cálculo.
- Métricas: filas válidas/rechazadas, duración, competencias calculadas, metas ajustadas, errores de exportación.
- Registro de parámetros efectivos del algoritmo en cada versión de meta.