feat: Add i18n support, new content block types, course export, and lesson interaction tracking.

2026-01-17 02:19:39 -03:00
parent b166387a48
commit 05faa20993
50 changed files with 3368 additions and 388 deletions
@@ -14,9 +14,16 @@ El proyecto ha sido optimizado para reducir la complejidad de la infraestructura
    - **Backend**: API de Rust para entrega de cursos y calificaciones (LMS).
 3.  **Database**: PostgreSQL compartido.
 4.  **AI Services**: stack local con Faster-Whisper (Transcripción) y Ollama (Traducción y Resúmenes).
-5.  **User Profiles**: Gestión completa de identidad (avatar, bio, preferencias).
+    - **AI Course Wizard**: Generación automática de cursos a partir de prompts estructurados.
+    - **Global Admin Console**: Panel estilo Django para gestión supervisada de tenants y auditoría.
+    - **Course Portability**: Importación/Exportación de cursos completos mediante JSON.
+    - **User Profiles**: Gestión completa de identidad (avatar, bio, preferencias).
+    - **Engagement Heatmaps**: Visualización de retención segundo a segundo en videos.
+    - **Smart Notifications**: Recordatorios de fechas límite y alertas in-app.
+    - **Global i18n**: Interfaz multilingüe (EN, ES, PT) con persistencia por usuario.
+    - **Document-Based Learning**: Soporte para actividades de lectura (PDF, DOCX, PPTX).

-## � Requisitos del Sistema
+##  Requisitos del Sistema

 OpenCCB es altamente escalable. A continuación se detallan los requisitos recomendados según la carga de usuarios concurrentes:

@@ -40,6 +47,8 @@ OpenCCB es altamente escalable. A continuación se detallan los requisitos recom
 - **IA Local**:
  - **Faster-Whisper**: Transcripción de audio a texto.
  - **Ollama**: Traducción inteligente (EN -> ES), resúmenes y generación de cuestionarios.
+- **i18n Infrastructure**: Sistema de traducción reactivo para soporte global.
+- **Document Management**: Motor de previsualización de documentos PDF nativo.

 ## 📦 Guía de Inicio Rápido

@@ -70,6 +79,14 @@ npm install
 npm run dev
 ```

+#### 📦 Course Portability
+Manage content mobility across different organizations using standardized JSON exports.
+
+#### GET /courses/{id}/export
+Generates a complete bundle of the course, including modules, lessons, and grading settings.
+
+#### POST /courses/import
+Creates a new course based on a provided export bundle. Automatic dependency mapping ensures data integrity in the new organization.
 #### Experience & LMS
 ```bash
 # Iniciar backend LMS
@@ -101,19 +118,12 @@ Crea una nueva organización y el usuario administrador inicial.
    "role": "string (admin | instructor | student)"
  }
  ```
- **Respuesta Exitosa (200 OK) ( AuthResponse ):**
-  ```json
-  {
-    "token": "string (JWT)",
-    "user": {
-      "id": "uuid",
-      "email": "string",
-      "full_name": "string",
-      "role": "string",
-      "organization_id": "uuid"
-    }
-  }
-  ```
+
+#### SSO (OpenID Connect)
+OpenCCB soporta integración con proveedores de identidad (IdP) externos como Google, Okta y Azure AD.
+- **Configuración**: Los administradores de la organización pueden configurar sus credenciales OIDC en el panel de configuración de Studio.
+- **Autoprovisionamiento**: Los nuevos usuarios se crean automáticamente en la plataforma tras una autenticación exitosa.
+- **Flujo**: `/auth/sso/login/{org_id}` -> IdP -> `/auth/sso/callback` -> Redirección a Studio/Experience con JWT.

 ```bash
 # Registrar un nuevo administrador y empresa
