# 20 — Glosario

> Términos de negocio y de sistema tal como los usa **este** proyecto.
> Muchos son palabras comunes con un significado técnico concreto aquí; confundirlos produce errores.

---

## A

**Acción** — Método público de un controlador con sufijo `Action` (`listAction()`, `aprobarAction()`). Se invoca como `?c=Controlador&a=nombreAccion`. **Debe estar declarada en `loadAccessControl()`** o es inaccesible.

**AccessControl** — Array `accion => nivel` que declara qué acciones existen y con qué nivel de acceso. `'*'` = público, `'@'` = sesión + permiso, ausente = **denegado para todos**.

**Adelanto de nómina** — Anticipo de salario solicitado por un colaborador, sujeto a una política de elegibilidad (`adelanto_politicas`) y descontado después en cuotas.

**Alerta** — Dos cosas distintas: (1) mensaje en pantalla para un rol o usuario (tabla `alertas`); (2) correo encolado para envío (tabla `alertas_email`).

**Asistente IA** — Módulo que traduce preguntas en lenguaje natural a `SELECT` de solo lectura mediante un modelo Ollama local.

**Atributo** — Objeto que representa una columna de un modelo. Se declara en `getOptionsAttributes()` y se instancia como una de las 26 clases de `core/attributes/`. Aporta validación, lectura de `$_POST` y metadatos de formulario.

**Ausencia** — Falta justificada de un colaborador (`asistencia_ausencias`), distinta de las **vacaciones**. Una ausencia aprobada **bloquea la marcación de asistencia** ese día.

---

## B

**Backoffice** — La interfaz administrativa (layout `metronic`), a la que se accede con una cuenta de la tabla `usuarios`. Es la contraparte del **Portal del Colaborador**.

**Beneficio** — Prestación ofrecida a los colaboradores: `subsidio`, `auxilio`, `bono` o `programa`. Tiene reglas de elegibilidad, cupo, presupuesto, vigencia y frecuencia.

**Bitácora** — Tabla de historial de un dominio: `linea_etica_bitacora`, `bitacora_auditoria`. Registra `Accion`, `ValorAnterior`, `ValorNuevo`, `UsuarioId`.

---

## C

**Cargo** — Puesto de trabajo (tabla `cargos`). En el menú aparece como "Cargos Administrativos". Tiene `LiderEquipo` para marcar los que gestionan personal.

**CECO** — Centro de costo (tabla `ceco`). Unidad contable a la que se imputa el colaborador.

**Ciclo** — Subdivisión de un periodo para metas (`metas_ciclos`). **Tabla vacía, sin modelo ni uso.**

**Clases generales** — `Config::$classesGeneral`: módulos que **no requieren permiso**. Contiene `Public`, `Home`, `Ajax`, `Log`, `Login`, `Perfil` y tres residuos de un producto de facturación.

**Colaborador** — Empleado de la empresa (tabla `colaboradores`). **Es la entidad raíz del sistema.** Puede tener credenciales propias para el Portal del Colaborador. **No es lo mismo que un Usuario.**

**Competencia** — Habilidad o comportamiento evaluable (tabla `competencias`). Alimenta la Evaluación 360 y los Planes de Desarrollo.

**Consolidado** — Dos cosas: (1) `metas_consolidado`, la calificación agregada de las metas de un colaborador en un periodo, con `Preliminar` (recalculado) y `Total` (cerrado); (2) `consolidado_evaluacion_360`, el resultado agregado del 360.

**Criteria** — Array PHP que describe una consulta: `['WHERE' => [...], 'ORDER_BY' => [...], 'GROUP_BY' => [...], 'LIMIT' => [...]]`. Lo traduce `MysqlPDO::criteriaToSql()`. 🔴 **No escapa los valores.**

**CRON_TOKEN** — Token compartido del `.env` que autoriza los endpoints de envío programado sin sesión.

---

## D

**dataListAjax** — Acción presente en casi todos los controladores que devuelve el JSON que consume DataTables. 🔴 Está exenta de permisos (`Config::$actionsGeneral`).

**Dependencia** — En el menú, "Dependencias" es el CRUD de la tabla **`areas`**. El término no se refiere a dependencias de software.

