Universidad Politécnica Territorial del Estado Lara "Andrés Eloy Blanco" (UPTAEB)
DIRPOLES-4 es el Sistema de Gestión Administrativa para la Dirección de Políticas Estudiantiles (DIRPOLES) de la Universidad Politécnica Territorial del Estado Lara "Andrés Eloy Blanco" (UPTAEB). Desarrollado como un monolito modular híbrido en PHP 8.2+ / 8.3 con MVC propio (sin frameworks comerciales), sirve páginas HTML renderizadas en el servidor (Puerta HTML) y una API RESTful JSON estricta (Puerta JSON) desacoplada para consumo web y preparado para servicios de Inteligencia Artificial (FastAPI).
Este repositorio constituye la versión final refactorizada, segura e inmutable del sistema, abarcando la automatización integral de 18 módulos funcionales, clínicos, logísticos y administrativos. Es 100% compatible tanto con Windows (XAMPP 8.2.12+) como con Linux (PHP 8.3+).
Proyecto Socio-Integrador y Tecnológico (PSIT) — Trabajo Especial de Grado para la obtención del título de Ingeniero(a) en Informática (Trayecto IV, PNF Informática, UPTAEB).
- ✨ Características Principales
- 🧱 Stack Tecnológico
- 🏛 Arquitectura del Sistema
- 📋 Requisitos de Infraestructura
- 🚀 Instalación y Despliegue
- 🔑 Gestión de Credenciales Iniciales
- ✅ Verificación del Despliegue
- ⚙ Variables de Entorno (.env)
- 🗂 Estructura del Código Fuente
- 🧩 Módulos del Sistema (18/18 Operativos)
- 🔐 Marco de Seguridad Defensiva
- 📚 Documentación Técnica
- 🛠 Solución de Problemas Frecuentes
- 📄 Licencia y Propiedad Intelectual
- Criptografía Asimétrica y Autenticación Defensiva:
- Cifrado en tránsito asimétrico con RSA-2048 (PKCS#1) en cliente → descifrado seguro en servidor → almacenamiento con hash Bcrypt (cost factor 10).
- Tokens JWT RS256 en cookie
HttpOnly+ Refresh Tokens con rotación de un solo uso (one-time use) con digest SHA-256 en base de datos. - Protección Anti-Fuerza Bruta Persistente en BD (
login_intentos) con bloqueo automático a los 3 intentos fallidos.
- Doble Base de Datos Aislada:
dirpoles_security: Autenticación, matriz RBAC, auditoría forense (bitacora), tokens y notificaciones.dirpoles_business: Expedientes clínicos, beneficiarios, inventario médico, jornadas, transporte y becas.
- Concurrencia e Integridad Transaccional:
- Bloqueo pesimista nivel de fila (
SELECT ... FOR UPDATE) en descuento de insumos médicos y control de aforo masivo en jornadas. - Kardex de movimientos transaccionales en tiempo real para inventario médico, mobiliario y flota de transporte.
- Bloqueo pesimista nivel de fila (
- Autorización Atómica RBAC: Matriz dinámica (Roles × Módulos × Permisos:
crear,leer,editar,eliminar). - Streaming SSE: Canal bidireccional asíncrono (Server-Sent Events) para la campana de notificaciones del topbar sin bloqueo de sesión (
session_write_close()). - Analítica y Reportes: 10 tableros estadísticos dinámicos con filtrado server-side en whitelist, gráficos Chart.js v2.9.4 local y exportación a PDF y Excel.
| Capa / Componente | Tecnología / Estándar |
|---|---|
| Lenguaje Backend | PHP 8.2+ / 8.3 (Compatible con XAMPP 8.2.12+ en Windows y PHP 8.3+ en Linux; MVC propio modular nativo) |
| Bases de Datos | MySQL 8.0+ / MariaDB 10.4+ (Dos esquemas aislados: dirpoles_security y dirpoles_business) |
| Servidor Web | Apache 2.4+ con módulo mod_rewrite activo |
| Dependencias PHP | Composer 2.x · firebase/php-jwt · vlucas/phpdotenv |
| Frontend & UI | HTML5 + Vanilla JS Modular + Bootstrap 5 (SB Admin 2) |
| Librerías Frontend Local | DataTables, Select2, SweetAlert2, Driver.js, FullCalendar, Chart.js v2.9.4 local |
| Seguridad / Criptografía | RSA-2048 (OpenSSL) · Bcrypt · JWT RS256 · SHA-256 |
DIRPOLES-4 opera bajo el patrón Monolito Modular con Front Controller Híbrido (Regla de las Dos Puertas):
Navegador ──▶ .htaccess ──▶ index.php (Front Controller)
│
├─ RateLimitMiddleware (Token Bucket por IP/Endpoint)
├─ SessionAuthMiddleware (Sesión PHP + Validación JWT RS256)
└─ Router ──▶ Controlador Funcional ──▶ Modelo (SQL PDO)
└──▶ Respuesta (JSON / HTML)
| Puerta / Canal | Identificador | Tipo de Respuesta | Propósito |
|---|---|---|---|
| Puerta HTML | Rutas estándar (ej: medicina/consultar) |
Renderizado HTML Server-Side (SSR) | Navegación entre vistas y plantillas del sistema. |
| Puerta JSON | Rutas bajo api/ (ej: api/medicina/listar) |
JSON con Contrato Único ({exito: bool, datos/error}) |
Operaciones asíncronas AJAX, DataTables y API. |
| Streaming SSE | sse/notificaciones |
text/event-stream |
Eventos y alertas en tiempo real en la barra superior. |
| Tercera Puerta | Endpoints binarios (ej: respaldo/descargar) |
Stream application/octet-stream o PDF |
Descarga de respaldos .sql e informes FPDF. |
| Requisito | Versión Soportada | Extensión / Módulo Requerido |
|---|---|---|
| Servidor PHP | 8.2+ o 8.3+ (ej. XAMPP 8.2.12+ en Windows o PHP 8.3+ en Linux) | openssl, pdo_mysql, mbstring, fileinfo, json |
| Motor MySQL / MariaDB | 8.0+ / 10.4+ | Motor InnoDB con soporte de transacciones ACID y FOR UPDATE |
| Servidor Web | Apache 2.4+ | mod_rewrite e AllowOverride All habilitados |
| Gestor de Paquetes | Composer 2.x | Para autoloader PSR-4 y dependencias de producción |
| Herramientas de Criptografía | PHP CLI / OpenSSL | Para generación de pares de claves RSA-2048 (script multiplataforma incluido) |
Important
Compatibilidad Nativa Total (Windows con XAMPP 8.2.12+ y Linux con PHP 8.3+):
El sistema fue concebido bajo estándares de PHP 8.2+ y las dependencias de desarrollo del repositorio fueron ajustadas a PHPUnit 11 (compatible nativamente con PHP >= 8.2).
De este modo, la instalación estándar mediante composer install (o composer install --no-dev para entornos de producción) funciona directamente y sin advertencias ni bloqueos de versión tanto en Windows (XAMPP 8.2.12+) como en Linux (PHP 8.3+).
Si utilizas Windows con XAMPP (incluso con PHP 8.2.12), el repositorio cuenta con el script automatizado setup_windows.bat:
-
Abre tu terminal (CMD, PowerShell o Git Bash) y clona el repositorio dentro de la carpeta
htdocsde XAMPP:cd C:\xampp\htdocs git clone https://github.com/mroberth/DIRPOLES-4.git DIRPOLES-4 cd DIRPOLES-4
-
Ejecuta el archivo por lotes (o haz doble clic sobre él en el Explorador de Archivos):
setup_windows.bat
El script se encargará automáticamente de:
- Crear el archivo
.envconfigurado para XAMPP (rootsin contraseña). - Crear los directorios
logs/,uploads/yapp/Config/Keys/. - Generar las 4 llaves RSA-2048 (
loginyjwt) mediante el generador PHP incluido. - Verificar PHP y las extensiones
openssl,pdo_mysql,mbstringyfileinfo. - Instalar las dependencias mediante Composer.
- Detectar los dumps SQL actualizados y mostrar los comandos de importación.
Por seguridad, el instalador no importa automáticamente las bases de datos: los dumps contienen
DROP TABLEy pueden reemplazar datos existentes. Después de confirmar que MySQL está iniciado y revisar los archivos, importa en CMD:C:\xampp\mysql\bin\mysql.exe -u root -p < docs\bd\dirpoles_security_actualizada.sql C:\xampp\mysql\bin\mysql.exe -u root -p < docs\bd\dirpoles_business_actualizada.sql
En una instalación XAMPP nueva, puedes omitir
-psirootno tiene contraseña. Como alternativa, puedes solicitar la importación explícita ejecutando:setup_windows.bat --import-databases
- Crear el archivo
-
Inicia Apache y MySQL desde el Panel de Control de XAMPP.
-
Accede en tu navegador a:
http://localhost/DIRPOLES-4
Para Debian, Ubuntu o Linux Mint con Apache, PHP 8.3+ y MariaDB/MySQL:
git clone https://github.com/mroberth/DIRPOLES-4.git DIRPOLES-4
cd DIRPOLES-4
chmod +x setup_linux.sh
./setup_linux.shEl script ejecuta automáticamente:
- Creación del archivo de configuración Apache Alias (
/DIRPOLES-4). - Generación del archivo
.enva partir de.env.example. - Verificación de PHP, Composer, OpenSSL, MySQL y las extensiones requeridas.
- Generación criptográfica de las llaves RSA de 2048 bits para Login y JWT en
app/Config/Keys/. - Creación de directorios de almacenamiento (
logs/,uploads/) con permisos restringidos. - Instalación de dependencias de PHP vía Composer.
- Verificación de los dumps SQL actualizados.
La importación SQL se ejecuta únicamente cuando se solicita explícitamente, porque
los dumps contienen DROP TABLE:
MYSQL_USER=root MYSQL_PASSWORD='tu_clave' ./setup_linux.sh --import-databasesSi la cuenta no tiene contraseña, puede omitirse MYSQL_PASSWORD. También puedes
ejecutar el instalador sin --import-databases y seguir el paso manual:
mysql -u root -p < docs/bd/dirpoles_security_actualizada.sql
mysql -u root -p < docs/bd/dirpoles_business_actualizada.sql- Reinicio del servicio Apache.
Acceso inmediato en: http://localhost/DIRPOLES-4
Si prefieres realizar la instalación manualmente en Windows con XAMPP:
Clona el repositorio dentro del directorio raíz web de XAMPP (htdocs):
cd C:\xampp\htdocs
git clone https://github.com/mroberth/DIRPOLES-4.git DIRPOLES-4
cd DIRPOLES-4Abre el archivo de configuración C:\xampp\php\php.ini (o desde el Panel de XAMPP haz clic en el botón Config junto a Apache y selecciona PHP (php.ini)).
Verifica y descomenta (elimina el punto y coma ; inicial) las siguientes extensiones:
extension=fileinfo ; <-- VITAL: viene desactivada por defecto en XAMPP y es requerida para validar uploads/fotos
extension=openssl
extension=pdo_mysql
extension=mbstringGuarda los cambios y reinicia Apache en XAMPP.
Copia la plantilla de entorno:
copy .env.example .envEn XAMPP, el usuario por defecto de MySQL es root sin contraseña. Tu .env debe quedar con:
DB_HOST=localhost
DB_NAME=dirpoles_business
DB_USER=root
DB_PASS=
DB_SECURITY_NAME=dirpoles_security
DB_SECURITY_USER=root
DB_SECURITY_PASS=DIRPOLES-4 incluye un generador PHP nativo que no requiere instalar herramientas externas:
php scripts/generar_llaves.php(Alternativamente, si usas Git Bash, puedes generarlas con OpenSSL CLI: openssl genrsa -out app/Config/Keys/login_private.pem 2048, etc.).
Gracias a que las dependencias de desarrollo están fijadas en PHPUnit 11 (compatible con PHP >= 8.2), puedes ejecutar la instalación estándar directamente:
composer installTip
Si vas a desplegar en un servidor de producción o deseas una instalación más ligera y rápida omitiendo librerías de pruebas, puedes usar composer install --no-dev. Ambas variantes funcionarán perfectamente en PHP 8.2 y 8.3.
Puedes importarlas de dos formas:
- Vía phpMyAdmin: Entra en
http://localhost/phpmyadmin, crea o importa directamente los scripts:docs\bd\dirpoles_security_actualizada.sqldocs\bd\dirpoles_business_actualizada.sql
- Vía Línea de Comandos (CMD):
C:\xampp\mysql\bin\mysql.exe -u root -p < docs\bd\dirpoles_security_actualizada.sql C:\xampp\mysql\bin\mysql.exe -u root -p < docs\bd\dirpoles_business_actualizada.sql
Asegúrate de que existan las carpetas para logs y subida de archivos:
if not exist logs mkdir logs
if not exist uploads mkdir uploadsInicia Apache y MySQL desde el Panel de Control de XAMPP y visita:
http://localhost/DIRPOLES-4
git clone https://github.com/mroberth/DIRPOLES-4.git DIRPOLES-4
cd DIRPOLES-4cp .env.example .envAjusta credenciales de base de datos en .env.
composer install --no-devphp scripts/generar_llaves.php(O usando OpenSSL CLI):
mkdir -p app/Config/Keys
openssl genrsa -out app/Config/Keys/login_private.pem 2048
openssl rsa -in app/Config/Keys/login_private.pem -pubout -out app/Config/Keys/login_public.pem
openssl genrsa -out app/Config/Keys/jwt_private.pem 2048
openssl rsa -in app/Config/Keys/jwt_private.pem -pubout -out app/Config/Keys/jwt_public.pem
chmod 600 app/Config/Keys/*_private.pem
chmod 644 app/Config/Keys/*_public.pemmysql -u root -p < docs/bd/dirpoles_security_actualizada.sql
mysql -u root -p < docs/bd/dirpoles_business_actualizada.sqlmkdir -p logs uploads
sudo chown -R "$USER:www-data" logs uploads
sudo chmod 750 logs uploadsEl esquema inicial incluye usuarios administrativos pre-configurados. Las contraseñas están resguardadas con hash Bcrypt. Para establecer una contraseña conocida para pruebas o administración:
# 1) Genera el hash Bcrypt de tu nueva contraseña desde la terminal:
php -r "echo password_hash('TuClaveSegura123!', PASSWORD_BCRYPT), PHP_EOL;"Actualiza el hash en la base de datos de seguridad:
UPDATE dirpoles_security.empleado
SET clave = 'HASH_GENERADO_AQUI', estatus = 1
WHERE correo = 'admin@gmail.com';- Abre
http://localhost/DIRPOLES-4/loginen el navegador. - Inicia sesión con las credenciales configuradas.
- Deberías visualizar el Panel de Inicio con las tarjetas estadísticas del módulo y el calendario operativo personal.
| Variable | Descripción | Ejemplo |
|---|---|---|
APP_DEBUG |
Muestra detalles de depuración (true desarrollo) |
false |
DB_HOST |
Host del motor de base de datos MySQL | localhost |
DB_NAME |
Nombre del esquema de negocio | dirpoles_business |
DB_USER / DB_PASS |
Credenciales de la BD de negocio | root / (vacío) |
DB_SECURITY_NAME |
Nombre del esquema de seguridad | dirpoles_security |
DB_SECURITY_USER / DB_SECURITY_PASS |
Credenciales de la BD de seguridad | root / (vacío) |
JWT_EXPIRATION |
Expiración del token JWT en segundos | 3600 (1 h) |
REFRESH_EXPIRATION |
Expiración del Refresh Token en segundos | 1296000 (15 días) |
APP_ENV |
Entorno de ejecución | local | staging | production |
CORS_ALLOWED_ORIGINS |
Dominio(s) permitidos en CORS | http://localhost:5173 |
DIRPOLES-4/
├── index.php Front Controller (CORS → sesión → handler → Router)
├── .htaccess Redirección centralizada a index.php
├── .env / .env.example Configuración de entorno
├── composer.json Autoload PSR-4 + dependencias
├── setup_linux.sh Script de instalación automatizado (Linux)
│
├── app/
│ ├── Core/ Infraestructura: Router, Database, Respuesta,
│ │ ExcepcionApi, ErrorCodes, Autorizacion,
│ │ Bitacora, Notificador, JwtHandler
│ ├── Middlewares/ RateLimitMiddleware, SessionAuthMiddleware
│ ├── Controllers/ Controladores funcionales (rutas web y APIs)
│ ├── Models/ Modelos de negocio y seguridad (con manejarAccion)
│ ├── Views/ Plantillas HTML renderizadas en servidor (SSR)
│ ├── routes/ Unidades de enrutamiento por módulo
│ ├── Config/ Catálogos, tarjetas dashboard, permisos RBAC
│ │ Keys/ (Llaves RSA no versionadas)
│ ├── bootstrap.php Inicializador de la aplicación
│ └── routes.php Rutas principales y middlewares globales
│
├── dist/
│ ├── css/ Estilos CSS Vanilla y temas custom
│ └── js/
│ ├── core/ apiFetch, AlertManager, logout, select2-init...
│ └── modulos/ Lógica cliente por módulo (tours, stats, CRUD)
│
├── plugins/ Librerías frontend auto-hospedadas (Bootstrap,
│ DataTables, Select2, SweetAlert2, FullCalendar...)
│
├── docs/
│ ├── MANUAL_TECNICO_DIRPOLES4.md Manual Técnico Maestro (Capítulos 1 al 6)
│ ├── bd/ Esquemas SQL completos (security y business)
│ └── auditoria/ Informes de auditoría de seguridad
│
├── logs/ Registros de errores php_errors.log (no versionado)
└── vendor/ Dependencias Composer (no versionado)
| Módulo | ID | Estado | Descripción Funcional |
|---|---|---|---|
| Gestionar Empleados | 1 | ✅ | Administra personal médico, docente, técnico y administrativo, roles y accesos. |
| Gestionar Beneficiarios | 2 | ✅ | Expedientes de estudiantes de la UPTAEB por PNF, trayecto, sección y contacto. |
| Gestionar Citas | 3 | ✅ | Agenda de Psicología y atención clínica contra horarios de disponibilidad. |
| Diagnósticos de Psicología | 4 | ✅ | Evaluaciones clínicas, seguimiento psicológico y constancias en PDF. |
| Diagnósticos de Medicina | 5 | ✅ | Consultas médicas primarias y descuento automático de medicamentos con FOR UPDATE. |
| Diagnósticos de Orientación | 6 | ✅ | Asistencia socioeducativa, vocacional, motivos y recomendaciones institucionales. |
| Diagnósticos de Trabajo Social | 7 | ✅ | Hub de 4 sub-flujos (becas, exoneraciones, FAMES, embarazadas) + Estudio Socioeconómico FPDF. |
| Diagnósticos de Discapacidad | 8 | ✅ | Expediente de atención a personas con diversidad funcional y habilidades. |
| Gestionar Inventario Médico | 9 | ✅ | Kardex transaccional de medicamentos, entradas, salidas justificadas y vencimiento. |
| Gestionar Referencias | 10 | ✅ | Remisión interdepartamental entre áreas de salud con historial de transiciones. |
| Gestionar Jornadas Médicas | 11 | ✅ | Eventos masivos de salud, control de aforo pesimista FOR UPDATE y consumo de insumos. |
| Gestionar Mobiliario y Equipos | 12 | ✅ | Hub de 3 pestañas (bienes muebles, equipos con serial único y Fichas Técnicas responsables). |
| Gestionar Transporte | 13 | ✅ | Control de flota vehicular, rutas universitarias, choferes (id_tipo_emp=8) y repuestos. |
| Configuraciones del Sistema | 14 | ✅ | Administración centralizada de catálogos y parámetros globales. |
| Reportes Estadísticos | 15 | ✅ | 10 tableros estadísticos con filtrado server-side, Chart.js local v2.9.4 y consumo IA. |
| Auditoría / Bitácora | 16 | ✅ | Registro inmutable de trazabilidad forense por IP, usuario y catálogo de acciones. |
| Matriz de Permisos (RBAC) | 17 | ✅ | Matriz dinámica de permisos atómicos (crear, leer, editar, eliminar) por rol. |
| Gestionar Horarios | 18 | ✅ | Administración exclusiva de turnos y agendas por especialista de salud. |
DIRPOLES-4 cumple estrictamente con el estándar OWASP ASVS v4.0.3:
- Cifrado Híbrido en Tránsito y Reposo: RSA-2048 en navegador + Bcrypt en servidor.
- Inmunidad a Inyecciones SQL: 100% de consultas preparadas PDO con tipado explícito (
PARAM_INT,PARAM_STR). - Inmunidad a XSS: Sanitización fail-fast en modelo (
__set()) + escape contextual en vistas (htmlspecialchars()). - Seguridad en Cookies y JWT: Firma RS256, cookies
HttpOnly,SameSite=Laxy rotación de Refresh Token. - Protección contra BOLA / IDOR: Métodos de autorización a nivel de fila (
asegurarAlcance()) en controladores y modelos.
Toda la arquitectura, especificaciones de base de datos, lógica de los 18 módulos y argumentos para la defensa de grado se encuentran detallados en:
- Manual Técnico Maestro de DIRPOLES-4: Documento oficial consolidado (Capítulos 1 al 6, Glosario y Estándares ISO/OWASP).
- Guía de Construcción de Módulos: Guía paso a paso para la incorporación de nuevas funcionalidades.
- Reglas de Desarrollo para IA / Agentes: Estándares y convenciones de código del repositorio.
- Estado en este repositorio: El proyecto cuenta con PHPUnit 11.5, el cual es 100% compatible con PHP >= 8.2 (tanto en Windows con XAMPP 8.2.12 como en Linux con PHP 8.3). Un simple
composer installresolverá todas las dependencias sin conflictos. - Instalación ligera / Producción: Si estás en un servidor donde solo requieres la aplicación en ejecución (sin pruebas unitarias), puedes omitir las dependencias dev:
composer install --no-dev
- Causa: En instalaciones estándar de XAMPP para Windows, la extensión nativa
fileinfoviene deshabilitada por defecto. - Solución:
- Abre el archivo
C:\xampp\php\php.ini(o presiona el botón Config junto a Apache en el Panel de XAMPP y seleccionaPHP (php.ini)). - Busca la línea
;extension=fileinfo(usaCtrl + BoCtrl + F). - Elimina el punto y coma (
;) al inicio para que quede:extension=fileinfo - Guarda el archivo y reinicia el servicio Apache en XAMPP.
- Abre el archivo
- Causa: Por seguridad, las llaves criptográficas RSA (
*.pem) no se incluyen en el repositorio Git y deben generarse en cada entorno. - Solución: Ejecuta el generador multiplataforma de llaves incluido en el sistema:
Esto generará de inmediato los 4 archivos
php scripts/generar_llaves.php
.pemnecesarios en la carpetaapp/Config/Keys/.
- Causa: El módulo
mod_rewritede Apache no está procesando el archivo.htaccess. - Solución:
- Verifica que el archivo
.htaccessesté presente en la raíz del proyecto (C:\xampp\htdocs\DIRPOLES-4\.htaccess). - En
C:\xampp\apache\conf\httpd.conf, comprueba que la línea:no tengaLoadModule rewrite_module modules/mod_rewrite.so#al inicio. - Asegúrate de que el bloque
<Directory "C:/xampp/htdocs">tengaAllowOverride All. - Reinicia Apache.
- Verifica que el archivo
- Causa: Las credenciales configuradas en
.envno coinciden con las de tu gestor de base de datos. - Solución: En una instalación fresca de XAMPP, el usuario es
rooty la contraseña está completamente vacía. Ajusta tu.env:DB_USER=root DB_PASS= DB_SECURITY_USER=root DB_SECURITY_PASS=
Licencia Institucional / Académica
El sistema DIRPOLES-4 es un desarrollo tecnológico y académico original diseñado para la Dirección de Políticas Estudiantiles (DIRPOLES) de la Universidad Politécnica Territorial del Estado Lara "Andrés Eloy Blanco" (UPTAEB), Barquisimeto, Estado Lara, Venezuela.
Desarrollado como Trabajo Especial de Grado / Proyecto Socio-Integrador y Tecnológico (PSIT) para la obtención del título de Ingeniero(a) en Informática en el Programa Nacional de Formación (PNF) en Informática (Trayecto IV).
- Institución Beneficiaria: Universidad Politécnica Territorial del Estado Lara "Andrés Eloy Blanco" (UPTAEB).
- Todos los derechos reservados © UPTAEB — DIRPOLES.
- Uso exclusivo institucional y académico. Queda prohibida la comercialización o distribución sin la debida autorización de las autoridades institucionales y autores del proyecto.
DIRPOLES-4 · Dirección de Políticas Estudiantiles · UPTAEB
Barquisimeto, Venezuela