91 lines
4.8 KiB
Markdown
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.
|