**DIR_INDEX** — Constante (`'public'`) que define el destino de las redirecciones cuando falla la autorización.

---

## E

**Embudo de vacante** — Secuencia de etapas específica de una vacante (`etapas_embudo_vacante`), derivada del **pipeline global** pero personalizable. Una postulación **solo puede moverse a etapas de su embudo**.

**Escala** — Conjunto de opciones de calificación de una pregunta de evaluación (`escalas`, con `Opcion0` a `Opcion5`).

**Estado** — 🔴 **Término sobrecargado. Tres significados distintos:**
1. `Estado` `tinyint(1)` = **borrado lógico** (1 activo, 0 eliminado). Filtro global de sesión.
2. `EstadoActual` `varchar` en `colaboradores` = **estado laboral** ("Activo", …).
3. `EstadoMeta`, `EstadoSolicitud`, `EstadoProceso`, `EstadoVacante`, `SlAEstado`… = **estado de negocio** del flujo correspondiente.

**Evaluación 360** — Evaluación multi-fuente: autoevaluación, jefe, colaboradores a cargo, pares y cliente. Cada fuente con peso configurable por periodo.

---

## F

**Festivo** — Día no laborable (tabla `festivos`). Se descuenta del cálculo de días hábiles de vacaciones.

**Filtros de sesión** — `Config::$FILTERS_SESION`. Condiciones (`Estado` y `Periodo`) que `Model::addFiltersSesion()` inyecta **automáticamente** en toda consulta de modelo, como `FIND_IN_SET`. Se desactivan pasando `array()` como tercer argumento. **Causa número 1 de "no aparecen datos".**

**Flash** — Mensaje temporal en sesión (`UserFlash`), mostrado una vez por el layout. Estados: `Success`, `Error`, `Warning`.

---

## H

**HiPo / Alto Potencial** — Colaborador cuyo puntaje consolidado de talento supera el umbral configurable (`TalentScoreService::getUmbralHipo()`). Se marca en `potencial_evaluaciones.EsAltoPotencial`.

---

## J

**Jefe funcional** — Segundo responsable de un colaborador (`colaboradores.IdJefeFuncional`), distinto del **jefe inmediato** (`IdJefeInmediato`). Ambos participan en la aprobación de metas.

---

## K

**Klee** — El framework propietario del proyecto (`core/`). También el nombre de la conexión de base de datos por defecto (`'klee'`) y de la empresa autora (Klee Software).

---

## L

**Layout** — Plantilla HTML envolvente (`app/layouts/`). Los cuatro principales: `metronic` (backoffice), `metronic_public` (portal), `metronic_empty` (login), `impresiones` (imprimible).

**Líder de equipo** — Colaborador con `colaboradores.LiderEquipo = 1`. **No es un rol**: es una bandera que habilita "Mi Equipo" y "Planes del Equipo" en el portal. Se comprueba con `ColaboradoresModel::esLiderEquipo()`.

**Línea de Ética** — Canal de denuncias **anónimo**. El denunciante recibe un código (`ETH-AAAA-NNNNNN`) y un PIN que **solo se muestra una vez** y se almacena hasheado con `password_hash`.

**ListaAjax** — Clase del core que genera tablas DataTables server-side completas (HTML + JavaScript) desde PHP. **Todo listado del sistema la usa.**

---

## M

**Meta** — Objetivo individual de un colaborador en un periodo, con un peso porcentual. **La suma de pesos debe ser exactamente 100 % para aprobar.**

**Mapa de Talento / 9-Box** — Matriz de 3×3 que cruza desempeño y potencial. Las 9 celdas son configurables (`talento_celdas_9box`).

**Modelo** — Clase que extiende `core/Model` y representa una tabla. Declara `$TABLE_NAME`, `$VIEW_NAME` y `getOptionsAttributes()`. ⚠️ En `app/models/` hay también **servicios** con nombre `*Model` que **no** extienden `Model`: `NominaCalculoModel`, `AsistenteIAModel`.

**MODULE_NAME** — Propiedad estática del controlador. Es la **clave en la tabla `permisos`** y el valor de `$this->Module`. ⚠️ `PerfilColaboradorController` comparte `MODULE_NAME='Colaboradores'` con el CRUD administrativo.

---

## N

