5.4 KiB
5.4 KiB
Desglose de Tareas: Asistente IA y Chatbot de Ayuda Contextual (SDD-009)
Tareas de Implementación
-
Tarea 1: Esquemas Pydantic v2 y Modelos de Contrato para Chatbot y Configuración
- Estimación: 20 min
- Acciones:
- Crear
backend/schemas/ai_chat.pyconChatMessage,ChatRequest,ChatResponse,AISettingsSchemay validaciones estrictas (Field,pattern,min_length). - Validar que los payloads inválidos fallen con 422 Unprocessable Entity.
- Crear
- Hecho cuando: Los modelos validan correctamente los tipos, roles y longitudes, y rechazan payloads sin mensajes o con roles inválidos.
-
Tarea 2: Lógica de Negocio de System Prompts por Rol y Router FastAPI (
backend/routers/ai_chat.py)- Estimación: 30 min
- Acciones:
- Crear
backend/routers/ai_chat.pyconAPIRouter(prefix="/api/chat", tags=["AI Chatbot"])y alias/api/v1/chat. - Implementar
generate_system_prompt_for_role(role: str) -> strcon los manuales operativos para:Docente: Reserva de aulas, actas de regularidad, asistencia, links a Meet.Alumno: Consulta de horarios, cartelera, notas en Gradebook, prohibición explícita de gestión administrativa.Bedelía / Admin: Circuito secuencial de 9 pasos, resolución de conflictos, importación de sheets, Moodle 4.1.
- Implementar endpoint
POST /conhttpx.AsyncClient(timeout=...)hacia la URL base de Llama.cpp (http://10.0.0.214:8080/v1/chat/completions). - Manejar excepciones de red y timeout mapeando a HTTP 503 controlado.
- Implementar endpoint
POST /test-connectionpara probar el servidor local. - Registrar el router en
backend/main.py.
- Crear
- Hecho cuando: Los endpoints
/api/chaty/api/v1/chatestán documentados en Swagger/docsy procesan consultas asíncronas con System Prompt inyectado.
-
Tarea 3: Persistencia y Gestión de Configuración de IA en
backend/routers/admin.py- Estimación: 25 min
- Acciones:
- Extender
get_all_settingsenbackend/routers/admin.pypara devolver el objetoai_assistantcon parámetros de Llama.cpp, modelo (qwen3-coder:30b) y API key enmascarada. - Crear endpoints
@admin_router.post("/settings/ai")y@admin_router.post("/settings/ai/test")que guarden enSystemSettingcon auditoría enAuditLog.
- Extender
- Hecho cuando: La configuración de IA se guarda y se recupera correctamente a través de la API administrativa.
-
Tarea 4: Pestaña de Configuración Global en Frontend (
global_config.html)- Estimación: 25 min
- Acciones:
- Agregar pestaña
#tab-ai("Asistente IA & LLM Local") enfrontend/views/admin/settings/global_config.html. - Maquetar formulario con los parámetros definidos en SDD-009: Base URL, API Key, Model ID, Model Name, Context Limit, Output Limit, Timeout, Temperatura y switch de habilitación.
- Implementar manejadores JavaScript en la vista para guardar configuración y ejecutar el botón "Probar Conexión con Llama.cpp" con feedback interactivo.
- Agregar pestaña
- Hecho cuando: El administrador puede editar los parámetros del LLM y probar la conexión desde
/admin/settings.
-
Tarea 5: Widget Flotante del Chatbot en la UI (
ai_chat_widget.html&ai-chat-widget.js)- Estimación: 30 min
- Acciones:
- Crear
frontend/views/partials/ai_chat_widget.htmle incluirlo enfrontend/views/base.htmlpara usuarios autenticados. - Diseñar interfaz flotante premium con Bootstrap 5 y Vanilla CSS (botón lanzador con animación sutil, ventana de chat responsiva, badge de rol de usuario, avatar institucional, indicador de tipeo y lista de mensajes).
- Desarrollar
frontend/public/js/ai-chat-widget.jspara enviar mensajes por AJAX a/api/v1/chat/, manejar scroll, formatear respuestas y persistir temporalmente la sesión ensessionStorage.
- Crear
- Hecho cuando: El usuario puede interactuar con el chatbot desde cualquier pantalla del sistema, recibiendo respuestas contextualizadas a su rol.
-
Tarea 6: Suite de Pruebas Automatizadas en Backend (
test_ai_chat.py)- Estimación: 25 min
- Acciones:
- Crear
backend/tests/test_ai_chat.pycon tests para:- Validación de esquemas Pydantic
ChatRequest,ChatMessage,ChatResponse. - Inyección correcta de system prompt según rol (alumno, docente, bedelia).
- Mocking de
httpx.AsyncClientpara simular respuesta 200 de Llama.cpp. - Mocking de falla de conexión para verificar HTTP 503 descriptivo.
- Endpoints de guardado y consulta de configuración de IA.
- Validación de esquemas Pydantic
- Ejecutar
pytest tests -vy validar 100% verde (89 tests pasando). - Verificar con
py_compile(Principio 10) que haya 0 errores o advertencias.
- Crear
- Hecho cuando: Todas las pruebas unitarias e integradas pasan con éxito y no hay problemas en el analizador de código.
-
Tarea 7: Bump Semántico a v3.8.24, Git Push y Despliegue en Producción
- Estimación: 20 min
- Acciones:
- Incrementar versión semántica a
v3.8.24enpackage.json,app.js,__init__.py,setup.pyyopenapi.py. - Actualizar
CHANGELOG.mdyMEMORY.md. - Ejecutar
git add ., commit ygit push origin dev. - Desplegar en el contenedor de producción LXC
10.0.0.217(https://eduspace.oemspot.com.ar) y verificar HTTP 200 en/versiony/admin/settings.
- Incrementar versión semántica a
- Hecho cuando: La versión
v3.8.24está activa en producción y verificada en caliente.