# 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.