**Novedad de nómina** — Ajuste puntual de un concepto para un colaborador en un periodo (`nomina_novedades`). Se **suma** al valor calculado por la fórmula.

---

## P

**Periodo** — Ciclo de evaluación (tabla `periodos`, 36 columnas). **Gobierna metas, evaluación 360 y los filtros de sesión.** El periodo activo vive en `$_SESSION[APP_ID]['filtersSesion']['Periodo']`.

⚠️ **No confundir con:** `nomina_periodos` (periodo de nómina) ni `potencial_periodos` (periodo de evaluación de potencial). **Son tres tablas distintas.**

**Permiso** — Fila de `permisos` que asocia un rol con un módulo y un JSON de acciones. **Tres valores por acción:** `0` denegado, `1` permitido, `2` **solo los registros propios** (este último solo lo implementa `ListaAjax`).

**Pipeline** — Secuencia global de etapas de reclutamiento (`reclutamiento_etapas_pipeline`). Etapas con `Codigo` especial: `rechazado`, `contratado`, `oferta`.

**Portal del Colaborador** — La interfaz de autoservicio del empleado (layout `metronic_public`), con login propio contra `colaboradores` y menú `Menu::$public`.

**Postulación** (*application*) — Vínculo entre un candidato y una vacante (`reclutamiento_postulaciones`). Avanza por las etapas del embudo.

---

## Q

**Quick-search** — Buscador de acciones de la barra superior. Endpoint `?c=api&a=quickSearch`, catálogo en `app/config/QuickActionsConfig.php`, filtrado por permisos.

---

## R

**Readiness** — Grado de preparación de un candidato a sucesión (`sucesion_candidatos.Readiness`).

**Reconocimiento** — Mensaje de agradecimiento entre colaboradores, con límite mensual por emisor, aprobación opcional y publicación en un muro.

**Rol** — Perfil de autorización (tabla `roles`). Tres en la base actual: Administrador (1), Analista (2), Colaborador (5). ⚠️ Los colaboradores del portal **siempre** obtienen el rol 5, forzado en código.

**Ruta de carrera** — Secuencia de cargos y etapas por las que puede progresar un colaborador (`carrera_rutas` + `carrera_ruta_etapas`). Versionable.

---

## S

**Semilla** (*seeder*) — Script que inserta datos iniciales. El **prefijo numérico** del fichero fija el orden: `0xx` base, `1xx` módulos, `2xx` demo.

**SLA** — Acuerdo de nivel de servicio de un ticket. Definido por prioridad en `servicio_sla_politicas` (`MinutosPrimeraRespuesta`, `MinutosResolucion`). El estado (`SlAEstado`, con esa mayúscula intercalada) es `en_tiempo` o `vencido`.

**Sucesión** — Preparación de reemplazos para puestos críticos (`sucesion_puestos_clave` → `sucesion_planes` → `sucesion_candidatos`).

---

## T

**Ticket** — Solicitud de servicio interno del colaborador (`servicio_tickets`). En el menú aparece como "Tickets / Solicitudes".

**Turno** — Horario de trabajo asignable (`asistencia_turnos`), con tolerancias de entrada y salida y bandera de cruce de medianoche.

---

## U

**Usuario** — Cuenta del **backoffice** (tabla `usuarios`). **No es lo mismo que un Colaborador**, que tiene su propia tabla y su propio login. Un colaborador puede no tener cuenta de usuario, y viceversa.

⚠️ **`getUserAccess()` devuelve `1`**: el usuario con `usuarios.Id = 1` tiene acceso total incondicional.

---

## V

**Vacante** — Puesto abierto en reclutamiento (`reclutamiento_vacantes`), con cupos, embudo y reglas de filtro.

**Ventana de metas** — Estado temporal derivado de las fechas del periodo:
`pendiente_apertura` → `planeacion` (se pueden crear y editar metas) → `seguimiento` (se registran avances) → `cerrado`.
Si faltan las fechas, el estado es `no_definido`, que **permite todo**.

**Vista** — Dos cosas distintas:
1. **Vista SQL** (`vista_*`, 62 en la base): lo que leen los modelos a través de `$VIEW_NAME`.
2. **Vista PHP** (`app/views/**/*.php`, 291): la plantilla que renderiza el HTML.

---

## Términos peligrosamente ambiguos