@@ -145,20 +155,66 @@ curl -X POST "http://localhost:3001/courses" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"title": "Curso de Rust", "pacing_mode": "self_paced"}'
 ```
+#### POST /courses/generate
+Utiliza IA para generar la estructura completa de un curso basado en un prompt.
+
+- **Lógica de Generación**: Utiliza modelos de lenguaje (LLM) para descomponer un tema complejo en una malla curricular lógica de módulos y lecciones.
+- **Cuerpo de la Petición ( GenerateCourseRequest ):**
+  ```json
+  {
+    "prompt": "string"
+  }
+  ```
+
+#### GET /courses/{id}/export
+Exporta un curso completo y su contenido a formato JSON para portabilidad.
+
+- **Integridad Portátil**: Empaqueta metadatos, categorías de calificación, módulos y lecciones manteniendo sus relaciones jerárquicas.
+- **Respuesta**: Archivo JSON estandarizado para importación.
+
+#### POST /courses/import
+Importa un curso a partir de un archivo JSON generado previamente.
+
+- **Mapeo de Dependencias**: Re-mapea automáticamente los IDs de lecciones y módulos para la nueva organización, asegurando que las relaciones y ponderaciones se mantengan intactas.
+- **Cuerpo de la Petición ( CourseBundle ):**
+  ```json
+  {
+    "title": "string",
+    "description": "string",
+    "modules": []
+  }
+  ```

 #### POST /lessons
 Agrega contenido multimedia o evaluaciones a un módulo.

 - **Configuración Graduable**: Si `is_graded` es true, los puntos sumarán al XP del estudiante en el LMS.
+- **Nuevos Tipos Gamificados**:
+    - `hotspot`: Identificación visual sobre imágenes (ideal para niños).
+    - `memory-match`: Juego de memoria con pares conceptuales.
 - **Cuerpo ( CreateLessonRequest ):**
+    ```json
+    {
+      "module_id": "uuid",
+      "title": "string",
+      "content_type": "string (video | reading | quiz | hotspot | memory-match | document)",
+      "content_url": "string (opcional)",
+      "is_graded": "boolean"
+    }
+    ```
+
+#### POST /assets
+Sube un archivo multimedia o documento al servidor y devuelve sus metadatos.
+
+- **Lógica de Almacenamiento**: Genera un UUID único para el archivo, extrae el mimetype y lo almacena físicamente en el volumen de `uploads`, registrando la entrada en la base de datos de activos.
+- **Cuerpo de la Petición ( MultipartForm ):**
+  - `file`: Archivo binario (PDF, Video, Imagen, Docx).
+- **Respuesta ( UploadResponse ):**
  ```json
  {
-    "module_id": "uuid",
-    "title": "string",
-    "content_type": "string (video | reading | quiz)",
-    "content_url": "string (opcional)",
-    "is_graded": "boolean",
-    "grading_category_id": "uuid (opcional)"
+    "id": "uuid",
+    "url": "string",
+    "mimetype": "string"
  }
  ```

@@ -196,15 +252,19 @@ curl -X POST "http://localhost:3002/enroll" \
 Registra el puntaje de una lección y actualiza la gamificación.

 - **Lógica Inteligente**: Actualiza automáticamente el XP del usuario y despacha webhooks si el curso se completa.
- **Cuerpo ( GradeSubmissionPayload ):**
-  ```json
-  {
-    "course_id": "uuid",
-    "lesson_id": "uuid",
-    "score": "float (0.0 a 1.0)",
-    "metadata": "object (opcional)"
-  }
-  ```
+- **Engagement Tracking**: Si la lección contiene video, el frontend envía eventos de "heartbeat" cada 5 segundos para generar mapas de calor.
+
+#### GET /notifications
+Obtiene las notificaciones pendientes del usuario.
+
+- **Filtro de Relevancia**: Devuelve únicamente alertas no leídas sobre fechas límite próximas o logros de gamificación recientes.
+- **Respuesta**: Array de `Notification`.
+
+#### POST /notifications/{id}/read
+Marca una notificación específica como leída.
+
+- **Persistencia**: Actualiza el estado en la base de datos para que no reaparezca en el feed del usuario.
+- **Cuerpo de la Petición**: Vacío.

 ```bash
 # Enviar calificación de 90%
@@ -219,10 +279,16 @@ curl -X POST "http://localhost:3002/grades" \
 Funcionalidades inteligentes 100% locales y gratuitas.

 #### POST /lessons/{id}/transcribe
-Inicia el proceso de transcripción (Whisper) y traducción (Ollama).
+Inicia el proceso de transcripción y traducción para una lección de video/audio.
+
+- **Procesamiento Asíncrono**: Despacha una tarea en segundo plano que utiliza Whisper para transcripción y Ollama para generar la traducción y el resumen inteligente.
+- **Cuerpo de la Petición**: Vacío.

 #### GET /lessons/{id}/vtt?lang=en|es
