Files

91 lines
4.8 KiB
Markdown

# Plan de Arquitectura Técnica (SDD-011)
## Módulo: Servidor MCP y Asistente Interactivo Guiado (Walkthrough Spotlight)
---
### 1. Arquitectura del Sistema
```mermaid
graph TD
subgraph "Cliente Web (Frontend BFF)"
WIDGET[UdeCi Chat Widget]
SPOTLIGHT[Spotlight & Walkthrough Engine (CSS/JS)]
DOM[DOM de la Aplicación: Sedes, Aulas, Ciclos...]
end
subgraph "Backend Core FastAPI (:5000)"
ROUTER[routers/ai_chat.py]
GUIDE_SRV[services/guide_service.py]
MCP_ROUTER[routers/mcp_server.py / mcp_endpoint]
end
subgraph "Servidor MCP Edu-Space (Python Standard MCP)"
MCP_TOOLS[MCP Tools: inspect_routes, get_step_guide, get_ui_selectors]
end
subgraph "Inferencia Local (10.0.0.214:8080)"
LLAMACPP[Llama.cpp Qwen3 30B (4 slots)]
end
WIDGET -->|1. Consulta del usuario / Iniciar Guía| ROUTER
ROUTER -->|2. Obtiene directivas guiadas| GUIDE_SRV
ROUTER -->|3. Prompt con herramienta de spotlight| LLAMACPP
ROUTER -->|4. Retorna respuesta + guide_step| WIDGET
WIDGET -->|5. Dispara iluminación visual| SPOTLIGHT
SPOTLIGHT -->|6. Ilumina botón / espera click del usuario| DOM
DOM -->|7. Usuario hace clic| SPOTLIGHT
SPOTLIGHT -->|8. Notifica siguiente paso a UdeCi| WIDGET
MCP_ROUTER -->|Protocolo MCP JSON-RPC| MCP_TOOLS
```
---
### 2. Capas y Componentes a Desarrollar
#### Capa 1: Servidor MCP Institucional (`backend/mcp_server.py` y `backend/routers/mcp.py`)
- Servidor MCP compatible con especificación estándar Anthropic/Open MCP.
- Herramientas (`tools`):
1. `get_application_routes`: Lista las URLs canónicas y vistas del sistema.
2. `get_canonical_9_steps`: Devuelve la secuencia exacta de 9 pasos con sus entidades y URLs.
3. `get_step_guide(action: str)`: Devuelve la lista ordenada de micro-pasos para acciones críticas (`crear_sede`, `crear_aula`, `crear_ciclo`, `crear_comision`, `crear_reserva`).
4. `get_ui_selectors(page: str)`: Mapea los botones y campos interactivos clave para cada vista.
- Endpoint HTTP/JSON-RPC montado en FastAPI `/api/v1/mcp` para inspección de clientes y herramientas de agentes.
#### Capa 2: Servicio de Guías Interactivas (`backend/app/services/guide_service.py`)
- Catálogo declarativo de pasos y selectores para las acciones clave:
- **Crear Sede**: Ir a `/buildings`, iluminar `#btnNewBuildingModal` o `[data-bs-target="#newBuildingModal"]`, iluminar campo `#buildingName`, iluminar `#btnSaveBuilding`.
- **Crear Aula**: Ir a `/classrooms`, iluminar `#btnCreateClassroom`, iluminar campos de tipo/aforo, iluminar botón Guardar.
- **Crear Ciclo Lectivo**: Ir a `/admin/academic_periods`, iluminar botón de nuevo período, etc.
- Inyección de metadatos de guía en `ChatResponse`:
```json
{
"response": "Para crear un aula nueva, haz clic en el botón '+ Nueva Aula' que he iluminado en la pantalla.",
"quick_options": ["Siguiente paso", "Cancelar guía"],
"guide_step": {
"target_url": "/classrooms/list_classrooms",
"selector": "#btnOpenCreateClassroomModal",
"message": "Paso 1: Haz clic aquí para abrir el formulario de creación de aula.",
"expected_action": "click",
"step_number": 1,
"total_steps": 3
}
}
```
#### Capa 3: Motor de Spotlight y Walkthrough en Frontend (`frontend/public/js/walkthrough-engine.js` y `frontend/public/css/walkthrough.css`)
- **Spotlight Visual**:
- Máscara oscura semitransparente (`.walkthrough-backdrop`) o halo luminoso con animación de pulso (`.walkthrough-highlight`).
- Tarjeta flotante interactiva (`.walkthrough-tooltip`) anclada con `Popper` o posicionamiento dinámico sobre el elemento, con número de paso, botón de "Cerrar" y mensaje de UdeCi.
- Scroll automático suave (`element.scrollIntoView({ behavior: 'smooth', block: 'center' })`).
- Detección del evento de interacción del usuario (click / input): cuando el usuario hace la acción requerida, el halo emite un destello de éxito y avanza al siguiente paso.
- **Soporte Responsive (Desktop y Mobile)**:
- Desktop: Spotlight completo con tooltip dinámico flotante.
- Mobile (<768px): Barra guía fija inferior (*Floating Guide Banner*) con indicación clara y botón táctil destacado para evitar descalces de pantalla táctil.
- **Soporte de Contrastes en Modo Oscuro y Claro**:
- Modo Oscuro: Borde `#ec4899` / `#a855f7` brillante con resplandor `box-shadow: 0 0 25px rgba(236, 72, 153, 0.6)`.
- Modo Claro: Resplandor púrpura/magenta UniCABA `#B43E8E` sobre fondo de alto contraste con texto oscuro legible `#1e293b`.
#### Capa 4: Integración en UdeCi Chat Widget (`frontend/views/partials/ai_chat_widget.html`)
- Cuando una guía está en curso, el chat widget se minimiza automáticamente a una píldora discreta o modo "Acompañante", para que el usuario tenga el 100% de la pantalla despejada para realizar la acción.