# Manual del Sistema — Klee Planner (Polímero)

> Documentación funcional y técnica de **todos los módulos** del sistema de gestión académica y de talento humano.
> Preparado como base para la **entrega de módulos**.
> Fecha: 2026-07-23

---

## Índice

1. [¿Qué es el sistema?](#1-qué-es-el-sistema)
2. [Arquitectura y funcionamiento general](#2-arquitectura-y-funcionamiento-general)
3. [Seguridad y control de acceso](#3-seguridad-y-control-de-acceso)
4. [Catálogos y CRUDs de configuración](#4-catálogos-y-cruds-de-configuración)
5. [Planta activa / Colaboradores](#5-planta-activa--colaboradores)
6. [Perfiles de cargo](#6-perfiles-de-cargo)
7. [Contratación académica (docentes)](#7-contratación-académica-docentes)
8. [Contratación administrativa y procesos de selección](#8-contratación-administrativa-y-procesos-de-selección)
9. [Solicitudes: novedades, aval de honorarios y adicionales](#9-solicitudes-novedades-aval-de-honorarios-y-adicionales)
10. [Periodos de prueba](#10-periodos-de-prueba)
11. [Labor docente](#11-labor-docente)
12. [Asignación / Programación académica](#12-asignación--programación-académica)
13. [Docentes y estructura académica](#13-docentes-y-estructura-académica)
14. [Inducción y reinducción](#14-inducción-y-reinducción)
15. [Dotaciones y bonos](#15-dotaciones-y-bonos)
16. [Cartas, plantillas y minutas](#16-cartas-plantillas-y-minutas)
17. [Cumpleaños](#17-cumpleaños)
18. [Encuestas](#18-encuestas)
19. [Reportería e informes](#19-reportería-e-informes)
20. [Cruces](#20-cruces)
21. [Integraciones y sincronización](#21-integraciones-y-sincronización)
22. [Apéndice A — Catálogo de estados](#apéndice-a--catálogo-de-estados)
23. [Apéndice B — Mapa de módulos del menú](#apéndice-b--mapa-de-módulos-del-menú)
24. [Apéndice C — Observaciones técnicas conocidas](#apéndice-c--observaciones-técnicas-conocidas)

---

## 1. ¿Qué es el sistema?

**Klee Planner** (nombre interno de la aplicación: *Polímero*) es un sistema web integral para la **gestión académica y de talento humano** de una institución de educación superior. Cubre el ciclo completo de vinculación y gestión del personal, tanto **docente/académico** como **administrativo**, y la operación académica asociada (programación de clases, labor docente, reportería institucional y regulatoria — SNIES).

En un solo lugar se administra:

- **Talento humano:** requisiciones, procesos de selección, contratación (con firma electrónica), planta activa, perfiles de cargo, periodos de prueba, novedades contractuales, dotaciones, inducción, cumpleaños y encuestas.
- **Operación académica:** pensum, asignaturas, programación de grupos/NRC, asignación de docentes a horarios, labor docente y su aprobación.
- **Reportería:** consolidados de asignación, horas docente, labor, contratación, nómina, cecos y el reporte oficial **SNIES**.

El sistema es utilizado por múltiples perfiles: Gestión del Talento (analistas/psicólogos, contratación, dirección), directores y coordinadores de escuela, jefes inmediatos, docentes y los propios colaboradores (autoservicio).

**Escala del sistema:** ~128 controladores y ~146 modelos.

---

## 2. Arquitectura y funcionamiento general

### 2.1 Stack técnico

| Componente | Tecnología |
|---|---|
| Lenguaje | PHP (framework MVC propio de Klee Software) |
| Base de datos | MySQL (`klee_planner`); conexión secundaria `sai` para Banner |
| Documentos Word | `phpoffice/phpword` |
| PDF | `mpdf/mpdf` (y Dompdf en algunos flujos) |
| Correo | `phpmailer/phpmailer` + parser `php-mime-mail-parser` |
| Editor de texto enriquecido | TinyMCE |
| Firma electrónica | Adobe Sign (API REST + OAuth) |
| IA (conversión DOCX→HTML) | OpenAI / Google Gemini / modelo interno Klee (configurable) |

### 2.2 Patrón MVC y ruteo

- El front controller es `core/AutoLoad.php`: inicia sesión, carga configuración y registra el autoload de clases (controladores, modelos, helpers).
- Las URLs siguen el patrón **`?c=<controlador>&a=<acción>&<parámetros>`**. Por defecto el controlador es `Home` y la acción `list`.
- Cada acción pública se implementa como un método **`<acción>Action()`** dentro del controlador. `Controller::process()` valida el acceso y la invoca.
- `core/Router.php` construye las URLs (`create_action_url`) y **oculta automáticamente los enlaces** a los que el usuario no tiene permiso.

### 2.3 CRUD base y componente de listas (`Lista` / `ListaAjax`)

El framework provee un patrón CRUD uniforme para casi todos los módulos:

- **`core/Model.php`** es un ORM propio. Cada modelo declara sus campos en `getOptionsAttributes()` y hereda `getAll / getById / getByCriteria / save / delete...`. Las consultas se arman con un arreglo `criteria` (`WHERE / ORDER_BY / GROUP_BY / LIMIT`).
- **`core/Lista.php`** y **`core/ListaAjax.php`** renderizan las tablas (DataTables). `ListaAjax` es *server-side*: la vista `list` pinta la tabla y `dataListAjaxAction()` sirve los datos en JSON.
- Funcionalidad estándar disponible en toda tabla del sistema:
  - Columnas tipadas (`Enlace`, `Color`, `Moneda`, `Alias`, `Etiqueta`).
  - **Acciones por fila** (editar / eliminar + acciones personalizadas, con modal de confirmación).
  - **Filtros** de columna y **filtros de sesión** (p. ej. por sede/estado) inyectados automáticamente.
  - **Búsqueda**, ordenamiento y **paginación** (10 … 10.000).
  - **Exportación**: imprimir, copiar, Excel, CSV, PDF y "Excel todo" (hasta 10.000 filas).
  - **Permiso de "solo mis registros"** (nivel 2): un rol puede ver únicamente los registros que él creó.

> En la práctica, "los CRUDs básicos" del sistema (catálogos de la sección 4) son todos instancias de este patrón: crear / editar / ver / eliminar / listar con exportación, más un `cargueMasivo` por CSV en la mayoría.

### 2.4 Vistas y layouts

`core/View.php` renderiza la vista de la acción (`app/views/<controlador>/<vista>.php`) dentro de un layout (por defecto *metronic*), que incluye el menú lateral, accesos directos, mensajes flash y consola de logs.

### 2.5 Auditoría y logs

Existen tres mecanismos:

- **`log_acceso`** (`LogAccesoModel` / `LogAccionesModel`): registra accesos, inicio y cierre de sesión, con **geolocalización por IP** (ipinfo.io). Se activa con `Config::$LOG_ACCESS`.
- **`log_modules`** (`LogModulesModel`): **auditoría CRUD**. Cuando un modelo tiene `$LOG=true`, cada creación / edición / eliminación guarda el usuario, la tabla, la URL y el JSON de los campos que cambiaron (`OldData` / `NewData`). Se activa con `Config::$LOG_MODULES`.
- **`LogsConsole`**: consola de mensajes efímeros en sesión (no persiste en BD).

### 2.6 Integraciones transversales

- **Correo:** dos vías — envío directo por PHPMailer (SMTP) y una cola de correos (`AlertasEmailModel`) despachada por crons; alertas internas en pantalla (`AlertasModel`).
- **PDF:** generación con mPDF a partir de plantillas HTML en `public/plantillas/` (contratos, otrosí, actas de dotación, cartas).
- **Adobe Sign:** firma electrónica de contratos, otrosí y cambios de modalidad (OAuth + *transient documents* + *agreements*), con seguimiento del estado de firma por cron.
- **Banner / SAI (sistema académico institucional):** integración por lotes — exportaciones dejan CSV en `files/data_csv/` o tablas *staging* (`_programaciones`, `_programas`) que el sistema consume vía `Sincronizacion*` y `Archivos::import*`. También hay consumo de una API externa Polímero/Banner para datos de persona (correo institucional, fecha de nacimiento, currículo).
- **IA:** conversión de plantillas `.docx` a HTML (`DocxExtractorService` + `AiHtmlConverterService`).

---

## 3. Seguridad y control de acceso

### 3.1 Login y sesión

- **`LoginController`**: formulario de acceso; toda la sesión cuelga de `$_SESSION['klee_planner']`.
- Autenticación por usuario/contraseña (`UsuariosModel::validateUser`), con **fallback opcional a Directorio Activo / LDAP** (`Config::$directorioActivo`) y validación de **IP/ubicación autorizada** (`unauthorized_ip`, ligado al catálogo *IPs autorizadas*).
- **SSO:** OAuth2 con Microsoft/Azure AD y "sesión remota" entre aplicaciones mediante token (`ApiController::validateSession`).

### 3.2 Usuarios, roles y permisos

- **Usuarios** (`usuarios`): campo `Tipo` (rol), credenciales, `NoIdentificacion`, `Email`, `Sede` (múltiple), `Estado`, `PermisosAdicionales` (JSON), foto. CRUD + carga masiva + cambio de contraseña/foto.
- **Roles** (`roles`): nombre, página de inicio, grupo, descripción, estado. Al eliminar un rol se borran sus permisos en cascada. El sistema tiene ~39 roles configurados (ver `ROLES_Y_PERMISOS.md`).
- **Permisos** (`permisos`): una fila por rol + módulo con un JSON `acción => nivel`. El formulario de permisos se construye leyendo el `AccessControl` del controlador destino.
  - **Niveles:** `0` sin acceso · `1` acceso total · `2` solo registros propios (compara `UsuarioRegistro`).
  - Al iniciar sesión, los permisos se vuelcan a la sesión y determinan el **menú visible** y las acciones habilitadas.
  - El **superusuario (id 1)** tiene acceso total sin depender de la tabla de permisos.
- **Control de acceso por acción** (`loadAccessControl()` en cada controlador):
  - `'*'` = abierto (crons, integraciones, autoservicio público).
  - `'@'` = requiere sesión + permiso del rol.

### 3.3 Bloqueos

**`bloqueos`**: documentos vetados para procesos de contratación, en dos secciones — **gestión de talento** y **gestión docente/académica**. Un documento bloqueado no puede ser incluido en una solicitud de contratación.

### 3.4 Configuración general

**`configuraciones`**: almacén clave-valor (grupo *General* y *Sistema*). Incluye plantillas de correo (inducción, aprobación de perfil, socialización), textos institucionales y el `ApiToken` (guardado con hash) que protege la API de salida.

---

## 4. Catálogos y CRUDs de configuración

Todos son CRUD estándar (listar / crear / editar / ver / eliminar con exportación; la mayoría con `cargueMasivo` por CSV). Alimentan el resto de los módulos.

| Catálogo | Controlador | Qué administra |
|---|---|---|
| Sedes | `Sedes` | Sedes de la universidad (ciudad, vicerrector, código, color, dirección) |
| Áreas | `Areas` | Áreas organizacionales |
| Facultades | `Facultades` | Facultades académicas (código, decano) |
| Escuelas | `Escuelas` | Escuelas por facultad (código, sede, director) |
| Programas | `Programas` | Programas académicos (código, ceco, tipo, metodología, jornadas) |
| Vicerrectoría | `Vicerectoria` | Vicerrectorías |
| Periodos | `Periodos` | Periodos académicos (año, fechas, nº de semanas, banderas de sincronización) |
| Semestres | `Semestres` | Semestres y **semanas de receso** (clave para el cálculo de horas) |
| Cecos | `Ceco` | Centros de costos y su relación con programa/escuela |
| Jornadas | `Jornadas` | Jornadas horarias (código, hora inicio/fin, días) |
| Tipos de contrato | `TiposContrato` | Tipos de contrato docente (horas cátedra mín./máx.) |
| Tipos de contrato administrativo | `TiposContratoAdministrativo` | Tipos de contrato administrativo |
| Cargos académicos | `Cargos` | Cargos docentes (tipo de contrato, horas) |
| Cargos administrativos | `CargoAdministrativo` | Cargos administrativos |
| Dependencias | `Dependencias` | Dependencias/áreas administrativas |
| Ciudades | `Ciudades` | Catálogo de ciudades |
| Edificios | `Edificios` | Edificios por sede |
| Salones | `Salones` | Salones (piso, capacidad, atributo) |
| Tipos de salón | `TipoSalon` | Tipos de salón |
| Cajas de compensación | `CajasCompensacion` | Cajas de compensación (departamento, NIT) |
| IPS autorizadas | `IpsAutorizadas` | IPS autorizadas para exámenes |
| Diplomados | `Diplomados` | Diplomados por periodo (omiten reporte pregrado) |
| Vigencias | `Vigencias` | Vigencias |
| Asignaturas | `Asignaturas` | Catálogo de asignaturas (nivel, modalidad, intensidad) |
| Pensum | `Pensum` | Plan de estudios por programa |
| Tipos de labor docente | `TipoLaborDocente` | Tipos de labor (código, eje estratégico, director) |
| Porcentajes de labor | `PorcentajesLabor` | Distribución % de la carga de labor por semestre |
| Niveles de contribución | `NivelesContribucion` | Nivel de contribución del cargo (perfiles) |
| Descripciones de contribución | `DescripcionesContribucion` | Descriptores de cada nivel |
| Mapa de procesos / subprocesos | `MapaProcesos` / `MapaSubProcesos` | Clasificación de procesos institucionales |
| Cardinales / Jerárquicas / Específicas | `Cardinales` / `Jerarquicas` / `Especificas` | Catálogos de competencias para perfiles |
| Souvenires | `Souvenires` | Souvenirs de inducción (pines, esferos, agendas) |
| Aplicativos periodo de prueba | `AplicativosPeriodoPrueba` | Sistemas sobre los que se evalúa capacitación |
| Minutas | `Minutas` | Catálogo de minutas contractuales por sección |
| Plantillas | `Plantillas` | Gestor de plantillas HTML (contratos, actas) |

---

## 5. Planta activa / Colaboradores

**Propósito.** La tabla `colaboradores` es el **hub central** del sistema: consolida la planta activa (académicos + administrativos) unificando las dos fuentes de contratación. Todos los demás módulos la consultan por `NoDocumento`, `CorreoInstitucional` o `IdSolicitud`.

**Campos clave.** `Rol` (Académico/Administrativo), `TablaOrigen` (`SolicitudContratos` o `SolicitudContratosAdministrativo`), `IdSolicitud`, `Estado`, `IdPerfilCargo`, `AprobacionPerfli`, `IdDotacion`, `ModalidadTrabajo`, `GestionadoTalentoHumano`.

**Estados del colaborador:** `1` Activo · `0` Inactivo · `2` Congelado · `3` Incapacidad-Licencia.

**Funciones principales:**
- **Planta activa** y **Planta activa académica** (vistas filtradas por tipo).
- CRUD y reporte general con filtros (fecha, tipo de contrato, estado, rol).
- Correo de bienvenida / pasos de ingreso (`alertaAction`).
- Aprobación de perfil de cargo (individual y masiva).
- Sincronización de `IdPerfilCargo`, sede y ciudad desde las solicitudes y desde la API de currículo.
- **Cargues y actualizaciones masivas por CSV** (colaboradores, fechas, campos por cédula, modalidad).
- **Crons de reactivación/inactivación:** reactivan colaboradores con novedad/licencia vigente y aplican la regla del **"mejor contrato"** por persona (gana el indefinido; si no, el de fecha de fin más lejana); inactivan contratos vencidos.

**Módulos relacionados:**
- **Colaboradores antiguos** (`colaboradores_antiguos`): histórico de excolaboradores con cálculo de antigüedad (días/meses/años) y reportes.
- **Colaboradores sin encontrar** (`colaboradores_sin_encontrar`): cola de personas que no se pudieron cruzar con una solicitud durante los cargues masivos.

---

## 6. Perfiles de cargo

**Propósito.** Definir, versionar, aprobar y socializar el **perfil de cargo** (descripción de puesto) de cada rol: formación y experiencia requeridas, propósito, funciones (área / frecuencia / nivel), competencias (cardinales, jerárquicas, específicas), nivel de contribución y jefe inmediato. Cada perfil pasa por una **cadena de aprobación de tres firmantes** y una **socialización final** con cada colaborador que ocupa el cargo.

**Entidad principal:** `perfil_cargo` (tabla muy ancha: 35 competencias, 18 áreas/frecuencias/niveles, metadatos de aprobación). Relacionadas: `perfil_cargo_versions`, `perfil_cargo_exepciones`, `historico_colaborador_perfiles`, `cargo_administrativo`, `niveles_contribucion`, `descripciones_contribucion`.

### 6.1 Roles que intervienen

| Rol | Papel en el perfil |
|---|---|
| **Psicólogo / Analista de Selección** | Elabora y aprueba el perfil (aprobación inicial) |
| **Jefe inmediato** | Aprueba o rechaza |
| **Director de Gestión de Talento** | Aprobación final |
| **Colaborador** | Socializa (declara que leyó su perfil) |
| **Gestión del Talento (admin)** | Cargues masivos, excepciones, activar/inactivar, reportes, restablecer socialización |

### 6.2 Ciclo de vida

```mermaid
stateDiagram-v2
    [*] --> Creado: Psicólogo crea el perfil
    Creado --> ApruebaPsicologo: aprobación psicólogo
    ApruebaPsicologo --> ApruebaJefe: correo al jefe
    ApruebaJefe --> ApruebaDirector: aprobación jefe
    ApruebaDirector --> Socializacion: aprobación director → correo a colaboradores
    Socializacion --> Aprobado: colaborador socializa (manual o Adobe Sign)
    ApruebaJefe --> Rechazado: rechazo con observación → alerta al psicólogo
    ApruebaDirector --> Rechazado: rechazo con observación → alerta al psicólogo
    Aprobado --> NuevaVersion: edición con "Crear versión"
    NuevaVersion --> ApruebaPsicologo: reinicia las 3 aprobaciones
```

**Estados de aprobación** (por firmante): `1` Aprobado · `0` Rechazado · `2` Pendiente.
**Estado del perfil:** `1` Activo · `0` Inactivo · `2` Sin aprobar.
**Socialización del colaborador** (`AprobacionPerfli`): `1` Socializado · `2` Sin socializar · `3` Restablecido para re-socializar · `0` blanqueado por cambio de versión.

**Pasos:**
1. **Creación (psicólogo):** se inicializan las tres aprobaciones en *pendiente*, se registra al psicólogo como quien elabora y se siembra el cargo en `cargo_administrativo`.
2. **Aprobación del psicólogo:** al aprobar, encola el correo de "aprobación del jefe inmediato".
3. **Aprobación del jefe:** aprueba o rechaza (con observación → alerta al psicólogo).
4. **Aprobación del director:** al aprobar, se encola el correo de "socialización" a todos los colaboradores con ese perfil.
5. **Socialización del colaborador:** dos vías — **manual** (el colaborador marca "socializado" desde su ficha) o **automática vía Adobe Sign** (un cron consulta acuerdos firmados y marca la socialización).
6. **Recordatorios:** un cron diario recuerda al jefe (si falta su aprobación) y a los colaboradores (si falta socializar).

### 6.3 Versionamiento y trazabilidad

- Cuando un perfil aprobado se edita con "Crear versión", se guarda un **snapshot completo** en `perfil_cargo_versions`, se **blanquean las socializaciones** de todos los colaboradores del cargo, se registra el cambio en `historico_colaborador_perfiles` y se **reinician las tres aprobaciones** (obliga a re-aprobar y re-socializar).
- **Excepciones de perfil** (`perfil_cargo_exepciones`): perfiles "congelados" cuyo nombre **no** debe propagarse a la planta al editarse/versionarse.
- **Archivos para perfiles** (`archivos_perfiles`): repositorio de formatos/anexos PDF descargables.

### 6.4 Reportes del módulo

- **Reporte plano de perfiles:** vuelca ~90 columnas del perfil en tabla plana.
- **Socialización de perfiles:** cruce planta activa vs. perfil (con/sin perfil asignado).
- **Aprobaciones de perfiles** y **versionamiento** (histórico de versiones).
- **Reporte brecha de perfil** (reside en Contratación administrativa): compara el perfil requerido contra la persona.

### 6.5 Catálogos que alimentan el perfil

Niveles y descripciones de contribución, mapa de procesos/subprocesos y las tres familias de competencias (**cardinales** = transversales, **jerárquicas** = liderazgo, **específicas** = técnicas).

---

## 7. Contratación académica (docentes)

**Propósito.** Gestionar la solicitud de contratación de un docente desde su creación (nace de la programación académica) hasta la firma y alta en planta activa, con checklist de documentos, seguridad social, contrato en Adobe Sign, periodo de prueba e inducción.

**Entidad principal:** `solicitud_contratos`. Campos clave: `EstadoProceso`, `IdAsociado` (0 = solicitud "padre"; >0 = NRC añadido a otra), responsables (`Responsable`, `ResponsableRecibe`, `ResponsableRecibeContratacion`), checklist de documentos, `Minuta`, `IdAdobe`/`EstadoAdobe`, `PeriodoPruebaEnviado`, `ObservacionesEstados` (historial JSON de transiciones).

### 7.1 Estados

| Valor | Estado |
|---|---|
| -2 | Regresado |
| -1 | Devuelto |
| 0 | Pendiente |
| 1 | Solicitado |
| 2 | Recibido TH |
| 3 | En proceso administrativo |
| 4 | Reportado para contratación |
| 5 | Contrato enviado |
| 6 | Firmado y contratado |
| 7 / 8 / 9 / 10 | Migrado / Renuncia / Cancelado / Inactivo |

### 7.2 Flujo

```mermaid
flowchart TD
    A[Creación - Solicitado 1<br/>coordinador/director] --> AV{¿Honorarios?}
    AV -->|Sí| AVAL[Cadena de aval<br/>Jefe → Sec. Académica → Dir. Talento]
    AVAL --> B
    AV -->|No| B[Recibido TH 2]
    B --> C[Proceso administrativo 3<br/>psicólogo: checklist de documentos]
    C --> D[Reportado para contratación 4<br/>envía carta oferta + asigna responsable]
    D --> E[Contrato enviado 5<br/>minuta PDF + Adobe Sign]
    E --> F[Firmado y contratado 6<br/>alta en planta + descuenta planta autorizada]
    F --> G[Periodo de prueba]
```

**Pasos y roles:**
1. **Creación — Solicitado (1).** Rol: coordinador/director de escuela. Valida que el docente **no esté bloqueado** y que no exista otra solicitud vigente con **fechas solapadas** (salvo NRC). Autoasigna un **psicólogo** (por menor carga). Ventana de edición de 1 hora. Si es de **honorarios**, dispara la cadena de aval y queda en *Pendiente (0)* hasta que el aval se complete.
2. **Recibido TH (2) → Proceso administrativo (3).** Rol: psicólogo/analista. Diligencia el checklist de documentos y seguridad social. Al reportar (estado 4) envía la **carta oferta** y asigna el **responsable de contratación** (por carga equitativa).
3. **Reportado (4) → Contrato enviado (5).** Rol: contratación. Genera la **minuta** (mPDF según plantilla) y la envía a **Adobe Sign** (firman colaborador + jefe).
4. **Firmado y contratado (6).** Al firmar: propaga el estado a los NRC asociados, **descuenta días de la planta autorizada** (y registra el movimiento), da de alta al colaborador en planta, crea su usuario (rol docente), crea la inducción si aplica y arranca el periodo de prueba. *(Revertir el estado devuelve los días a la planta autorizada.)*
5. **Periodo de prueba.** Ver [sección 10](#10-periodos-de-prueba).

**Reglas notables:** anti-duplicado por fechas solapadas; bloqueos de docentes; autoasignación de responsables por carga; `IdAsociado` para agrupar NRC; término indefinido se guarda con `FechaFin = 0000-00-00`; cada transición se registra en el historial JSON y genera una alerta.

### 7.3 Planta autorizada

**`planta_autorizada`** es la "bolsa" presupuestal de días de contratación por tipo de dedicación. Cada contratación **descuenta** días y cada cancelación los **devuelve**; **`planta_autorizada_movimientos`** es el libro de auditoría de esos movimientos. Los reportes de "cruce planta vs contratados" y "contratados por plaza" se basan en estas tablas.

---

## 8. Contratación administrativa y procesos de selección

**Propósito.** Gestiona el ciclo completo de **selección y contratación de personal administrativo y aprendices**: requisición, asignación de psicólogo, terna de candidatos, entrevistas y pruebas, aprobación de perfil por jefes, verificación documental, generación de minuta, firma Adobe Sign, alta en planta y periodo de prueba.

**Entidad principal:** `solicitud_contratos_administrativo` (~200 columnas). Es orquestada por el controlador más grande del sistema (`SolicitudContratosAdministrativoController`, ~10.400 líneas).

### 8.1 Estados

**Estado maestro (`EstadoProceso`):**

| Valor | Estado |
|---|---|
| 0 | Congelada |
| 1 | Contratado (planta activa) |
| 2 | Inactivo |
| 3 | En proceso de selección |
| 4 | Selección de candidato |
| 5 | Verificación candidato |
| 6 | En contratación |
| 7 / 8 / 9 | Migrado / Renuncia / Cancelado |

**Sub-estado de la fase de selección (`EstadoSolicitud`, 1–6):** Publicación → Recepción/filtro → Entrevistas → Pruebas de evaluación (cada transición sella marcas de tiempo).

### 8.2 Flujo

```mermaid
flowchart TD
    R[Requisición - opcional<br/>área solicitante] --> S1[Creación 3 - En selección<br/>asigna psicólogo por menor carga]
    S1 --> S2[Recepción y filtro<br/>terna de candidatos + hojas de vida]
    S2 --> S3[Entrevistas y pruebas<br/>notas por etapa]
    S3 --> S4[Formato finalistas + brecha perfil<br/>doble aprobación: Jefe + Dir. Talento]
    S4 --> S5[Selección de candidato 4]
    S5 --> S6[Verificación candidato 5<br/>correo pre-ingreso + docs SARLAFT/EPS/AFP/examen]
    S6 --> S7[En contratación 6<br/>asigna responsable + minuta]
    S7 --> S8[Contratar → Contratado 1<br/>crea usuario y colaborador]
    S8 --> S9[Adobe Sign<br/>firmantes según minuta]
    S9 --> S10[Periodo de prueba]
```

**Pasos y roles:**
1. **Requisición (opcional).** El área solicita una vacante; se notifica a decano, director de programa y gestión.
2. **Creación — En selección (3).** Se **asigna automáticamente el psicólogo** con menor carga en el año (balanceo round-robin; hereda el psicólogo si el jefe ya tiene un proceso activo). Soporta N plazas.
3. **Recepción y filtro.** El psicólogo carga la **terna de candidatos** y sus hojas de vida (PDF), registra entrevista inicial, entrevista final, prueba técnica, assessment center y prueba psicotécnica.
4. **Formato de finalistas + brecha de perfil.** Se sube el concepto del candidato finalista y se envía por correo. **Doble aprobación:** jefe inmediato y director de gestión de talento. Si hay brecha de perfil, se involucra a la dirección.
5. **Selección de candidato (4)** → **Verificación (5).** Se fija el candidato seleccionado, se le envía el correo de **documentación de pre-ingreso** y se hace la verificación documental (SARLAFT, EPS, AFP, AFC, ARL, examen médico, certificación bancaria, etc.). Si el candidato desiste, se revierte a estado 3.
6. **En contratación (6).** Se asigna el responsable de contratación y se genera la **minuta/contrato** (HTML editable en TinyMCE → PDF con mPDF).
7. **Contratar → Contratado (1).** Crea el usuario y el registro en `colaboradores`, crea la inducción si aplica, y encamina a la **firma electrónica (Adobe Sign)** — los firmantes (2, 3 o gerente) dependen de la minuta.
8. **Periodo de prueba.** Ver [sección 10](#10-periodos-de-prueba).

**Automatizaciones (cron):** seguimiento de firmas en Adobe, baja automática de contratos vencidos, alertas de vencimiento (15 días antes para temporales), (re)asignación masiva de responsables.

### 8.3 Módulos satélite

- **Requisiciones** (`requisiciones`): solicitud formal de vacante previa al proceso, con selección/devolución de candidato notificada por correo.
- **Candidatos entrevista inicial** (`candidatos_entrevista_inicial`): candidatos ligados a una solicitud que alimentan la terna.
- **Examen médico** (`examen_medico`): catálogo de fechas de examen por documento (con carga masiva CSV) para los cruces de contratación.
- **Cambio de modalidad:** ver [sección 9](#9-solicitudes-novedades-aval-de-honorarios-y-adicionales).

### 8.4 Reportes y utilidades del módulo

Cuota SENA, reporte base de ingresos, reporte brecha de perfil, reporte de académicos y administrativos en proceso, auditoría de formatos de candidatos finalistas, certificaciones, cargues masivos (activar/desactivar, modificar data, cargar nueva data), y el reporte de Adobe.

---

## 9. Solicitudes: novedades, aval de honorarios y adicionales

### 9.1 Novedades de contrato (académicas y administrativas)

**Propósito.** Registrar novedades sobre un contrato ya firmado y generar el **"otro sí"** correspondiente (firma en Adobe Sign).

- **Académicas** (`solicitud_novedades`): tipo **1** contrato/prórroga, **2** agregar NRC, **5** liquidación. Al procesar, actualiza `colaboradores` (nuevo registro si cambia el cargo; si no, ajusta la fecha fin), **descuenta días de la planta autorizada**, notifica al director si cambian las fechas y envía el otrosí.
- **Administrativas** (`solicitud_novedades_administrativo`): tipo **1** prórroga, **2** vacaciones/incapacidad de aprendiz, **5** incapacidad/licencia administrativa. La prórroga corre la fecha fin; el aprendiz suma días; la incapacidad/licencia pone al colaborador en estado 3.

**Estados de novedad:** `0` Pendiente · `1` Recibida · `2` Contrato enviado · `3` Firmado y contratado · `8` Rechazada · `9` Cancelado.

### 9.2 Aval de honorarios

**Propósito.** Cadena de aprobación **obligatoria previa** para contrataciones de honorarios. Mientras el aval no se complete, la solicitud de contratación queda bloqueada en *Pendiente (0)*; al completarse pasa a *Recibido TH (2)*.

```mermaid
flowchart LR
    J[Pendiente Jefe 0] -->|aprueba jefe| S[Avalado Jefe 1]
    S -->|aprueba Sec. Académica| D[Avalado Sec. 2]
    D -->|aprueba Dir. Gestión Talento| C[Avalado completo 3<br/>→ solicitud pasa a Recibido TH]
    J -->|rechazo| X[Rechazado -1<br/>→ solicitud Devuelta]
    S -->|rechazo| X
    D -->|rechazo| X
```

**Estados del aval:** `0` Pendiente Jefe · `1` Avalado Jefe · `2` Avalado Sec. Académica · `3` Avalado completo · `-1` Rechazado.
El rechazo en cualquier nivel devuelve la solicitud a estado `-1` (Devuelto) y acumula la observación en el historial.

### 9.3 Solicitudes adicionales

**Propósito.** Contrataciones adicionales por honorarios (dictado de módulos), con soporte para **dos personas por solicitud**: el **Autor** y el **Par**, cada uno con su propio flujo de estados, honorarios, contrato y aprobación de pago.

**Estados (por Autor y por Par):** `2` Pendiente → `1` Aprobado Jefe (o `0` Rechazado) → `5` Aprobado Talento (o `9` Rechazado) → `6` Contrato enviado → `7` Firmado y contratado → `8` Aprobado para pago. (`10` = no cuenta con par/autor; `3` novedad, `4` rechazado contratación auxiliares.)

**Flujo:** alta (manual o cargue CSV) → aprobación de jefe → aprobación de talento → contratación (minuta) → firma Adobe Sign (2 o 3 firmantes según minuta) → firmado → aprobado para pago.

**Versionamiento automático:** cada edición guarda una **versión completa** en `solicitudes_adicionales_versions` (solo lectura), permitiendo ver el histórico de una solicitud. Las aprobaciones (aprobador + fecha) se toman de la sesión, no del formulario (auditoría server-side).

### 9.4 Cambio de modalidad

Cambia la `ModalidadTrabajo` de un colaborador de planta activa y genera/envía el otrosí correspondiente por Adobe Sign (firman colaborador y jefe).

---

## 10. Periodos de prueba

**Propósito.** Formato de evaluación del periodo de prueba de un colaborador recién contratado (académico o administrativo): adaptación, adecuación, evaluación, reconocimiento/inducción, descripción del cargo, aplicativos, y formación y desarrollo.

**Entidad principal:** `periodos_prueba`. Se relaciona con el colaborador, con la solicitud de contrato de origen (académica o administrativa) y con el usuario evaluador/aprobador. Tiene una sub-entidad `calificacion_aplicativos_periodo_prueba` para calificar los sistemas (SAP, Banner, Canvas, etc.) sobre los que se capacitó al colaborador.

**Estados** (`EstadoPeriodoPrueba`, espejo con `PeriodoPruebaEnviado` de la solicitud):

| Valor | Estado |
|---|---|
| -1 | Rechazado por colaborador |
| 0 | Rechazado |
| 1 | Aprobado |
| 2 | No aprobado |
| 3 | Asignado |
| 4 | Sin asignar |
| 5 | No aplica |
| 6 | No reporta formato evaluador |
| 7 | Socializado |

### 10.1 Ciclo

```mermaid
flowchart TD
    A[Asignación 3<br/>al notificar al candidato en contratación] --> B[Diligenciar<br/>jefe/director evaluador + califica aplicativos]
    B --> C{Aprobación}
    C -->|aprueba| D[Aprobado 1]
    C -->|no aprueba| E[No aprobado 2<br/>alerta a Admón Laboral + Seguridad Social]
    D --> F[Recibir / Socializar 7]
    A -.cron vencimiento.-> G[No reporta formato 6]
```

**Pasos y roles:**
1. **Asignación (RRHH/Contratación).** Al notificar al candidato seleccionado, la solicitud queda en estado *Asignado (3)* y se crea el periodo de prueba con su evaluador (director de escuela en académicos; jefe inmediato en administrativos) y fechas límite.
2. **Diligenciamiento (jefe/director evaluador).** El evaluador completa el formato, incluyendo la calificación de aplicativos (escala 0–3).
3. **Aprobación (jefe/director).** Pantallas separadas para administrativos (cada jefe ve solo los suyos, filtrado por su correo) y académicos. Se aprueba (→1) o no (→0/2).
4. **Recepción / socialización (RRHH y colaborador).** Se registra la recepción y la socialización (→7).
5. **Notificación de resultado.** Al colaborador; si el resultado es *No aprobado*, se alerta a la Dirección de Administración Laboral y a Seguridad Social.

**Reglas y crons:** recordatorio automático al evaluador 2 días antes del vencimiento; los periodos vencidos sin diligenciar pasan a *No reporta formato (6)*. La escala de calificación varía por sección (No alcanza / Puede mejorarse / Alcanza el nivel; o No se ejecutó / Parcial / Ejecutado).

> **Nota:** la **"Evaluación 360"** del menú es un **sistema externo** independiente (`polimeroevaluacion360.poligran.edu.co`); no forma parte del flujo del periodo de prueba dentro de este sistema.

---

## 11. Labor docente

**Propósito.** Gestionar el **acta de labor docente**: consolidar por docente y periodo las horas de docencia directa y las labores adicionales (proyectos), imprimirla, enviarla al docente para su aprobación y tramitar solicitudes de ajuste.

**Entidades:**
- `labor` (acta de labor por docente y periodo).
- `proyectos` (catálogo de actividades/labores por tipo) y `proyectos_docentes` (líneas de la hoja de labor: docente ↔ proyecto ↔ periodo, con horas). Convención: `IdProyecto = 1` es docencia directa; `> 1` son labores/proyectos adicionales. `proyectos_entregables` = entregables de cada proyecto.
- `solicitudes_labor` (solicitudes de ajuste sobre un acta).
- `porcentajes_labor` (distribución % de la carga por semestre; la suma debe dar 100%).

**Estados del acta (`EstadoLabor`):** `0`/`1` Pendiente → `2` En cola de envío → `3` Enviada → `4` Aceptada · `9` Rechazada.
**Estados de solicitud de ajuste:** `0` Pendiente · `1` Aprobada · `2` Rechazada.

### 11.1 Flujo del acta de labor y solicitudes de ajuste

```mermaid
flowchart TD
    A[Sincronización cron<br/>crea el acta - Pendiente 1] --> B[Asignar labor<br/>director/coordinador agrega líneas de proyectos]
    B --> C[Enviar → En cola 2]
    C --> D[Cron envía correo → Enviada 3]
    D --> E{Docente revisa}
    E -->|acepta| F[Aceptada 4<br/>alerta al director]
    E -->|rechaza| G[Rechazada 9<br/>alerta al director]
    F --> H{Solicitud de ajuste}
    H -->|crea solicitud 0| I[Aprobador resuelve]
    I -->|aprueba 1| B
    I -->|rechaza 2| F
```

**Pasos y roles:**
1. **Generación del acta.** Un cron crea/actualiza las actas de la planta académica del periodo actual (*Pendiente*).
2. **Asignación de labor.** El **director de escuela** / coordinadores agregan las líneas de docencia directa y proyectos, respetando horas mínimas/máximas y los **porcentajes por semestre**. El acceso está restringido por escuela según el rol.
3. **Envío.** Se pone *En cola (2)* y un cron envía el correo al docente (*Enviada, 3*).
4. **Aprobación del docente.** El docente **acepta (4)** o **rechaza (9)** su acta. Si tiene encuestas pendientes, no puede aprobar/rechazar.
5. **Solicitud de ajuste.** El director/coordinador crea una solicitud (*Pendiente, 0*) dirigida al aprobador; si este la **aprueba**, el acta se reabre para editar y reenviar.

**Proyectos y tipos de labor:** el catálogo de proyectos (con horas mín./máx. y programas) y los tipos de labor docente (código, eje estratégico, director) parametrizan el módulo. El código **500** identifica la docencia directa.

---

## 12. Asignación / Programación académica

**Propósito.** Crear los **grupos/NRC** (secciones) de las asignaturas por periodo y asignarles docentes a nivel de **horario (franja)**, con vistas lista, gráfica y consolidada; exportar a Banner.

**Entidades:**
- `programacion` (el NRC/grupo: periodo, CRN, sede, asignatura, nivel, escuela, programa, pensum, grupo, créditos, cupos, jornada, presencial/virtual, franja, espejo).
- `programacion_horarios` (las franjas de cada NRC; **aquí se asigna el docente**: día, hora, fechas, docente, horas, salón, edificio).
- `programacion_asignacion` (qué usuario/planificador es responsable de programar cada ámbito por periodo/sede/programa).

### 12.1 Flujo

1. **Insumos:** pensum + asignaturas (intensidad) + partes de periodo (calendario) + semestres (recesos).
2. **Creación de grupos/NRC** (planificador/coordinador): se crean en `programacion` (manual o cargue CSV), tomando datos del pensum.
3. **Asignación de docente** sobre `programacion_horarios.Docente`:
   - **Vista gráfica:** tablero por escuela con **semáforo** por asignatura (verde = completo, amarillo = en proceso, rojo = pendiente); asignación por franja con **docentes recomendados por afinidad**.
   - **Vista lista:** asignación masiva por NRC.
4. **Vista consolidada:** total de horas por docente en el semestre (cálculo que excluye semanas de receso), con estado de contratación y de labor.
5. **Relación con contratación:** cada horario muestra el estado de contrato del docente (vigente / enviado / sin contrato) y alerta si no está asignado en Banner.
6. **Exportación a Banner** (formato SSASECT).

**Cálculo de horas:** se computa semana a semana excluyendo recesos, distinguiendo presencial (P) vs. virtual (V), nivel, franjas y rangos de inscritos.

---

## 13. Docentes y estructura académica

- **Docentes** (`docentes`): ficha del docente con pestañas de información, labor, asignaturas, horario y hoja de vida (educación, experiencia, investigaciones). Login del docente como rol propio; carga masiva por CSV; autocompletado por documento.
  - **Docentes-asignaturas** (con **afinidad** y jornadas) alimentan la recomendación de docentes en la asignación.
  - **Docentes-horario**: disponibilidad por franja.
  - **Docentes-cecos**: reporte de distribución por centro de costo (CECO, programa, estudiantes, SNIES).
- **Pensum** (`pensum`): plan de estudios por programa (asignatura, semestre, créditos, intensidad, transversalidad). Con aprobación y clonación. Alimenta la programación.
- **Asignaturas** (`asignaturas`): catálogo con nivel, modalidad e intensidad horaria (base del cálculo de horas).
- **Calendario académico** (`partes_periodo`): partes de periodo (modalidad, nivel, fechas, sede), con carga masiva.
- **Semestres**: definen las **semanas de receso** (Fin de Año, Semana Santa, Octubre), clave para el cálculo de horas.

---

## 14. Inducción y reinducción

### 14.1 Inducción

**Propósito.** Gestión de la inducción de nuevos colaboradores: agendamiento, invitación por correo, registro de asistencia y observaciones.

**Entidad:** `inducciones`. **Estados:** `0` Pendiente · `1` Asistió · `2` Renunció · `3` Asistió reinducción · `4` No asistió · `5` Pendiente-activo · `6` Asistió-no registro · `7` No asistió-contrato finalizado.

**Flujo:** crear/importar candidatos → **enviar la plantilla de invitación** (Bogotá = presencial, resto = virtual) → registrar asistencia (individual, masiva o autoservicio del colaborador) → observaciones → archivar o derivar a reinducción. Rol responsable: psicólogo. Incluye reporte de observaciones y gestión de soportes/cartilla.

### 14.2 Reinducción

**Propósito.** Reinducción anual de la planta ya existente (`reinducciones`), con seguimiento de asistencia por año. Cargue masivo con validación estricta de plantilla (encabezado exacto, encoding y formato de fecha) y descarga de plantilla. **Estados:** `1` Asistió · `4` No asistió · vacío = No aplica.

### 14.3 Inventario de refrigerios y souvenirs

- **Inventario inducción** (`inventario_induccion`): control de refrigerios/souvenirs y **facturación** por evento (comprados vs. entregados, participantes, factura con soporte PDF; estado de factura: en proceso de pago / pagada). Al registrar, envía la factura por correo.
- **Souvenires** (`souvenires`): catálogo (pines, esferos, agendas) con cantidades totales, asignadas y disponibles; recalcula lo disponible a partir de lo entregado en el inventario.

---

## 15. Dotaciones y bonos

**Propósito.** Gestión de dotación (uniformes/prendas) y bonos por colaborador: catálogo, tallas, asignación, generación y firma de actas.

**Entidades:** `dotaciones` (catálogo por sede/género con cantidades por prenda y banderas de bono), `dotaciones_personalizado` (override a medida), `tallas_dotaciones`, `proceso_dotacion`, `bonos_colaborador` (acta de bono por mes/año), más banderas en `colaboradores` (`IdDotacion`, `DotacionEnviadaActa`, `DotacionRecibida`).

**Estados:** recibido `0` Sin recibir / `1` Recibido; acta enviada `0` / `1`.

### 15.1 Flujo

1. **Cargar catálogo** de dotaciones (CSV).
2. **El colaborador registra sus tallas** (autoservicio) — o carga masiva de tallas.
3. **Asignar dotación** a un colaborador (o **personalizar** cantidades a medida).
4. **Enviar acta:** genera el **acta PDF** (mPDF, plantillas de bono/ropa), la envía por correo, marca *enviada* y crea el registro de bono si aplica. Los temporales se marcan enviado/recibido sin generar acta.
5. **El colaborador aprueba recibido** (autoservicio) y sube el **acta firmada** (PDF).
6. **Reportes** de actas firmadas (dotación y bonos) y cierre mensual con histórico de planta.

**Roles:** asignador (Gestión del Talento) vs. colaborador (autoservicio de tallas y aprobación de recibido).

---

## 16. Cartas, plantillas y minutas

### 16.1 Cartas

**Propósito.** Generar y enviar **cartas/notificaciones masivas** a docentes (bienvenida, notificación de asignación por periodo/parte/escuela).

**Entidades:** `cartas` (tipo, periodo, partes, escuelas; el **contenido HTML se toma de un archivo `.eml`** parseado, con imágenes embebidas) y `cartas_destinatarios` (destinatarios cruzados con la programación).

**Estados de la carta:** `0` Pendiente · `1` Creado · `2` Enviado · `3` Completo. **Estados de destinatario:** `1` Pendiente · `2` Enviado · `3` No aplica.

**Flujo:** crear la carta (elige plantilla `.eml` por tipo) → **sincronizar destinatarios** (cruce de programación de horarios con planta activa) → enviar (un cron despacha por SMTP, reemplazando placeholders como nombre, NRC, tabla de horarios, periodo) → histórico de envíos.

### 16.2 Plantillas

Gestor de archivos HTML en `public/plantillas/` (usados por dotaciones, minutas y contratos). Permite subir, editar, previsualizar y descargar, y **convertir `.docx` a HTML** mediante IA (por trozos).

### 16.3 Minutas

Catálogo de minutas contractuales por sección (académico, académico-novedad, administrativo, administrativo-novedad, cambio de modalidad); consumido por la generación de contratos y por Plantillas.

---

## 17. Cumpleaños

**Propósito.** Automatizar el envío de tarjetas de felicitación a los colaboradores el día de su cumpleaños.

**Entidad:** `cumpleanos` (nombre, documento, fecha de nacimiento, correo, estado de envío, año). **Estados de envío:** `0` Sin enviar · `1` Enviado.

**Flujo:**
1. **Subir la plantilla base** de la tarjeta (`plantilla.jpg`).
2. **Sincronizar/listar** cumpleañeros (obtiene la fecha de nacimiento desde las solicitudes o desde la API Banner/Polímero).
3. **Cron diario:** busca los cumpleaños del día no enviados; si el colaborador ya no está activo lo desactiva; si está activo, **genera un JPG escribiendo el nombre sobre la plantilla** (GD), lo adjunta y envía el correo, y marca *enviado*.

**Regla:** una tarjeta por año por colaborador.

---

## 18. Encuestas

**Propósito.** Crear encuestas dinámicas, asignarlas a colaboradores, permitir que las presenten y consolidar resultados.

**Entidades:** `encuestas` (preguntas en JSON, correos habilitados, periodo) y `respuestas_encuestas` (respuestas en JSON, finalización, autorización de tratamiento de datos).

**Flujo:**
1. **Crear** la encuesta (preguntas dinámicas en JSON).
2. **Asignar correos hábiles** (individual o masivo por CSV de cédulas cruzado con planta activa).
3. **El colaborador la presenta** (identificado por su correo institucional), **autoriza el tratamiento de datos** y responde — **una sola vez por periodo**.
4. **Resultados** (tabla y gráficos) sobre las respuestas finalizadas.

**Roles:** administrador (crear/asignar/resultados) vs. colaborador (presentar/responder). *Nota: la aprobación de labor docente se bloquea si el docente tiene encuestas pendientes.*

---

## 19. Reportería e informes

El módulo **Reportes** es el más extenso del sistema y consolida datos de contratación, programación, labor, planta y SNIES. Casi todos generan una tabla exportable.

### 19.1 Reportes académicos

- **General de asignaciones**, **Asignación pregrados** y **Asignación posgrados** (consolidado por parte de periodo).
- **Horas docente** y **Total horas docentes** (por docente y semestre, escalado a 8/16 semanas).
- **Labor**, **Labor detallada**, **Labor resumen** y **Reporte labor docente** (por proyecto/entregable/tipo de labor).
- **SNIES** (reporte oficial), **Histórico de docentes cecos**.
- **Seguimiento diario de asignaciones** (horarios sin docente / con docente sin contratar).
- **Docentes vs. contratación**, **Histórico de contratos**, **Reporte de solicitudes de aval**.

### 19.2 Reportes de contratación

- **Plantilla de ingresos** y **Reporte de ingresos** (contratados por tipo de contrato y rango de fechas).
- **Reporte plano** (tutores a término fijo con horas contratadas; con variante por cron y exportación CSV).
- **Reporte de Adobe** (por mes, para el sistema de firma).
- **Solicitudes de contratación**, **Consolidado de docentes contratados**, **Reporte base de ingresos**.
- **Documentos** (CV, formato de autorización), **Auditoría de solicitudes adicionales**.

### 19.3 Reportes de perfiles, dotaciones y administrativos

- Perfiles: reporte plano, socialización, histórico, versionamiento, aprobaciones, brecha de perfil.
- Dotaciones: actas firmadas (dotación y bonos), personas encontradas.
- Administrativos: reporte de inducción, inventario de refrigerios, auditorías de formatos, cuota SENA.

### 19.4 Informes

- **SNIES** (genera el reporte oficial a partir de planta académica, contratos vigentes, horas y códigos SNIES).
- **Nómina**, **Cecos** (con plantillas de carga por Excel/CSV) e **Histórico por NRC**.

### 19.5 Históricos

Snapshots generados de reportes de **pregrado**, **posgrado**, **consolidado de docentes contratados** y **reporte plano** (con su data de origen).

---

## 20. Cruces

Reportes que confrontan la **asignación académica** contra la **contratación**, apoyados en vistas SQL dedicadas:

- **Cruce de asignación frente a contratados.**
- Contratados sin asignación / asignados sin contrato / asignados con solicitud.
- Cruce planta vs. contratados y contratados por plaza (contra la planta autorizada y sus movimientos).

---

## 21. Integraciones y sincronización

### 21.1 Sincronización con Banner / SAI

**`Sincronizacion`** importa datos de Banner por lotes (la mayoría de acciones se ejecutan por cron):
- **Programación** (`grupos.csv`) → crea/edita grupos y horarios.
- **Docentes** (`docentes.csv`) → crea/edita docentes.
- **Solicitudes/estados** (`status.csv`) → actualiza estados de solicitudes.
- **Históricos de NRC**, **solicitudes de labor** y **programas** (desde tablas staging `_programas`).
- El modelo de sincronización apunta a la conexión externa **`sai`** (Banner); el resto de la app usa `klee`.

**`Archivos`** genera PDFs (mPDF) e importa periodos, partes de periodo y programaciones desde la tabla staging `_programaciones`.

> La integración con Banner es **en dos pasos** (exportaciones dejan CSV o tablas staging que el sistema consume); no hay conexión en tiempo real dentro del código.

### 21.2 API de salida

**`Api`**: API JSON protegida con **bearer token** (validado contra el `ApiToken` de configuración). Expone: planta activa, programación de horarios, labor y soporte de SSO (`validateSession`).

### 21.3 AJAX interno

**`Ajax`**: endpoints internos para filtros de programación, consultas de bloqueos, planta autorizada, datos de solicitud/ceco, y carga por *chunks* de CSV grandes para el informe de cecos.

### 21.4 Firma electrónica (Adobe Sign)

Presente en toda la contratación (académica, administrativa, novedades/otrosí, cambio de modalidad, solicitudes adicionales): OAuth + carga del PDF + creación del acuerdo, con firmantes determinados por la minuta y seguimiento del estado de firma por cron.

### 21.5 API externa Polímero/Banner de persona

Consulta de datos de persona (correo institucional para inducción, fecha de nacimiento para cumpleaños, tipo de documento del currículo) vía token de autenticación institucional.

---

## Apéndice A — Catálogo de estados

**Solicitud de contratación académica (`EstadoProceso`):** -2 Regresado · -1 Devuelto · 0 Pendiente · 1 Solicitado · 2 Recibido TH · 3 En proceso administrativo · 4 Reportado para contratación · 5 Contrato enviado · 6 Firmado y contratado · 7 Migrado · 8 Renuncia · 9 Cancelado · 10 Inactivo.

**Solicitud administrativa (`EstadoProceso`):** 0 Congelada · 1 Contratado · 2 Inactivo · 3 En selección · 4 Selección de candidato · 5 Verificación · 6 En contratación · 7 Migrado · 8 Renuncia · 9 Cancelado. *(Sub-estado de selección 1–6: Publicación → Recepción/filtro → Entrevistas → Pruebas.)*

**Periodo de prueba:** -1 Rechazado por colaborador · 0 Rechazado · 1 Aprobado · 2 No aprobado · 3 Asignado · 4 Sin asignar · 5 No aplica · 6 No reporta formato · 7 Socializado.

**Aval de honorarios:** 0 Pendiente Jefe · 1 Avalado Jefe · 2 Avalado Sec. Académica · 3 Avalado completo · -1 Rechazado.

**Novedades de contrato:** 0 Pendiente · 1 Recibida · 2 Contrato enviado · 3 Firmado y contratado · 8 Rechazada · 9 Cancelado.

**Solicitudes adicionales:** 0 Rechazado (jefe) · 1 Aprobado (jefe) · 2 Pendiente · 3 Novedad · 4 Rechazado contratación · 5 Aprobado (talento) · 6 Contrato enviado · 7 Firmado y contratado · 8 Aprobado para pago · 9 Rechazado (talento) · 10 No cuenta con par/autor.

**Acta de labor:** 0/1 Pendiente · 2 En cola de envío · 3 Enviada · 4 Aceptada · 9 Rechazada. **Solicitud de ajuste:** 0 Pendiente · 1 Aprobada · 2 Rechazada.

**Inducción:** 0 Pendiente · 1 Asistió · 2 Renunció · 3 Asistió reinducción · 4 No asistió · 5 Pendiente-activo · 6 Asistió-no registro · 7 No asistió-contrato finalizado.

**Perfil de cargo:** Estado 1 Activo / 0 Inactivo / 2 Sin aprobar. Aprobaciones (psicólogo/jefe/director): 1 Aprobado / 0 Rechazado / 2 Pendiente. Socialización del colaborador: 1 Socializado / 2 Sin socializar / 3 Restablecido / 0 blanqueado.

**Colaborador:** 1 Activo · 0 Inactivo · 2 Congelado · 3 Incapacidad-Licencia.

**Dotación:** recibido 0 Sin recibir / 1 Recibido; acta enviada 0 / 1.

**Cumpleaños (envío):** 0 Sin enviar · 1 Enviado.

---

## Apéndice B — Mapa de módulos del menú

| Sección | Módulos |
|---|---|
| **Inicio** | Home, Evaluación 360 (externa), Planta activa, Planta activa académica, Colaboradores antiguos |
| **Configuración** | Roles, Usuarios, Semestres, Porcentajes de labor, Sedes, Áreas, Facultades, Escuelas, Programas, Vicerrectoría, Cardinales/Jerárquicas/Específicas, Periodos, Cecos, Jornadas, Tipos de contrato, Mapa de procesos, Niveles/Descripciones de contribución, Asignaturas, Pensum, Tipos de labor docente, Cargos, Dependencias, Bloqueos, Exámenes médicos, Salarios, Minutas |
| **Generales** | Inducción, Reinducción, Inventario, Cartas, Dotaciones, Encuestas, Perfiles de cargo, Periodos de prueba, Cumpleaños |
| **Académicos** | Calendario académico, Labor docente, Docentes, Asignación (lista/gráfica/consolidada) |
| **Procesos de selección** | Procesos académicos (solicitudes de contratación, avales, NRC, planta autorizada, solicitudes adicionales), Solicitudes de contratación, Procesos administrativos (novedades, cambio de modalidad, aprobaciones, periodo de prueba) |
| **Reportería** | Dotaciones, Perfiles, Administrativos, Académicos, Contratación, Informes, Históricos |
| **Cruces** | Cruce de asignación frente a contratados |

---

## Apéndice C — Observaciones técnicas conocidas

Detectadas durante el levantamiento del código. Se listan como referencia para la entrega; para el detalle de seguridad ver `docs/AUDITORIA_SEGURIDAD_2026-04-23.md`.

- **Credenciales embebidas en código fuente:** claves de API de IA (`app/config/Config.php`) y credenciales/tokens de Adobe Sign (en los controladores de contratación) están *hardcodeados*. Recomendado migrarlos a variables de entorno (`.env`).
- **Controladores satélite con boilerplate:** `PerfilCargoVersions`, `HistoricoColaboradorPerfiles`, `CandidatoSeleccionado` y parte de `ArchivosPerfiles` tienen métodos copiados de otros CRUD que instancian el modelo equivocado (`SedesModel`); la lógica real de versiones/histórico vive dentro de `PerfilCargoController::editAction`.
- **Defectos puntuales verificados:** en la importación de aprobaciones de perfil hay una comparación con `=` en vez de `==` (aprueba siempre); `apruebaPerfilDirectorAction` lee un campo de correo mal escrito; el versionamiento de perfil inserta la copia dos veces por edición.
- **`AvalSolicitudes`:** la ruta GET de `avalJefeAction` invoca un método inexistente (`procesarAval`); el flujo operativo real usa los botones `aprobarAvalJefe`/`rechazarAvalJefe`.
- **Módulo legado:** `ContratacionAdicional` (tabla `contracion_adicional`, con typo) es un CRUD aislado sin flujo de estados; la contratación adicional vigente es `SolicitudesAdicionales`.
- **Depuración residual:** algunos métodos de sincronización de colaboradores terminan en `dd(...)` (volcado de depuración) que interrumpe la ejecución; `aprobarDotacionTemporalAction` está vacío; hay mensajes flash con texto de plantilla ("La sede se creó…") por copy-paste.
- **Estado del repositorio:** al momento de esta documentación, el directorio `app/` figura como eliminado en el árbol de trabajo (working tree) aunque está íntegro en git (`HEAD`); esta documentación se elaboró leyendo el código desde git. Conviene restaurar `app/` (`git restore app/`) o confirmar el estado esperado del branch antes de la entrega.

---

*Documento generado a partir del análisis del código fuente (128 controladores / 146 modelos). Complementa a `docs/ROLES_Y_PERMISOS.md` (matriz detallada de roles) y `docs/AI_MODULE_DEVELOPMENT_GUIDE.md` (guía de desarrollo).*