LC-ADVANCE

<img src='https://github.com/cervanlfc7/LC-ADVANCE/actions/workflows/ci.yml/badge.svg' alt='CI' class='inline-image' />

Plataforma educativa interactiva con lecciones, quizzes adaptativos, sistema de puntos, badges, ranking en tiempo real y mapa de combate interactivo.

📋 Contenido Rápido

• Requisitos | Instalación | Getting Started | Agregar Lecciones | Troubleshooting

Documentación complementaria:

• public/docs/DEVELOPMENT.md - Arquitectura y desarrollo
• public/docs/API.md - Endpoints y referencias
• public/docs/TROUBLESHOOTING.md - Soluciones a problemas

✨ Características Principales

🎓 Lecciones Interactivas

• ✅ 200+ lecciones en múltiples materias
• ✅ Contenido estructurado con quizzes integrados
• ✅ Progreso guardado automáticamente
• ✅ Acceso invitado (lectura sin guardar)

🏆 Sistema de Puntos y Ranking

• ✅ Top 10 Ranking en vivo - Se actualiza automáticamente cada 15 segundos
• ✅ Puntos por respuesta correcta
• ✅ Cálculo automático de niveles
• ✅ Badges (insignias) por logros
• ✅ Solo usuarios logueados aparecen en ranking

🗺️ Mapa Interactivo

• ✅ Combate educativo con maestros
• ✅ Selección dinámica de personajes
• ✅ Sistema de diálogos inmersivo

🔐 Autenticación y Seguridad

• ✅ Login/Register con hashing bcrypt
• ✅ NUEVO: Autenticación social (Google y GitHub) mediante OAuth
• ✅ NUEVO: Gatekeeper - Sistema de acceso dual (Login o Invitado)
• ✅ Sesiones seguras
• ✅ Protección CSRF
• ✅ Validación de entrada

🤖 Inteligencia Artificial Integrada

• ✅ NUEVO: Tutor AI - Asistencia contextual basada en IA directamente en las lecciones y quizzes.

📱 Responsive Design

• ✅ Funciona en desktop y mobile
• ✅ Diseño retro 8-bit moderno
• ✅ Efectos visuales y animaciones

🚀 Performance

• ✅ Tests automatizados
• ✅ CI/CD con GitHub Actions
• ✅ Carga rápida de contenido
• ✅ Actualizaciones en tiempo real

Requisitos

• PHP 8.1+ (8.2 recomendado)
• MySQL/MariaDB 5.7+
• Servidor web: Apache, Nginx, o PHP built-in
• Extensiones PHP: PDO, pdo_mysql, curl, mbstring
• Navegador moderno (Chrome, Firefox, Safari, Edge)

Instalación local (XAMPP):

