Manual de Usuario

1. Objetivo

Guía para el rol Aprendiz: acceder a rutas, realizar simulaciones y revisar resultados.

2. Acceso y navegación

• Inicia sesión.
• Menú superior: Escenarios, Mis Rutas, Mi Perfil, Notificaciones.

3. Mis Rutas

Ruta: /routes

• Lista de rutas asignadas a tu ficha.
• Al ingresar a una ruta verás los escenarios pendientes.
• Los escenarios completados se ocultan hasta completar toda la ruta.

4. Escenarios

Ruta: /scenarios

• Ver escenarios disponibles.
• Filtrar por área y nivel.

4.1 Simulación

• Selecciona una opción por paso.
• Se registra la decisión y el puntaje por competencia.
• Al finalizar, se muestra un resumen.
• Los puntajes pueden ser negativos para indicar oportunidad de mejora.

5. Mi Perfil

Ruta: /profile

• Estadísticas de sesiones y puntajes.
• Historial de escenarios completados.

6. Notificaciones

Ruta: /notifications

• Consulta logros y avisos del sistema.

1. Objetivo

Describe las tareas del rol Instructor: crear programas, analizar PDF con IA, generar escenarios, gestionar rutas y consultar reportes.

2. Acceso

Inicia sesión con rol instructor y entra al dashboard en /instructor.

3. Programas (IA)

Rutas:

• /instructor/programs (listado)
• /instructor/programs/create (crear)

3.1 Crear programa desde PDF

1. Subir PDF oficial del programa.
2. Presionar Analizar PDF con IA (Puter.js).
3. El sistema llena automáticamente:
   • Título del programa
   • Código
   • Competencias
   • Perfil de egreso
4. Guardar programa.

Notas: Si no hay sesión en Puter, se solicitará login. Existe un botón opcional Iniciar sesión con Puter.

3.2 Ver análisis del programa

En el detalle del programa se muestran:

• Sector sugerido.
• Habilidades blandas recomendadas.

3.3 Generar escenarios con IA

En Acciones IA:

• Selecciona la competencia foco (lista de habilidades blandas).
• Presiona Generar escenario IA.
• El escenario se guarda automáticamente y queda disponible en la lista.

4. Rutas de aprendizaje

Rutas:

• /instructor/routes (listado)
• /instructor/routes/create (crear)

Funciones:

• Crear rutas y seleccionar escenarios.
• Asignar grupos/fichas.
• Definir fechas de inicio y fin.

5. Reportes

Rutas:

• /instructor/reports/individual/{id}
• /instructor/reports/group

Usa estos reportes para seguimiento individual o grupal.

6. Recomendaciones

• Mantener escenarios alineados al perfil y competencias del programa.
• Verificar que el análisis IA está completo antes de generar escenarios.

1. Objetivo

Este manual describe las tareas y pantallas disponibles para el rol Administrador en RolPlay EDU: gestión de usuarios, escenarios, configuración del sistema, logs y acciones administrativas.

2. Acceso al panel

1. Inicia sesión con un usuario con rol admin.
2. Ingresa a Dashboard (menú superior) o directamente a /admin.

3. Panel de Administración

En el dashboard se muestran indicadores generales:

• Total de usuarios y distribución por rol.
• Total de escenarios.
• Sesiones: activas, completadas, dinámicas y promedio de puntaje.

4. Gestión de Usuarios

Ruta: /admin/users

Acciones:

• Crear usuario: nombre, correo, rol (aprendiz/instructor/admin) y ficha (opcional para aprendiz).
• Editar usuario: actualizar datos y rol.
• Eliminar usuario: desactiva el usuario (no elimina tu propio admin).

Buenas prácticas:

• Verifica que el correo sea único.
• Mantener fichas consistentes para asignación de rutas.

5. Gestión de Escenarios

Ruta: /admin/scenarios

Acciones:

• Ver listado de escenarios con estado.
• Activar/Desactivar escenarios según disponibilidad.

6. Configuración del Sistema

Ruta: /admin/settings

6.1 Configuración general

• Nombre de la aplicación.
• Modo mantenimiento.

6.2 Integraciones

• Estado de base de datos.
• Estado de TCPDF (reportes).
• Integración con Puter:
  • Activar/Desactivar la integración.
  • Usuario/correo sugerido (login hint).
  • Modo de acceso (login/consent/selección de cuenta).
  • Auto-login al cargar.
  • Contraseña (no visible; si se deja vacío se conserva la anterior).

Nota: Puter requiere autenticación mediante su ventana oficial; el sistema usa el usuario como pista.

6.3 Seguridad

• Hashing de contraseñas (PASSWORD_BCRYPT).
• Sesiones PHP activas.
• Protección SQL Injection vía PDO.

6.4 Gamificación

• Habilitar/deshabilitar logros.
• Habilitar/deshabilitar ranking.
• Habilitar/deshabilitar notificaciones.

7. Acciones del Sistema

En /admin/settings:

• Limpiar caché.
• Backup de base de datos.
• Exportar usuarios CSV.
• Ver logs.

8. Logs del sistema

Ruta: /admin/logs

• Permite revisar los últimos eventos registrados.

9. Recomendaciones operativas

• Realiza backups periódicos.
• Verifica que Puter esté habilitado antes de habilitar análisis IA.
• Desactiva escenarios obsoletos para evitar que se asignen.

1. Arquitectura general

• Backend: PHP (estructura MVC propia).
• Frontend: HTML + Tailwind CSS + componentes neumorfismo.
• BD: MySQL.
• IA: Puter.js con modelo gemini-2.5-flash.
• PDF: PDF.js para extracción de texto.

2. Estructura de carpetas (resumen)

• app/controllers: lógica de controladores.
• app/models: acceso a datos.
• app/views: vistas por módulo.
• public/assets: CSS/JS estáticos.
• database/migrations: scripts SQL.
• storage: logs, backups y caché.

3. Flujo IA con Puter.js

• Se autentica mediante popup oficial (signIn).
• Análisis de PDF en frontend con PDF.js.
• Respuestas JSON validadas y normalizadas.

4. Rutas principales del sistema

• Auth: /login, /register, /logout.
• Aprendiz: /scenarios, /routes, /profile.
• Instructor: /instructor/programs, /instructor/routes.
• Admin: /admin, /admin/settings.

5. Base de datos (resumen conceptual)

• users: usuarios, roles y ficha.
• programs: programas, análisis IA y PDF.
• scenarios: escenarios y pasos.
• sessions: sesiones de juego y puntajes.
• routes: rutas de aprendizaje.
• system_settings: configuraciones del sistema.

6. Configuración del sistema

• Panel admin en /admin/settings.
• Integración Puter configurable (habilitar, usuario, auto-login, modo).

7. Seguridad

• Hash de contraseñas: password_hash.
• Consultas parametrizadas PDO.
• Control de acceso por rol en controladores.

8. Operación y mantenimiento

• Backup DB desde Admin > Settings.
• Logs accesibles en /admin/logs.
• Limpieza de caché disponible.

9. Consideraciones de despliegue

• Requiere PHP 8+ y MySQL 8+ (XAMPP local en desarrollo).
• Variables en .env.
• Permisos de escritura en storage/.