-Devuelve los subtítulos en formato WebVTT para integración nativa en el reproductor.
+Devuelve los subtítulos en formato WebVTT para integración nativa.
+
+- **Internacionalización**: Filtra los subtítulos por el parámetro `lang` y los devuelve con el formato de tiempo compatible con reproductores de video HTML5.
+- **Respuesta**: Archivo de texto WebVTT.

 #### POST /chat (Streaming)
 Conversación en tiempo real con la base de conocimientos.
@@ -253,7 +319,22 @@ curl -X POST "http://localhost:8000/chat" \
 **Respuesta**: Stream de texto plano. Al final incluye un JSON con el ID de sesión: `{"session_id": "..."}`.

 #### GET /courses/{id}/analytics/advanced
-Métricas de retención y análisis de cohortes.
+Métricas de retención y análisis de cohortes para un curso.
+
+- **Inteligencia de Datos**: Cruza información de intentos de evaluaciones y tiempos de visualización para identificar patrones de deserción.
+- **Respuesta**: Dashboard JSON con métricas agregadas.
+
+#### GET /lessons/{id}/heatmap
+Devuelve los puntos de concentración de visualización para una lección.
+
+- **Engagement Visual**: Analiza los eventos de heartbeat para determinar cuáles segundos del video son los más vistos o repetidos por los estudiantes.
+- **Respuesta**: Array de `(second, count)`.
+
+#### GET /courses/{id}/analytics/reports
+Generador de reportes personalizados para exportación.
+
+- **Flexibilidad Administrativa**: Permite filtrar el desempeño por cohortes específicas y devuelve la estructura necesaria para generar archivos CSV profesionales.
+- **Respuesta**: Stream de datos o estructura de reporte.

 ---

@@ -263,6 +344,10 @@ OpenCCB is built for multi-tenancy. Organizations are isolated, but a **Super Ad
 #### Super Admin Definition
 - **Default Organization ID**: `00000000-0000-0000-0000-000000000001`
 - Any user with `role: admin` in this organization is a **Super Admin**.
+#### Global Control Panel (`/admin`)
+- **Dashboard**: Resumen de organizaciones, usuarios y salud del sistema.
+- **Audit Logs**: Seguimiento detallado de todas las acciones administrativas.
+- **Service Monitor**: Estado en tiempo real del API Cluster, AI Services y Background Workers.

 #### Global Courses
 Courses created by Super Admins in the **Default Organization** are automatically marked as **Global**.
@@ -281,14 +366,25 @@ curl -H "Authorization: Bearer $SUPER_ADMIN_TOKEN" \
 ```

 #### GET /organizations
-Returns a searchable list of all organizations. (Admin only).
+Obtiene una lista de todas las organizaciones registradas.
+
+- **Control Global**: Accesible únicamente para usuarios con rol `admin` dentro de la organización `Default`. Permite supervisar el crecimiento del ecosistema.
+- **Respuesta**: Array de `Organization`.

 ---

 ## 🏆 Premium UI Components
+- **Course Portability**: Full JSON-based import/export system for multi-tenant content mobility.
+- **AI Course Wizard**: Instant curriculum generation from natural language prompts.
+- **Global Admin Console**: Centralized control for organizations, users, and audit logs.
+- **Experience Player**: A high-performance, accessible learning interface with glassmorphism design.
 - **Organization Selector**: A searchable combobox for managing large lists of tenants.
+- **Engagement Heatmaps**: Dynamic bar charts showing video retention signatures.
+- **Notification Center**: Real-time alerts for deadlines and achievements.
+- **Custom Report Builder**: Professional reports with one-click CSV export.
 - **Glassmorphism Design**: Consistent aesthetic across Studio and Experience portals.
- **Micro-animations**: Enhanced feedback for publishing and content management.
+- **Global Localization**: Native support for English, Spanish, and Portuguese.
+- **PDF Integrated Viewer**: Read academic documents without leaving the platform.

 ## 📄 Licencia
 Este proyecto es código abierto y está disponible bajo los términos de la licencia especificada en el repositorio.