221 lines
9.9 KiB
Markdown
221 lines
9.9 KiB
Markdown
|
# Plataforma LMS — Estafeta
|
||
|
|
|
||
|
|
Plataforma de aprendizaje (LMS) desarrollada a la medida para **Grupo Estafeta**. Administra cursos/categorías, recursos SCORM, evaluaciones, encuestas, gamificación (insignias/sellos), constancias y reportes de avance de los colaboradores.
|
||
|
|
|
||
|
|
> Sitio de producción: https://induccion-estafeta.com.mx/
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Tabla de contenido
|
||
|
|
|
||
|
|
- [Stack utilizado](#stack-utilizado)
|
||
|
|
- [Arquitectura y estructura](#arquitectura-y-estructura)
|
||
|
|
- [Funcionalidades principales](#funcionalidades-principales)
|
||
|
|
- [Alumno / Colaborador](#alumno--colaborador)
|
||
|
|
- [Administración](#administración)
|
||
|
|
- [SCORM / RTE](#scorm--rte)
|
||
|
|
- [Reportes](#reportes)
|
||
|
|
- [Modelo de datos](#modelo-de-datos)
|
||
|
|
- [Requisitos](#requisitos)
|
||
|
|
- [Instalación](#instalación)
|
||
|
|
- [Configuración](#configuración)
|
||
|
|
- [Seguridad](#seguridad)
|
||
|
|
- [Convenciones](#convenciones)
|
||
|
|
- [Roadmap / pendientes](#roadmap--pendientes)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Stack utilizado
|
||
|
|
|
||
|
|
**Backend**
|
||
|
|
- **PHP 7.4** (Apache + `mod_php`, ea-php74)
|
||
|
|
- **MySQL / MariaDB** (extensión `mysqli`)
|
||
|
|
- **Composer** con:
|
||
|
|
- `phpoffice/phpspreadsheet` — generación/lectura de Excel
|
||
|
|
- `mpdf/mpdf` — generación de PDF (constancias, reportes)
|
||
|
|
- `swiftmailer/swiftmailer` — envío de correo
|
||
|
|
|
||
|
|
**Frontend**
|
||
|
|
- **HTML5, CSS3, JavaScript (jQuery 3.4.1)**
|
||
|
|
- **Bootstrap 4** + **bootstrap-select**
|
||
|
|
- **DataTables** (+ checkboxes, searchpanes, select) — tablas de administración
|
||
|
|
- **SweetAlert2** — modales/alertas
|
||
|
|
- **Uppy** — carga de archivos (imágenes, paquetes SCORM)
|
||
|
|
- **Trumbowyg** — editor WYSIWYG
|
||
|
|
- **Highcharts** — gráficas de reportes
|
||
|
|
- **Select2, Daterangepicker, Moment, Lodash, Owl Carousel, signature_pad** — apoyo de UI
|
||
|
|
- Librerías de exportación: **excelexportjs, js-xlsx, FileSaver**
|
||
|
|
|
||
|
|
**SCORM**
|
||
|
|
- RTE propio en `runtime/` que implementa **SCORM 1.2** (API `LMSInitialize`, `LMSGetValue`, `LMSSetValue`, `LMSCommit`, `LMSFinish`) y lanza los paquetes en un `<iframe>`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Arquitectura y estructura
|
||
|
|
|
||
|
|
Aplicación **PHP monolítica** de múltiples páginas (sin framework), con endpoints AJAX que devuelven JSON y vistas HTML que se cargan dinámicamente en el panel de administración.
|
||
|
|
|
||
|
|
```
|
||
|
|
Estafeta/
|
||
|
|
├── index.php # Login (solo número de empleado)
|
||
|
|
├── dashboard.php # Panel del alumno (categorías asignadas)
|
||
|
|
├── recursos.php # Recursos de una categoría (?idcat=)
|
||
|
|
├── pasaporte.php # Pasaporte de sellos del alumno
|
||
|
|
├── evaluaciones.php # Evaluaciones
|
||
|
|
├── encuestas.php # Encuestas
|
||
|
|
├── certificate.php # Constancias
|
||
|
|
├── config.php # Configuración + conexión a BD + helpers
|
||
|
|
├── sessionManager.php # Bootstrap de sesión (redirige a logout si no hay sesión)
|
||
|
|
├── header.php / footer.php # Layout común
|
||
|
|
├── runtime/ # RTE SCORM (api, sco, commit, finish, gotorte, newlogin...)
|
||
|
|
├── controller/ # Endpoints JSON del front del alumno
|
||
|
|
├── admin/ # Panel de administración (endpoints + vistas .html)
|
||
|
|
│ ├── index.php # Layout admin (carga secciones en .mainseccion)
|
||
|
|
│ ├── auth_guard.php # Guard de autenticación + CSRF
|
||
|
|
│ ├── audit.php # Registro de auditoría (logs/admin.log)
|
||
|
|
│ └── *.php / *.html # Módulos (usuarios, categorías, recursos, etc.)
|
||
|
|
├── cron_report/ # Tareas programadas (avance/sellos)
|
||
|
|
├── evaluaciones/ # Lógica de evaluaciones
|
||
|
|
├── data/ # Datos subidos: scormpkg/, recursos/, imgcat/, ...
|
||
|
|
│ └── .htaccess # Bloquea ejecución de scripts en data/
|
||
|
|
├── logs/ # Bitácora de auditoría (.htaccess de protección)
|
||
|
|
├── vendor/ # Dependencias Composer
|
||
|
|
└── js/ css/ img/ webfonts/ # Recursos frontend
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Funcionalidades principales
|
||
|
|
|
||
|
|
### Alumno / Colaborador
|
||
|
|
- **Ingreso** con número de empleado.
|
||
|
|
- **Dashboard** con las categorías/cursos asignados, agrupados por categoría padre e hijos.
|
||
|
|
- **Cursos SCORM**: apertura de paquetes SCORM 1.2 en un contenedor con barra superior, botón **"Regresar al menú anterior"** (con scroll y resaltado de la categoría al volver) y registro de avance.
|
||
|
|
- **Progreso y sellos**: marca de `completed`/`passed` por recurso; **pasaporte de sellos** por categoría.
|
||
|
|
- **Evaluaciones** y **encuestas**.
|
||
|
|
- **Constancias** en PDF al completar objetivos.
|
||
|
|
|
||
|
|
### Administración
|
||
|
|
Panel en `admin/` (carga secciones vía AJAX en un layout):
|
||
|
|
- **Usuarios**: alta/edición/baja, carga masiva, roles, centros/distritos/posiciones/sociedades/divisiones.
|
||
|
|
- **Categorías**: jerarquía (padre/hijo), clave, imagen, orden, habilitado.
|
||
|
|
- **Recursos (SCORM)**: alta/edición, URL del paquete, imagen; **carga de `.zip` SCORM** que se descomprime en `data/scormpkg/<categoría>/` y genera la URL automáticamente (soporta Storyline, Rise y HTML).
|
||
|
|
- **Asignaciones**: asignación de categorías a usuarios (individual y masiva).
|
||
|
|
- **Evaluaciones / Encuestas**: preguntas, opciones, respuestas y estado.
|
||
|
|
- **Gamificación**: insignias por objetivo (categoría o recurso).
|
||
|
|
- **Constancias**: plantillas (logo/fondo) por categoría.
|
||
|
|
- **Permisos / Licencia**.
|
||
|
|
- **Auditoría**: registro de acciones de escritura en `logs/admin.log`.
|
||
|
|
|
||
|
|
### SCORM / RTE
|
||
|
|
- Punto de entrada: `runtime/gotorte.php?recursoid=<id>` → carga central `runtime/sco.php`.
|
||
|
|
- `runtime/sco.php` sirve un contenedor con el **API SCORM** en la página padre y el paquete en un `<iframe>` (así los SCO localizan el API subiendo por los frames).
|
||
|
|
- Persistencia de progreso en la tabla **`scormvars`** vía `runtime/commit.php` y `runtime/finish.php` (tiempo total, estado, calificación).
|
||
|
|
- Detección robusta del archivo de inicio (por `imsmanifest.xml` o nombres comunes: `index.html`, `index_lms.html`, `story.html`, etc.).
|
||
|
|
|
||
|
|
### Reportes
|
||
|
|
Módulos en `admin/reporte_*` con filtros por categoría, distrito, fechas y estado:
|
||
|
|
- Avance general, por categoría, completados y visitados.
|
||
|
|
- Exportación a **Excel** y vistas con **Highcharts**.
|
||
|
|
- Vistas SQL (`viewReporte*`) para consultas agregadas.
|
||
|
|
- Tareas programadas (`cron_report/`) para consolidar avance/sellos.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Modelo de datos
|
||
|
|
|
||
|
|
Principales tablas y vistas (MySQL):
|
||
|
|
|
||
|
|
| Tabla / Vista | Descripción |
|
||
|
|
|---|---|
|
||
|
|
| `user` | Colaboradores (numempl, nombre, área, rol, habilitado, etc.) |
|
||
|
|
| `categoria` | Categorías jerárquicas (padre, clave, nombre, imagen, orden) |
|
||
|
|
| `scormpkg` | Recursos/cursos (url, idcategoria, imagen, clave, habilitado) |
|
||
|
|
| `scormvars` | Datos de avance SCORM por usuario y recurso (estado, score, tiempo) |
|
||
|
|
| `asignacion` | Categorías asignadas a usuarios |
|
||
|
|
| `insignias` | Gamificación (insignia por objetivo) |
|
||
|
|
| `evaluaciones`, `evaluaciones_preguntas`, `evaluaciones_opciones`, `evaluaciones_respuestas`, `evaluaciones_estado` | Evaluaciones |
|
||
|
|
| `encuestas`, `encuestas_preguntas`, `encuestas_respuestas`, `encuesta_estado` | Encuestas |
|
||
|
|
| `constancias` | Plantillas de constancias por categoría |
|
||
|
|
| `licencia`, `config` | Configuración/permisos |
|
||
|
|
| `viewReporte*` | Vistas para reportes agregados |
|
||
|
|
|
||
|
|
> El estado de un recurso se considera **completado** cuando existe una fila en `scormvars` con `VarName = 'cmi.core.lesson_status'` y `VarValue` `completed` o `passed` para el usuario y el `SCOInstanceID` (id de `scormpkg`).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Requisitos
|
||
|
|
|
||
|
|
- PHP **7.4** con extensiones: `mysqli`, `zip`, `openssl`, `gd`/`mbstring` (según uso), `dom`/`libxml`.
|
||
|
|
- MySQL 5.7+ / MariaDB.
|
||
|
|
- Apache con `mod_rewrite`.
|
||
|
|
- Composer.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Instalación
|
||
|
|
|
||
|
|
1. Clonar/copiar el proyecto en el webroot (`htdocs/git/Estafeta-plataform` o similar).
|
||
|
|
2. Instalar dependencias:
|
||
|
|
```bash
|
||
|
|
composer install
|
||
|
|
```
|
||
|
|
3. Crear la base de datos e importar el respaldo:
|
||
|
|
```sql
|
||
|
|
CREATE DATABASE estafeta_lms2 CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
|
||
|
|
```
|
||
|
|
Luego importar el dump `.sql` correspondiente.
|
||
|
|
4. Ajustar credenciales en `config.php` (host, usuario, contraseña, nombre de BD).
|
||
|
|
5. Dar permisos de escritura a: `data/`, `data/scormpkg/`, `data/recursos/`, `data/imgcat/`, `logs/`.
|
||
|
|
6. Verificar límites de PHP para SCORM (`upload_max_filesize`, `post_max_size`) en `php.ini`/`.htaccess`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Configuración
|
||
|
|
|
||
|
|
En `config.php`:
|
||
|
|
```php
|
||
|
|
$CFG->wwwroot = 'https://tu-dominio/'; // debe terminar en "/"
|
||
|
|
$CFG->sessionname = 'estafetalms360';
|
||
|
|
$dbhost = 'localhost';
|
||
|
|
$dbuser = '...';
|
||
|
|
$dbpass = '...';
|
||
|
|
$dbname = 'estafeta_lms2';
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Seguridad
|
||
|
|
|
||
|
|
Medidas ya implementadas:
|
||
|
|
- `admin/auth_guard.php`: valida sesión + rol admin en los endpoints de `admin/` y **token CSRF** en métodos de escritura.
|
||
|
|
- Sesión endurecida (`use_strict_mode`, `use_only_cookies`, `HttpOnly`, `SameSite=Lax`, `Secure` en HTTPS).
|
||
|
|
- Login con **consultas preparadas**, `session_regenerate_id(true)` y **límite de intentos** por IP.
|
||
|
|
- Consultas preparadas en los CRUD principales (usuarios, categorías, recursos, insignias).
|
||
|
|
- `data/.htaccess` y `logs/.htaccess`: `Options -Indexes` y bloqueo de ejecución de scripts en carpetas de datos.
|
||
|
|
- Auditoría de acciones de administración (`logs/admin.log`).
|
||
|
|
|
||
|
|
Recomendaciones pendientes:
|
||
|
|
- Mover credenciales de `config.php` a variables de entorno y rotar claves.
|
||
|
|
- Extender sentencias preparadas al resto de endpoints (encuestas, evaluaciones, constancias, licencia).
|
||
|
|
- Revisar `session.save_path` en `.htaccess`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Convenciones
|
||
|
|
|
||
|
|
- Vistas de administración: `admin/<modulo>.html` (front) + `admin/<modulo>.php` (endpoint JSON) + `admin/<modulo>_add.php` / `_upadate.php` / `_delete.php`.
|
||
|
|
- Los endpoints validan sesión/rol y **responden JSON**.
|
||
|
|
- Nombres de tablas/columnas en `snake_case`; jerarquía de categorías con `padre` (0 = raíz).
|
||
|
|
- `$CFG->wwwroot` siempre con `/` final.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Roadmap / pendientes
|
||
|
|
|
||
|
|
- Migrar todo el SQL restante a **sentencias preparadas**.
|
||
|
|
- **Hashear** contraseñas (si en el futuro se habilita login con contraseña).
|
||
|
|
- Test automatizados de flujos críticos (login, SCORM, alta de recursos).
|
||
|
|
- Optimización: cache de assets, minificación, revisión de consultas.
|
||
|
|
- Accesibilidad e internacionalización.
|