• Windows: XAMPP (https://www.apachefriends.org)
• macOS/Linux: XAMPP o docker

Instalación Rápida

1️⃣ Clonar/Descargar el proyecto

git clone https://github.com/cervanlfc7/LC-ADVANCE.git
cd LC-ADVANCE

2️⃣ Configurar base de datos

Opción A: Base de datos unificada (recomendado) ⭐

# Windows (XAMPP)
c:\xampp\mysql\bin\mysql.exe -u root -p < src\Database\lc_advance.sql
# macOS/Linux
mysql -u root -p < src/Database/lc_advance.sql

Nota: El archivo src/Database/lc_advance.sql incluye automáticamente:

• Tabla usuarios (login y progreso)
• Tabla user_progress (puntos y lecciones completadas)
• Tabla lecciones_completadas (tracking)
• Tabla badges (logros)
• Tabla preguntas (banco de preguntas del sistema de combate)
• Tabla dialogosmapa (diálogos del mapa)
• Tabla maestroact (maestros actuales en mapa)

3️⃣ Configurar credenciales

Edita src/Config/config.php:

define('DB_HOST', 'localhost');     // Tu host MySQL
define('DB_NAME', 'lc_advance');    // Nombre BD (por defecto: lc_advance)
define('DB_USER', 'root');          // Usuario MySQL
define('DB_PASS', '');              // Contraseña MySQL (vacía si no hay)

4️⃣ Iniciar servidor local

Con XAMPP: Abre XAMPP Control Panel → Apache + MySQL "Start"

O usa PHP built-in:

php -S localhost:8000 -t .

Abre en navegador:

• 🏠 Landing: http://localhost/LC-ADVANCE/index.php
• 🗺️ Mapa: http://localhost/LC-ADVANCE/public/mapa/index.php
• 📊 Dashboard: http://localhost/LC-ADVANCE/public/dashboard.php (requiere login)

Getting Started

Crear tu primer usuario

1. Ve a http://localhost/LC-ADVANCE/index.php
2. Click en "🆕 Crear cuenta"
3. Llena:

• 👤 Usuario: estudiante_prueba
• 📧 Correo: estudiante@example.com
• 🔑 Contraseña: Mínimo 6 caracteres (ej: Test1234)

1. Click "Registrar"
2. Ve a Login → Ingresa credenciales

Tomar una lección y subir en el ranking

1. Haz login
2. Ve a Dashboard (automático después de login)
3. Selecciona una materia (Inglés, Matemáticas, etc.)
4. Click en una lección (ej: "PAST SIMPLE DOMINATION 2025")
5. Lee el contenido y click "🧠 Ir al Quiz"
6. Responde las preguntas (máximo 10)
7. ¡Recibirás puntos! 🎉

Ver tu posición en el ranking

• ✅ El TOP 10 aparece en el lado derecho del Dashboard
• ✅ Tu usuario se destaca en verde neón si estás en el top 10
• ✅ Se actualiza cada 15 segundos automáticamente
• ✅ Solo usuarios logueados aparecen en el ranking

Subir de nivel

• Cada 500 puntos = 1 Nivel
• 500 pts → Nivel 1: Novato (Badge bronze)
• 1000 pts → Nivel 2: Explorador (Badge silver)
• 2000 pts → Nivel 3: Élite (Badge gold)

Verificar progreso en BD

USE lc_advance;
-- Ver todos los usuarios y sus puntos
SELECT nombre_usuario, puntos, nivel FROM usuarios ORDER BY puntos DESC;
-- Ver progreso de un usuario específico
SELECT u.nombre_usuario, up.slug, up.score, up.completed
FROM user_progress up
JOIN usuarios u ON u.id = up.user_id
WHERE u.nombre_usuario = 'estudiante_prueba';
-- Top 10 ranking
SELECT nombre_usuario, puntos, nivel FROM usuarios ORDER BY puntos DESC LIMIT 10;

Estructura del Proyecto

LC-ADVANCE/
├── index.php                 # Landing page
├── login.php                 # Formulario login
├── register.php              # Formulario registro
├── auth_provider.php         # 🔐 Proveedor OAuth (Google/GitHub)
├── auth_callback.php         # 🔐 Callback OAuth
├── ai_tutor.php              # 🤖 Endpoint del Tutor IA
├── gatekeeper.php            # 🚪 Intersticial para acceso Login/Invitado
├── dashboard.php             # Panel principal (después de login)
├── leccion_detalle.php       # Vista de lección + quiz
├── guest_login.php           # Acceso como invitado (lectura)
├── update_progress.php       # Endpoint para actualizar puntos
├── logout.php                # Cerrar sesión
│
├── config/
│   ├── config.php            # 🔑 Credenciales BD (EDITAR AQUÍ)
│   └── csrf.php              # Protección CSRF
│
├── src/
│   ├── content.php           # 📚 Array de lecciones ($lecciones)
│   └── funciones.php         # Acciones AJAX (calificar_quiz, etc.)
│
├── assets/
│   ├── css/style.css         # Estilos
│   └── js/app.js             # JavaScript cliente
│
├── mapa/                     # 🗺️ Sistema de combate interactivo
│   ├── index.html
│   ├── updateDB.php          # Endpoint para actualizar maestros
│   ├── sistemC.php
│   └── imagenes/
│
├── db/
│   └── lc_advance.sql        # 🔑 Dump unificado (USAR ESTE)
│
├── scripts/
│   └── seed_test_data.php    # Crear usuario de prueba CI
│
├── tests/
│   ├── test_lessons.php      # Verificar lecciones
│   ├── test_integration.php  # Verificar endpoints
│   ├── test_e2e_simple.php   # E2E básico
│   ├── test_updateDB.php     # Verificar mapa
│   └── run_all_tests.php     # 🧪 Ejecutor de tests
│
└── .github/workflows/
    └── ci.yml                # ✅ Pipeline CI (GitHub Actions)

Endpoints & API

Ver documentación completa en public/docs/API.md

Endpoints principales:

• POST /login.php - Autenticación
• GET /leccion_detalle.php?slug=...&materia=... - Ver lección
• POST /src/Core/funciones.php - Calificar quiz (accion=calificar_quiz)
• POST /src/Core/funciones.php - Obtener estado (accion=obtener_estado)
• POST /public/mapa/updateDB.php - Actualizar maestro del mapa

Ver public/docs/API.md para ejemplos curl y respuestas JSON detalladas.

Cómo Agregar Lecciones

1️⃣ Editar src/Content/content.php

Localiza el array $lecciones y agrega una nueva entrada:

$lecciones[] = [
    'materia'   => 'Inglés',
    'slug'      => 'mi-primera-leccion',
    'titulo'    => 'Mi Primera Lección',
    'icon'      => '📖',
    'contenido' => <<<'EOT'
<h2>Título de la lección</h2>
<p>Contenido aquí...</p>
<p>Puedes usar HTML normal, <strong>no uses &lt;?php sin escapar</strong></p>
EOT,
    'quiz'      => [
        [
            'pregunta'  => '¿Cuál es la respuesta correcta?',
            'correcta'  => 'La respuesta 1',
            'opciones'  => ['La respuesta 1', 'Opción falsa', 'Otra opción']
        ],
        [
            'pregunta'  => '¿Y esta?',
            'correcta'  => 'Correcto',
            'opciones'  => ['Incorrecto', 'Correcto', 'Muy incorrecto']
        ]
    ]
];

2️⃣ Estructura de cada lección

3️⃣ Estructura de cada pregunta

[
    'pregunta'  => 'Texto de la pregunta',
    'correcta'  => 'Respuesta correcta (texto exacto)',
    'opciones'  => [
        'Opción 1',
        'Opción 2',
        'Opción 3',
        'Opción 4'
    ]
]

4️⃣ Ejemplo completo

$lecciones[] = [
    'materia'   => 'Matemáticas',
    'slug'      => 'ecuaciones-cuadraticas-2025',
    'titulo'    => 'Ecuaciones Cuadráticas',
    'icon'      => '∑',
    'contenido' => <<<'EOT'
<h2>Ecuaciones Cuadráticas</h2>
<p>Una ecuación cuadrática tiene la forma: <strong>ax² + bx + c = 0</strong></p>
<h3>Fórmula General</h3>
<p>x = (-b ± √(b² - 4ac)) / 2a</p>
<h3>Ejemplo</h3>
<p>Resuelve: x² + 3x + 2 = 0</p>
<p>Respuesta: x = -1 o x = -2</p>
EOT,
    'quiz'      => [
        [
            'pregunta'  => 'Resuelve x² - 5x + 6 = 0',
            'correcta'  => 'x = 2, x = 3',
            'opciones'  => ['x = 2, x = 3', 'x = 1, x = 6', 'x = -2, x = -3']
        ],
        [
            'pregunta'  => '¿Cuál es el discriminante de x² + 4x + 4 = 0?',
            'correcta'  => '0',
            'opciones'  => ['0', '4', '-4', '16']
        ]
    ]
];

5️⃣ Probar la lección

1. Guarda src/content.php
2. Recarga la página (sin caché: Ctrl+Shift+R)
3. Ve a Dashboard → Selecciona "Matemáticas"
4. Tu nueva lección debería aparecer

Testing & CI/CD

Ejecutar tests localmente

# Todos los tests
php tests/run_all_tests.php
# Test específico
php tests/test_lessons.php
php tests/test_integration.php
php tests/test_e2e_simple.php

Salida esperada:

Running: tests/test_lessons.php
OK: targeted lesson checks passed
PASS: tests/test_lessons.php
---
Running: tests/test_integration.php
OK: integration endpoint tests passed
PASS: tests/test_integration.php
---
ALL TESTS PASSED

CI/CD con GitHub Actions

Cada push a main o PR ejecuta automáticamente:

• ✅ PHP 8.1 y 8.2
• ✅ Importa BD (sql/lc_advance.sql)
• ✅ Ejecuta suite de tests
• ✅ Reporta resultados

Ver estado en: https://github.com/cervanlfc7/LC-ADVANCE/actions

Troubleshooting

Ver soluciones detalladas en public/docs/TROUBLESHOOTING.md

Problemas comunes rápidos:

Ver public/docs/TROUBLESHOOTING.md para soluciones completas.

🚀 Despliegue a Producción

1. Ejecuta tests: php tests/runalltests.php
2. Haz backup: mysqldump -u root -p lc_advance > backup.sql
3. Actualiza config/config.php con credenciales de producción
4. Habilita HTTPS
5. Asegura permisos: chmod 600 config/config.php

Ver public/docs/DEVELOPMENT.md para más detalles de arquitectura y deployment.

� Documentación Completa

�📞 Soporte

• 🐛 Reporta bugs en Issues: https://github.com/cervanlfc7/LC-ADVANCE/issues
• 💡 Solicita features en Discussions: https://github.com/cervanlfc7/LC-ADVANCE/discussions
• 📧 Contacta al equipo: lcadvance40@gmail.com

¡Gracias por usar LC-ADVANCE! 🎓✨