# 01 — Visión general del sistema

## 1.1 Qué es

Plataforma web de **Evaluación Docente y Gestión Docente** desarrollada por Klee Software para
instituciones de educación superior. La instancia principal documentada aquí está configurada
para la **Universidad Compensar** (`Config::$perfil = "universidad"`, redirect de SSO a
`gestiondocente.ucompensar.edu.co`).

El sistema resuelve un ciclo semestral completo:

1. **Sincronizar** desde el sistema académico institucional quién estudia, quién enseña y qué materias.
2. **Recoger evaluaciones** de cuatro fuentes distintas sobre cada docente.
3. **Consolidar** esas fuentes en una nota definitiva ponderada.
4. **Reportar y graficar** los resultados a cada nivel jerárquico (docente, programa, facultad, sede).
5. **Derivar acciones**: planes de mejora, labor docente, órdenes de servicio, ascensos en el escalafón.

## 1.2 Las dos aplicaciones

El mismo código sirve dos front-ends distintos, diferenciados por el `index.php` de entrada:

| App | Entrada | Constantes | Usuarios | Layout |
|---|---|---|---|---|
| **Backoffice / Admin** | `public/admin/index.php` | `DIR_LLAMADO='/admin'`, `DIR_INDEX='login'` | Tabla `usuarios` (personal administrativo) | `metronic` |
| **Portal público** | `public/index.php` | `DIR_LLAMADO=''`, `DIR_INDEX='public'` | Tablas `estudiantes`, `docentes`, `directores` | `metronic_public` |

Ambas cargan el mismo bootstrap (`core/AutoLoad.php`) y el mismo conjunto de controladores.
La diferencia de comportamiento surge de:
- qué menú se carga (`Menu::$principal` vs `Menu::$public[<rol>]`),
- qué tabla se usa para autenticar (ver [06 — Seguridad](06-seguridad-permisos.md)),
- el layout (`$MyLayout`) que declara cada controlador.

Ojo: algunos controladores (p. ej. `ReportesController`, `GraficasController`) **cambian su layout
en tiempo de ejecución** según el rol del usuario, para poder servir la misma vista a ambos mundos:

```php
// app/controllers/ReportesController.php
if (UsuariosModel::getUserTypeCode() == "director" || UsuariosModel::getUserTypeCode() == "coordinador") {
    $this->MyLayout = 'metronicPublic';
}
```

## 1.3 Actores y roles

Los roles viven en la tabla `roles` (`Id`, `Tipo`, `Nombre`, `Codigo`, `Inicio`, `Grupo`, `Orden`).
El **`Codigo`** es lo que el código PHP consulta (`UsuariosModel::getUserTypeCode()`), no el nombre.

`roles.Tipo` dice **contra qué tabla se autentica** el rol (catálogo `GeneralDataArray::$tipos_roles`):

| `roles.Tipo` | Tabla | |
|---|---|---|
| 0 | `usuarios` | Roles de administración (backoffice); los únicos asignables a un `usuario` |
| 1 | `estudiantes` | |
| 2 | `docentes` | |
| 3 | `directores` | `directores.Tipo` **es el `Id` del rol** |

Los roles con `Tipo != 0` son los del portal público y aparecen en el selector del login
ordenados por `Orden`.

Roles del portal público:

| Id | Tipo | Código | Grupo | Nombre visible | Qué hace en el sistema |
|---|---|---|---|---|---|
| 3 | 1 | `estudiante` | | Estudiante | Evalúa a los docentes de las materias que cursa |
| 2 | 2 | `docente` | | Docente | Se **autoevalúa**, evalúa pares, ve sus resultados, planes de mejora, actas de labor, postulaciones a escalafón |
| 4 | 3 | `director` | `director` | Director | Evalúa a los docentes a su cargo (`docentes.Jefe`), ve reportes de su programa, crea ODS y requisiciones |
| 11 | 3 | `decano` | `director` | Decano | Igual que el director, a nivel de facultad |
| 5 | 3 | `lider` | `lider_nacional` | Líder de Funciones Sustantivas | Evalúa docentes en un instrumento transversal, gestiona labores |
| 10 | 3 | `lider_virtual` | `lider_nacional` | Líder de Docencia Virtual | Idem sobre la metodología virtual |
| 9 | 3 | `coordinador` | | Coordinador Académico | Perfil de consulta de reportes/ODS |

**`roles.Grupo` agrupa roles equivalentes.** `director` y `decano` comparten el grupo
`director`; `lider` y `lider_virtual` comparten `lider_nacional`. El grupo es lo que decide:

