# Auditoría funcional y de potencial analítico — Timeklee2 > **Naturaleza del documento.** Auditoría de negocio, datos y analítica de la plataforma de reservas de espacios/equipos y acceso remoto Timeklee2, realizada como consultoría senior en analítica, BI, UX y arquitectura para instituciones de educación superior. > > **Fecha del levantamiento:** 3 de agosto de 2026. > **Alcance:** código completo (37 controladores, 37 modelos, 9 servicios, 45 módulos registrados, 14 comandos CLI, 27 migraciones, 23 seeders), esquema de las tres bases de datos vivas (`timeklee2`, `guacamole_db`, `timeklee_tadeo`) y datos reales de producción de la generación anterior (2022–2025). > **No se modificó ninguna línea de código ni ningún dato.** Este documento y sus anexos son el único artefacto producido. --- ## Índice del documento | Parte | Archivo | Contenido | |---|---|---| | **0** | Este archivo | Resumen ejecutivo, veredicto de madurez, hallazgos críticos, cómo leer la auditoría | | **1** | [01_MAPA_FUNCIONAL.md](01_MAPA_FUNCIONAL.md) | FASE 1 — Qué hace el sistema: modelo de negocio, 45 módulos, los 7 flujos completos (autenticación, reserva, aprobación, préstamo, práctica libre, escritorio remoto, sanción), interacciones entre módulos | | **2** | [02_INVENTARIO_DATOS.md](02_INVENTARIO_DATOS.md) | FASE 2 — Qué información almacena: ficha de las 32 tablas + 4 vistas, esquema Guacamole, modelo dimensional propuesto, 16 defectos de calidad de dato, arqueología de la producción anterior | | **3** | [03_AUDITORIA_REPORTES.md](03_AUDITORIA_REPORTES.md) | FASE 3 — Auditoría crítica de los 16 reportes Excel, 4 dashboards y las pantallas de inicio e historial existentes (26 artefactos), con nota de utilidad 1–10 y veredicto | | **4** | [04_DASHBOARDS.md](04_DASHBOARDS.md) | FASE 4 — Diseño de los 30 dashboards solicitados + 8 de escritorio remoto (que cubren las 13 métricas pedidas) + 8 potenciados con IA. Ficha completa por dashboard | | **5** | [05_OPORTUNIDADES.md](05_OPORTUNIDADES.md) | FASE 5 — Oportunidades de producto por rol directivo (Rector, Director TIC, Infraestructura, Coordinador de Laboratorios, Decano, Director Académico, Financiero) | | **6** | [06_CATALOGO_KPIS.md](06_CATALOGO_KPIS.md) | Catálogo consolidado de **147 indicadores** con fórmula, fuente exacta y semáforo de factibilidad | | **7** | [07_BRECHAS_Y_HABILITADORES.md](07_BRECHAS_Y_HABILITADORES.md) | Semáforo de factibilidad por dominio, eventos de negocio no registrados, arquitectura de la capa analítica recomendada, riesgos | --- ## 1. Qué es Timeklee2, en una página Timeklee2 es una **plataforma de gestión de recursos universitarios compartidos** con dos caras: 1. **Un motor de reservas y préstamos** que gobierna todo lo que una universidad presta o agenda: aulas de cómputo, aulas móviles, salas de juntas, salas de tutorías, auditorios, espacios abiertos, casilleros, portátiles y equipos individuales. Cinco canales de entrada conviven sobre el mismo modelo de datos: autoservicio del estudiante en el portal, mostrador administrativo, creación rápida desde el calendario, préstamo inmediato *walk-in* y práctica libre autogestionada. 2. **Una consola de acceso remoto** construida sobre Apache Guacamole, que permite al estudiante usar el computador físico de un laboratorio desde su casa, dentro de la ventana horaria de su reserva. Es el diferenciador comercial del producto y el sustituto industrial del `AnyDesk` artesanal que usaba la generación anterior. Alrededor de esos dos núcleos hay: un catálogo de oferta con políticas por espacio (~70 parámetros por agenda), un motor de aprobación configurable, un sistema de sanciones automáticas por inasistencia, una cola de correo transaccional, un asistente conversacional con IA (Ollama/Groq con *tool calling*) que ya consulta y propone escrituras sobre las reservas, y un módulo de reportes con 16 reportes Excel y 4 dashboards. **La propuesta de valor real para una universidad**, tal como está construida: *«convierto un inventario de espacios y equipos disperso, gobernado por correos y hojas de cálculo, en un servicio con reglas, trazabilidad y acceso remoto — y sé qué se usa, quién lo usa y cuánto se desperdicia.»* La primera mitad de esa frase está construida. **La segunda mitad es exactamente lo que esta auditoría viene a evaluar.** --- ## 2. Veredicto de madurez analítica Sobre una escala de cinco niveles: | Nivel | Definición | ¿Timeklee2? | |---|---|---| | 1. **Operativo** | El sistema registra transacciones; consultarlas requiere abrir listados | Superado | | 2. **Descriptivo básico** | Existen conteos y listados exportables por rango de fechas | **Superado con holgura** | | 3. **Descriptivo completo** | Existen tasas, tendencias, comparativas contra periodo anterior, heatmaps y ranking de sobre/subutilización | **← AQUÍ ESTÁ, con defectos graves de exactitud** | | 4. **Diagnóstico** | El sistema explica *por qué*: denominadores de capacidad, demanda insatisfecha, causas tipificadas, drill-down hasta el hecho | No alcanzado | | 5. **Predictivo / prescriptivo** | El sistema anticipa y recomienda: predicción de demanda y de no-show, recomendación de apertura, redistribución de equipos | No alcanzado | **Nota media de los 26 artefactos analíticos existentes: 4,3 / 10.** La conclusión no es «falta analítica». Es más incómoda y más útil: **la plataforma ya tiene una capa analítica de nivel 3 razonablemente ambiciosa (1.298 líneas en `ReportesModel`, 378 en `GraficasModel`, 16 reportes catalogados con código, 4 dashboards con heatmap y embudo), pero está construida sobre cuatro supuestos que los datos no cumplen. El resultado es un sistema que responde con números precisos a preguntas mal planteadas.** Corregir esos cuatro supuestos vale más que construir veinte dashboards nuevos, y es la precondición para que los veinte nuevos no repitan el error. --- ## 3. Los seis hallazgos que condicionan todo lo demás ### H1. La tasa de cancelación reporta cero. Estructuralmente. El flujo de cancelación **borra físicamente la fila de `citas`** y la inserta en `citas_canceladas` ([CitasController.php:1771](../../app/controllers/CitasController.php#L1771)). Pero **los cinco KPIs oficiales de cancelación cuentan `citas.Estado = 2`**: [GraficasModel::getKpis](../../app/models/GraficasModel.php#L52) (`tasa_cancelacion`), [ReportesModel::getKpisGlobal](../../app/models/ReportesModel.php#L1147), `getEficienciaPorSede`, `getReservasResumenEspacio`, `getReservasResumenFecha`. Ese estado es **inalcanzable por el flujo normal**: sólo lo dejan la cancelación de series recurrentes y los seeders. Verificado en la base viva: `citas.Estado=2` → 3 filas (todas de seeder); `citas_canceladas` → 1 fila. En producción, la tasa de cancelación que verá un decano en el reporte ADV002 **tenderá a 0 % mientras las cancelaciones reales se acumulan en una tabla que ningún KPI lee**. En la generación anterior, la tasa real medible fue del **12,6 %**. > Es el defecto de reporting más grave del sistema. Un rector puede tomar decisiones de inversión con una tasa de cancelación de 0 % que en realidad es del 12 %. ### H2. No existe el denominador de la ocupación. Todos los reportes y dashboards de «ocupación» calculan **sólo el numerador**: horas reservadas. El denominador —horas ofertadas— vive exclusivamente dentro de **ocho columnas `mediumtext` con JSON** (`agendas.HorarioTotal` + `HorarioLunes..HorarioDomingo`), no consultables por SQL. No hay tabla de franjas, no hay tabla de calendario, y `festivos` sólo tiene 13 filas, todas de 2026. Consecuencia: **el KPI que toda universidad compra primero — «¿qué porcentaje de mi capacidad estoy usando?» — hoy no es calculable.** Lo que existe es un conteo relativo entre espacios, que responde «cuál se usa más», no «cuánto se desperdicia». Y en la generación anterior el problema era peor: de 1.396 agendas configuradas, sólo **405 (29 %)** tuvieron alguna reserva. ### H3. La dimensión académica no existe. - `areas_universitarias`: **0 filas**, y `agendas.IdAreaUni` contiene los códigos `1101–1108` de `agendas_categoria`, no ids de área. Verificado: **16 de 16 agendas quedan huérfanas** en el join. El gráfico «Reservas por área» devuelve `Sin área` para el 100 % de las reservas. - `clientes.Programa` es `varchar(180)` de **texto libre**, sin catálogo, y mezcla tres semánticas distintas (programa académico, cargo de monitoría, dependencia administrativa). Con 20 clientes ya hay 19 valores distintos. - **Facultad, semestre y asignatura no existen** en ninguna tabla. Consecuencia directa sobre lo solicitado: **los dashboards 8 (por facultades), 9 (por programas), 21 (uso por estudiante), 22 (uso por docente) y 23 (uso por dependencia) no son construibles hoy de forma defendible.** No es una limitación de visualización: es ausencia de la dimensión. La ruta para cerrarlo está especificada en la Parte 7 y es trabajo de días, no de meses. ### H4. La cadena espacio → equipo → conexión remota → reserva → persona está rota en tres puntos. 1. **Dos inventarios paralelos y desconectados.** `agendas_recursos` (59 filas — los PCs del laboratorio, con `CodigoGuacamole`) y `activos` (**0 filas** — el inventario patrimonial con serial y valor). No hay ninguna columna, FK ni vista que los una. El módulo que factura la operación diaria (préstamos inmediatos) nunca toca `activos`. 2. **El puente a Guacamole cubre el 6,8 % del parque.** De 59 recursos, 8 tienen `CodigoGuacamole` y **4 de ellos son inválidos** (el literal `client:PI-PC-05` no es un identificador de Guacamole). Además la llave es base64 opaco, imposible de usar en un JOIN. 3. **Todos los usuarios navegan con la cuenta de servicio compartida `guacadmin`.** Por tanto `guacamole_connection_history.username` **siempre valdrá `guacadmin`** y la atribución persona↔sesión se pierde en origen. El «top usuarios» del dashboard remoto mostrará una única barra. Consecuencia: **el KPI más vendible del módulo remoto — horas de escritorio remoto por estudiante y por programa — hoy es imposible.** Y `guacamole_connection_history` tiene **0 filas**, con el servidor Guacamole configurado (`192.168.31.197`) inalcanzable: el diferenciador comercial es hoy indemostrable en vivo. ### H5. El sistema está funcionalmente congelado: no hay cron. `crontab -l` → vacío. No hay systemd timers, ni scheduler, ni CI programado. Los workers críticos (`expire-citas`, `email-queue`, `waitlist`) existen, están bien construidos y **nadie los ejecuta**. Evidencia dura en la base: **19 correos llevan meses en estado «por enviar»**, y `alertas_email` no tiene una sola fila enviada. Esto tiene un efecto analítico devastador y poco obvio: **el estado `4 = No asistió` sólo lo genera el cron**. Sin cron, la tasa de no-show —el KPI más sólido del sistema— mide un fenómeno que nunca se materializa. Igual la expiración de pendientes y las sanciones automáticas. > Tres líneas de crontab son la intervención de mayor retorno por esfuerzo en toda la plataforma. ### H6. Se perdieron los procesos que sí generaban valor medible. La base de producción de la generación anterior (`timeklee_tadeo`, datos reales 2022–2025) documenta procesos que **desaparecieron** en Timeklee2: | Proceso perdido | Volumen real | KPI que se llevó consigo | |---|---|---| | **Órdenes de salida** de bienes del campus | 2.559 órdenes con doble firma | **50,1 % de devolución tardía**, con retraso medio de **33 horas** | | **Sanción automática por devolución tardía** | 903 de 1.243 bloqueos (72,6 %) | El único mecanismo probado de disciplina de devolución | | **Estructura física** edificios → salones → equipos | 21 edificios, 46 salones (858 puestos), 764 equipos | Ocupación por módulo del campus y % de aforo utilizado | | **Uso real vs. agendado** (`InicioDesarrollada`/`FinDesarrollada`) | — | Horas realmente usadas frente a horas reservadas | | **Catálogo de programas** con facultad | 3 filas (parcial ya entonces) | Jerarquía programa → facultad | Y un dato que debería estar en la primera diapositiva de cualquier propuesta: en la generación anterior, **10 equipos de 764 concentraron el 80 % de los préstamos**. La asignación no se balanceaba: se entregaba siempre el mismo portátil hasta que moría. Ese hallazgo, por sí solo, justifica un dashboard de redistribución de equipos. --- ## 4. Lo que sí está bien construido (y es el activo a apalancar) Ser justo con el sistema es parte de la auditoría: - **`vista_citas` es una capa semántica embrionaria de buena calidad**: resuelve agenda, sede, recurso, activo y traduce los estados a texto. Es el mejor punto de partida de BI que existe hoy, y ya es la fuente única del asistente IA, los reportes y los dashboards. - **El control de concurrencia de reservas es de nivel profesional**: pre-validación optimista, verificación pesimista con `SELECT ... FOR UPDATE` dentro de transacción, e índices compuestos anti-solape (`idx_citas_overlap_agenda`, `idx_citas_overlap_activo`). Los datos de reserva son confiables en lo que respecta a overbooking. - **`ReportesController` tiene un catálogo formal de reportes con código, título, descripción y filtros declarados** (RES001…ADV004) y despacho dinámico. Es una arquitectura de reporting correcta, sólo mal alimentada. - **`GuacHistorialStats` es el modelo a imitar**: 11 funciones puras, deterministas, sin dependencias de red ni de BD. Es exactamente cómo debe construirse una capa de cálculo analítico. - **El asistente IA ya funciona end-to-end** con dos proveedores, 10 herramientas, *tool calling*, patrón propuesta→confirmación humana con revalidación de estado, y trazabilidad de tokens. Es la única pieza de IA operativa y es una base sólida para las alertas inteligentes y los dashboards conversacionales. - **`GuacdProbe` es una joya oculta**: no es un ping, es el handshake completo del protocolo `guacd` con 12 códigos de error traducidos a lenguaje de negocio («No se encontró el equipo: revisa si está encendido»). Está construido, funciona, **y no tiene ni un botón en la interfaz ni una tabla donde persistir**. Con una tabla y un cron se convierte en el dashboard de disponibilidad de equipos. - **`core/Cache.php`** (APCu con *fallback* a ficheros, con *namespaces* para invalidación) está construido, probado y **prácticamente sin usar**. Es la infraestructura de precálculo que hace falta. --- ## 5. Cómo leer esta auditoría Tres convenciones se aplican en todo el documento: 1. **Semáforo de factibilidad.** Cada KPI y cada dashboard lleva una marca: - 🟢 **VERDE** — calculable hoy con el dato existente. - 🟡 **AMARILLO** — calculable con transformación, o con dato parcial/sucio que exige advertencia explícita al usuario. - 🔴 **ROJO** — requiere capturar dato nuevo. Se especifica siempre *qué* dato y *dónde* se dispararía. 2. **Nada se afirma sin evidencia.** Cada hallazgo cita archivo y línea, o la consulta SQL ejecutada contra la base viva. Los números de producción provienen de `timeklee_tadeo` y se marcan como tales. 3. **Se distingue «no existe» de «existe y no se usa».** La diferencia decide el esfuerzo: poblar una tabla vacía es un día; construir un módulo de mantenimiento es un trimestre. En la Parte 7 hay un inventario explícito de las **siete tablas con esquema listo y cero filas**, que son la fruta más baja del árbol. --- ## 6. Resumen de la propuesta analítica | | Cantidad | |---|---| | Indicadores catalogados | **147** (Parte 6) | | — de ellos calculables hoy (🟢) | 39 | | — calculables con transformación (🟡) | 48 | | — que requieren instrumentación nueva (🔴) | 60 | | Dashboards diseñados | **46** (30 solicitados + 8 de escritorio remoto que cubren las 13 métricas pedidas + 8 con IA) | | Eventos de negocio hoy no registrados que hay que capturar | **14** (Parte 7) | | Tablas con esquema listo y 0 filas (habilitación = poblar) | **7** | | Defectos de calidad de dato documentados | **16** | | Tablas/procesos de la generación anterior recuperables | **17** | **El orden correcto de trabajo no es el orden de la lista de dashboards.** Los cinco habilitadores de la Parte 7 (cron, dimensión tiempo, dimensión académica, tabla de capacidad ofertada, tabla puente equipo↔conexión) desbloquean por sí solos 41 de los 60 indicadores en rojo. Construir dashboards antes de eso produce pantallas bonitas que mienten — exactamente el problema que esta auditoría documenta en la Parte 3. --- *Al final de la Parte 7 hay una sección de siguientes pasos. El plan de implementación detallado, tal como se acordó, se abordará una vez validada esta auditoría.*