| Término | Significados posibles | Cómo distinguirlos |
|---|---|---|
| **Estado** | Borrado lógico · Estado laboral · Estado de flujo | Por el nombre de la columna: `Estado` (0/1), `EstadoActual` (texto), `Estado{Algo}` (flujo) |
| **Periodo** | Periodo de evaluación · Periodo de nómina · Periodo de potencial | Tres tablas distintas: `periodos`, `nomina_periodos`, `potencial_periodos` |
| **Usuario** | Cuenta del backoffice · Persona en general | La tabla `usuarios` es solo el backoffice |
| **Vista** | Vista SQL · Vista PHP | Prefijo `vista_` vs carpeta `app/views/` |
| **Modelo** | Clase que extiende `Model` · Servicio con nombre `*Model` | `NominaCalculoModel` y `AsistenteIAModel` **no** extienden `Model` |
| **Dependencia** | Tabla `areas` (en el menú) · Dependencia de software | Por el contexto |
| **Cargo** | Tabla `cargos` · Columna `usuarios.Cargo` (varchar, sin FK) | |
| **Sede** | Tabla `sedes` · Columna `usuarios.Sede` (varchar, sin FK) | |
| **Programa** | `beneficios_catalogo_programas` · `ProgramasModel` (**clase inexistente**, legado docente) | |
| **Application** | Postulación de reclutamiento (`RecruitmentApplicationsModel`) | Nunca significa "aplicación" en el sentido de software |
| **Módulo** | Módulo funcional · `permisos.ModuleName` · `Controller::$MODULE_NAME` | Los tres coinciden, pero `PerfilColaborador` comparte módulo con `Colaboradores` |

---

## Abreviaturas

| Sigla | Significado |
|---|---|
| **CECO** | Centro de costo |
| **HiPo** | High Potential — Alto Potencial |
| **LMS** | Learning Management System — el módulo de Capacitación |
| **9-Box** | Matriz de 3×3 de desempeño × potencial |
| **SLA** | Service Level Agreement |
| **PDI** | Plan de Desarrollo Individual |
| **ADM / ANA / COL** | Códigos de rol: Administrador / Analista / Colaborador |
| **ETH-AAAA-NNNNNN** | Formato del código de caso de la Línea de Ética |
| **HR-0XX** | Identificador de hallazgo de la auditoría de seguridad |

---

## Convenciones de estado en el código

| Dominio | Constantes |
|---|---|
| **Metas** | `borrador` · `en_revision` · `aprobada` · `rechazada` · `cerrada` |
| **Vacaciones** | `SOLICITADA` · `APROBADA` · `RECHAZADA` · `CANCELADA` *(en MAYÚSCULAS)* |
| **Beneficios (catálogo)** | `borrador` · `activo` · `inactivo` · `archivado` |
| **Beneficios (solicitud)** | `creada` · `en_revision` · `aprobada` · `rechazada` · `entregada` · `cancelada` |
| **Adelantos** | `creada` · `en_revision` · `aprobada` · `rechazada` · `desembolsada` · `en_descuento` · `descontada` · `cancelada` |
| **Tickets** | `nuevo` · `asignado` · `en_progreso` · `en_espera` · `resuelto` · `cerrado` · `reabierto` |
| **Línea de ética** | `recibido` · `en_revision` · `en_investigacion` · `en_espera` · `cerrado` · `archivado` |
| **Capacitación** | `asignado` · `en_progreso` · `completado` · `vencido` · `cancelado` |
| **Asistencia** | `pendiente` · `completo` · `inconsistente` · `ausente` · `vacaciones` · `incapacidad` · `permiso` |
| **Postulación** | `nueva` · `en_proceso` · `oferta` · `rechazada` · `retirada` · `contratada` |
| **SLA** | `en_tiempo` · `vencido` |
| **Prioridad** (tickets y ética) | `baja` · `media` · `alta` · `critica` |

> Todos en minúscula `snake_case`, **salvo vacaciones**, que usa MAYÚSCULAS.

---

## Documentos relacionados
- [04_MODULES.md](04_MODULES.md)
- [05_DATABASE.md](05_DATABASE.md)
- [10_BUSINESS_LOGIC.md](10_BUSINESS_LOGIC.md)