feat: database-first refactor, unified architecture and visual developer manual

Summary of changes: - Consolidated Studio+CMS and Experience+LMS into unified services. - Moved core business logic (enrollment, grading, auth) to PostgreSQL functions. - Implemented advanced auditing via DB triggers and session context. - Added gamification (XP/Levels/Leaderboards) and logic encapsulation. - Updated installation/diagnostic scripts for the new architecture. - Created a comprehensive Visual Developer Manual in README.md with hardware scaling.
2026-01-11 02:34:23 -03:00
parent a19da8de76
commit b1eb23926e
42 changed files with 2661 additions and 588 deletions
@@ -2,196 +2,269 @@

 OpenCCB es una infraestructura de código abierto para plataformas de gestión de aprendizaje y contenido (LMS/CMS), construida con rendimiento, seguridad y escalabilidad en mente.

-## 🚀 Estado del Proyecto
+## 🚀 Arquitectura Consolidada

-El sistema se encuentra en una fase avanzada (**Phase 6 en progreso**), ofreciendo una infraestructura multi-inquilino de alto rendimiento, gestión de marcas por organización (branding), autenticación segura y análisis detallado de datos.
+El proyecto ha sido optimizado para reducir la complejidad de la infraestructura, consolidando los servicios de backend con sus respectivos frontends en contenedores unificados:

-Consulta el archivo [ROADMAP.md](./roadmap.md) para ver el desglose detallado de funcionalidades.
+1.  **Studio + CMS (Puerto 3000/3001)**:
+    - **Frontend**: Next.js app para administración y creación de contenido.
+    - **Backend**: API de Rust para gestión (CMS).
+2.  **Experience + LMS (Puerto 3003/3002)**:
+    - **Frontend**: Next.js app para la experiencia del estudiante.
+    - **Backend**: API de Rust para entrega de cursos y calificaciones (LMS).
+3.  **Database**: PostgreSQL compartido.
+4.  **AI Services**: Faster-Whisper para transcripción automática.

-## 🛠 Stack Tecnológico
+## � Requisitos del Sistema

- **Core**: Rust (Edition 2024)
- **API Framework**: Axum
- **Base de Datos**: PostgreSQL (con `sqlx`)
- **Autenticación**: JWT + RBAC (Roles: Admin, Instructor, Student)
- **Infraestructura**: Docker & Docker Compose
+OpenCCB es altamente escalable. A continuación se detallan los requisitos recomendados según la carga de usuarios concurrentes:

-## 🔌 API Reference (CMS Service)
+| Componente | **Pequeño (100 u.)** | **Mediano (500 u.)** | **Grande (1000+ u.)** |
+| :--- | :--- | :--- | :--- |
+| **CPU** | 4 vCPUs | 8 vCPUs (AVX2) | 16+ vCPUs |
+| **RAM** | 8 GB | 16 GB | 32 GB+ |
+| **Almacenamiento** | 50 GB SSD | 200 GB NVMe | 500 GB+ NVMe |
+| **AI (Opcional)** | N/A (Solo CPU) | NVIDIA 8GB+ VRAM | Multi-GPU / Cloud API |
+| **OS** | Ubuntu 22.04 LTS | Ubuntu 22.04+ | Cloud Managed (K8s) |

-El servicio CMS expone una API RESTful en el puerto `3001`. A continuación se detallan los contratos de los endpoints principales.
+> [!NOTE]
+> Los requisitos de AI son específicos para la función de transcripción local (Whisper). Si se utiliza una API externa, el requisito de GPU desaparece.

-### 🔐 Autenticación
+## �🛠 Stack Tecnológico

-#### Registrar Usuario
- **URL**: `POST /auth/register`
- **Descripción**: Crea una nueva cuenta de usuario.
- **Body (JSON)**:
-  ```json
-  {
-    "email": "string (email format)",
-    "password": "string (min 8 chars)",
-    "role": "string ('instructor' | 'student')",
-    "organization_name": "string (optional)"
-  }
-  ```
+- **Backend**: Rust (Edition 2024), Axum, SQLx.
+- **Frontend**: React, Next.js (App Router), Tailwind CSS, Lucide React.
+- **Base de Datos**: PostgreSQL 16.
+- **Infraestructura**: Docker & Docker Compose.
+- **IA**: Faster-Whisper (Transcriptor de video).

