feat: servidor mcp institucional y asistente interactivo guiado con spotlight didactico (SDD-011, v3.8.27)
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user