- el menú público — `Menu::$public` se indexa primero por `Grupo` y, si no hay entrada, por `Codigo`
  (`PublicModel::setAuthenticated()`);
- los chequeos de perfil en controladores y vistas — `UsuariosModel::getUserTypeGroup() == "director"`
  cubre director **y** decano, mientras que `getUserTypeCode() == "director"` es solo el director;
- los filtros por `directores.Tipo` — `RolesModel::getIdsListByGroup('director')` devuelve `"(4,11)"`
  para usarlo en un `criteria` con `operator => 'IN'`.

Un mismo usuario (mismo `Usuario`/login) **puede tener varios roles a la vez**: al autenticarse,
`PublicModel::setRolesDisponibles()` busca su login en `estudiantes`, `docentes` y `directores`, y
guarda todos los roles encontrados en `$_SESSION[...]['roles_disponibles']` (en `directores`, un rol
por fila, tomado de `directores.Tipo`); luego puede alternar con
`public/?c=public&a=validateChange&rol=<IdRol>`.

En el backoffice los usuarios están en `usuarios` y su rol es `usuarios.Tipo → roles.Id`;
los permisos finos se resuelven contra la tabla `permisos` (ver [06](06-seguridad-permisos.md)).

## 1.4 Vocabulario de dominio

| Término | Significado en este sistema |
|---|---|
| **Periodo** | Semestre académico (`periodos`, p. ej. `20242`). Es el eje temporal de casi todo; se guarda como *filtro de sesión* y se lee con `PeriodosModel::getSesionId()` |
| **Metodología** | `P` = Presencial, `V` = Virtual. Discrimina preguntas, evaluaciones y promedios |
| **Instrumento** | Cuestionario transversal aplicado por un Líder de Proceso (`GeneralDataArray::$instrumentos`: Investigación y Transferencia, Internacionalización, Currículo, Autoría de contenidos virtuales, Tutorías, Experiencia Empresarial, Dirección Virtual) |
| **Consolidado** | Nota definitiva del docente en el periodo, mezcla ponderada de estudiantes + autoevaluación + autoridad superior (`consolidado_evaluaciones`) |
| **Plan de mejora** | Acción correctiva registrada para un docente tras la evaluación (`planes`) |
| **Labor docente** | Actividad no lectiva asignada al docente con horas, objetivo, evidencia y progreso (`labor_docente`) |
| **ODS** | *Orden de Servicio*: documento que formaliza la carga y contratación de docentes de un programa en un periodo (`ods` + `ods_docentes`) |
| **OPS** | *Orden de Prestación de Servicios*: contratación puntual de conferencistas/talleristas (`ops`) |
| **Requisición** | Solicitud de vinculación de un docente nuevo, con flujo de aprobación (`requisiciones`) |
| **Escalafón** | Carrera docente por categorías con puntaje y salario requerido (`escalafon`) |
| **Convocatoria** | Proceso periódico de ascenso en el escalafón (`convocatorias`, `docentes_convocatorias`, `postulaciones`) |
| **Producción intelectual** | Catálogo de productos académicos con puntaje, insumo de las postulaciones (`produccion_intelectual`) |
| **DN** | "Director Nacional" / Líder de Proceso. Aparece en nombres de campos y acciones heredados (`DirectoresNacionales`, `requisiciones_nn`) |

## 1.5 Mapa mental del ciclo semestral

```
      [API Academusoft]                             (07-integraciones)
              │  sincronización
              ▼
   estudiantes · docentes · asignaturas · docentes_asignaturas
              │
              │  el usuario entra al portal público y "genera" su evaluación
              ▼
  ┌───────────────────────────────────────────────────────────┐
  │ estudiantes_evaluaciones   (estudiante → docente/materia)  │
  │ docentes_evaluaciones      (autoevaluación y pares)        │
  │ directores_evaluaciones    (director e instrumentos DN)    │
  │   cada una con su tabla *_respuestas (1 fila por pregunta) │
  └───────────────────────────────────────────────────────────┘
              │  Consolidados → "Consolidar Evaluaciones"
              ▼
      consolidado_evaluaciones  (nota definitiva ponderada)
              │
    ┌─────────┼────────────┬───────────────┬────────────────┐
    ▼         ▼            ▼               ▼                ▼
 reportes  graficas   planes de mejora  labor docente   convocatorias
                                          ODS / OPS     escalafón
```