-#### Iniciar Sesión
- **URL**: `POST /auth/login`
- **Descripción**: Autentica un usuario y devuelve un token JWT.
- **Body (JSON)**:
+## 📦 Guía de Inicio Rápido
+
+### Requisitos Previos
+- Docker y Docker Compose.
+- Node.js 18+ (para desarrollo local).
+- Rust (para desarrollo local).
+
+### Ejecución con Docker (Recomendado)
+```bash
+docker-compose up --build
+```
+Esto iniciará todos los servicios:
+- **Studio**: [http://localhost:3000](http://localhost:3000)
+- **Experience**: [http://localhost:3003](http://localhost:3003)
+
+### Desarrollo Local
+
+#### Studio & CMS
+```bash
+# Iniciar backend CMS
+cd services/cms-service
+cargo run
+
+# Iniciar frontend Studio
+cd web/studio
+npm install
+npm run dev
+```
+
+#### Experience & LMS
+```bash
+# Iniciar backend LMS
+cd services/lms-service
+cargo run
+
+# Iniciar frontend Experience
+cd web/experience
+npm install
+npm run dev
+```
+
+## 🔌 Manual del Desarrollador (API)
+
+### 1. Autenticación y Cuentas
+Gestión de registro, login y perfiles organizacionales.
+
+#### POST /auth/register
+Crea una nueva organización y el usuario administrador inicial.
+
+- **Lógica Inteligente**: Si `organization_name` está vacío, se utiliza el dominio del email. El primer usuario es marcado como `role: admin`.
+- **Cuerpo de la Petición ( AuthPayload ):**
  ```json
  {
    "email": "string",
-    "password": "string"
+    "password": "string",
+    "full_name": "string",
+    "organization_name": "string",
+    "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"
+    }
  }
  ```

-### 📚 Gestión de Cursos
+```bash
+# Registrar un nuevo administrador y empresa
+curl -X POST "http://localhost:3001/auth/register" \
+     -H "Content-Type: application/json" \
+     -d '{"email": "admin@empresa.com", "password": "pass", "organization_name": "OpenCCB Corp"}'
+```

-#### Listar Cursos
- **URL**: `GET /courses`
- **Descripción**: Obtiene la lista de cursos visibles para el usuario.
+---

-#### Crear Curso
- **URL**: `POST /courses`
- **Descripción**: Inicializa un nuevo curso.
- **Body (JSON)**:
+### 2. Gestión de Contenidos (CMS)
+Herramientas para instructores y administradores.
+
+#### POST /courses
+Crea un nuevo curso vinculado a la organización del usuario.
+
+- **Lógica**: El `instructor_id` se asigna automáticamente desde el token JWT.
+- **Cuerpo ( CreateCourseRequest ):**
  ```json
  {
    "title": "string",
-    "description": "string (optional)",
-    "passing_percentage": "integer (0-100, default: 70)"
+    "pacing_mode": "string (self_paced | instructor_led)"
  }
  ```

-#### Actualizar Curso
- **URL**: `PUT /courses/{id}`
- **Descripción**: Modifica metadatos del curso.
- **Body (JSON)**:
-  ```json
-  {
-    "title": "string",
-    "description": "string",
-    "passing_percentage": "integer",
-    "certificate_template": "string (HTML content)"
-  }
-  ```
+```bash
+# Crear curso básico
+curl -X POST "http://localhost:3001/courses" \
+     -H "Authorization: Bearer $TOKEN" \
+     -d '{"title": "Curso de Rust", "pacing_mode": "self_paced"}'
+```

-#### Publicar Curso
- **URL**: `POST /courses/{id}/publish`
- **Descripción**: Sincroniza el curso y su contenido con el servicio LMS.
- **Body**: `{}` (Vacío)
+#### POST /lessons
+Agrega contenido multimedia o evaluaciones a un módulo.

-### 📦 Contenido (Módulos y Lecciones)
-
-#### Crear Módulo
- **URL**: `POST /modules`
- **Body (JSON)**:
-  ```json
-  {
-    "course_id": "uuid",
-    "title": "string",
-    "order_index": "integer"
-  }
-  ```
-
-#### Crear Lección
- **URL**: `POST /lessons`
- **Body (JSON)**:
+- **Configuración Graduable**: Si `is_graded` es true, los puntos sumarán al XP del estudiante en el LMS.
+- **Cuerpo ( CreateLessonRequest ):**
  ```json
  {
    "module_id": "uuid",
    "title": "string",
-    "content_type": "string ('video' | 'article' | 'quiz')",
-    "max_attempts": "integer (optional, null = unlimited)",
-    "allow_retry": "boolean (default: true)"
+    "content_type": "string (video | reading | quiz)",
+    "content_url": "string (opcional)",
+    "is_graded": "boolean",
+    "grading_category_id": "uuid (opcional)"
  }
  ```

-#### Actualizar Lección
- **URL**: `PUT /lessons/{id}`
- **Body (JSON)**:
+```bash
+# Agregar lección de video
+curl -X POST "http://localhost:3001/lessons" \
+     -H "Authorization: Bearer $TOKEN" \
+     -d '{"module_id": "...", "title": "Intro", "content_type": "video", "is_graded": false}'
+```
+
+---
+
+### 3. Experiencia de Aprendizaje (LMS)
+Endpoints para estudiantes y seguimiento de progreso.
+
+#### POST /enroll
+Inscribe al usuario en un curso.
+
+- **Lógica**: Verifica que el curso pertenezca a la misma organización que el usuario.
+- **Cuerpo ( EnrollPayload ):**
  ```json
  {
-    "title": "string",
-    "content_blocks": "array (JSON objects)",
-    "max_attempts": "integer",
-    "allow_retry": "boolean"
+    "course_id": "uuid"
  }
  ```

-#### Transcripción AI (Simulado)
- **URL**: `POST /lessons/{id}/transcribe`
- **Descripción**: Inicia el proceso de generación de subtítulos/resumen.
- **Body**: `{}` (Vacío)
+```bash
+# Inscribirse en un curso
+curl -X POST "http://localhost:3002/enroll" \
+     -H "Authorization: Bearer $TOKEN" \
+     -d '{"course_id": "uuid-del-curso"}'
+```

-### 📂 Sistema & Assets
+#### POST /grades
+Registra el puntaje de una lección y actualiza la gamificación.

-#### Subir Archivo
- **URL**: `POST /assets/upload`
- **Tipo**: `multipart/form-data`
- **Campo**: `file` (Binary)
-
-#### Logs de Auditoría
- **URL**: `GET /audit-logs`
- **Query Params**: `?page=1&limit=50`
-
-### 🏢 Organizaciones & Branding
-
-#### Listar Organizaciones (Admin)
- **URL**: `GET /organizations`
- **Descripción**: Obtiene la lista completa de inquilinos del sistema.
-
-#### Configurar Branding
- **URL**: `PUT /organizations/{id}/branding`
- **Descripción**: Actualiza los colores primario y secundario de la organización.
- **Body (JSON)**:
+- **Lógica Inteligente**: Actualiza automáticamente el XP del usuario y despacha webhooks si el curso se completa.
+- **Cuerpo ( GradeSubmissionPayload ):**
  ```json
  {
-    "primary_color": "#hex",
-    "secondary_color": "#hex"
+    "course_id": "uuid",
+    "lesson_id": "uuid",
+    "score": "float (0.0 a 1.0)",
+    "metadata": "object (opcional)"
  }
  ```

-#### Subir Logo de Organización
- **URL**: `POST /organizations/{id}/logo`
- **Tipo**: `multipart/form-data`
- **Campo**: `file` (Binary)
+```bash
+# Enviar calificación de 90%
+curl -X POST "http://localhost:3002/grades" \
+     -H "Authorization: Bearer $TOKEN" \
+     -d '{"course_id": "...", "lesson_id": "...", "score": 0.9}'
+```

-#### Obtener Branding Público
- **URL**: `GET /organizations/{id}/branding`
- **Descripción**: Recupera la identidad visual (logo y colores) de una organización.
+---

-### 👥 Gestión de Usuarios (Admin)
+### 4. IA y Analíticas Avanzadas
+Funcionalidades inteligentes y métricas de negocio.

-#### Listar Usuarios
- **URL**: `GET /users`
- **Descripción**: Obtiene todos los usuarios registrados en el sistema.
+#### POST /chat (Streaming)
+Conversación en tiempo real con la base de conocimientos.

-#### Actualizar Usuario
- **URL**: `PUT /users/{id}`
- **Descripción**: Permite cambiar el rol o la organización de un usuario.
- **Body (JSON)**:
+- **Nueva Sesión**: Omite `session_id`. La API creará uno nuevo y generará un título automático.
+- **Continuar Sesión**: Envía el `session_id` devuelto anteriormente.
+- **RAG (Base de Conocimiento)**: Envía `"use_kb": true` para que la IA busque en los documentos de S3.
+- **Cuerpo ( ChatPayload ):**
  ```json
  {
-    "role": "string",
-    "organization_id": "uuid"
+    "username": "string",
+    "prompt": "string",
+    "session_id": "uuid (opcional)",
+    "use_kb": "boolean"
  }
  ```

-## 📦 Configuración y Ejecución
+```bash
+# Iniciar chat con RAG
+curl -X POST "http://localhost:8000/chat" \
+     -H "Content-Type: application/json" \
+     -d '{
+           "username": "juan",
+           "prompt": "Explícame qué es Docker en una frase",
+           "use_kb": true
+         }'
+```
+**Respuesta**: Stream de texto plano. Al final incluye un JSON con el ID de sesión: `{"session_id": "..."}`.

-1. **Variables de Entorno**:
-   Asegúrate de tener configurado `DATABASE_URL` en tu archivo `.env`.
+#### GET /courses/{id}/analytics/advanced
+Métricas de retención y análisis de cohortes.

-2. **Base de Datos**:
-   El sistema utiliza migraciones automáticas de `sqlx` al iniciar.
+- **Respuesta ( AdvancedAnalyticsResponse ):**
+  ```json
+  {
+    "cohorts": [
+      { "period": "string", "count": "int", "completion_rate": "float" }
+    ],
+    "retention": [
+      { "lesson_id": "uuid", "lesson_title": "string", "student_count": "int" }
+    ]
+  }
+  ```

-3. **Ejecutar Servicio**:
-   ```bash
-   cargo run --bin cms-service
-   ```
-   O mediante Docker:
-   ```bash
-   docker-compose up --build
-   ```
+---
+
+## 🏆 Gamificación y Analíticas
+OpenCCB incluye un sistema integrado de:
+- **XP y Niveles**: Los estudiantes progresan al completar lecciones.
+- **Leaderboards**: Rankings dentro de la organización.
+- **Analíticas Avanzadas**: Análisis de cohortes y mapas de calor de retención para instructores.
+
+## 📄 Licencia
+Este proyecto es código abierto y está disponible bajo los términos de la licencia especificada en el repositorio.