# Pendientes priorizados del RAG **Ultima actualizacion:** 2026-09-11 **Responsable de la priorizacion:** Usuario **Estado:** Activo Este documento es la fuente canonica del orden de trabajo pendiente del modulo RAG. La numeracion ya refleja la prioridad final indicada por el usuario. ## 1. Documentacion y descubrimiento de la API **Estado:** Completado y validado definitivamente en produccion el 2026-09-08. - Implementar `/help` o una especificacion OpenAPI consultable. - Actualizar documentos desfasados que todavia muestran como pendientes funciones ya desplegadas, como playground, logs y cleanup. - Documentar los contratos, parametros, respuestas y errores reales de todos los endpoints. - Mantener la documentacion alineada con produccion para que agentes e integradores no tengan que reconstruir el comportamiento desde el codigo. ## 2. Ciclo de vida del conocimiento **Estado:** Implementado y desplegado; bloqueado por la preparacion operativa de PostgreSQL y la migracion controlada del corpus. El contrato de implementacion esta cerrado en [`CONTRATO_CICLO_VIDA_Y_OCR.md`](./CONTRATO_CICLO_VIDA_Y_OCR.md). Antes de ejecutar las pruebas de migracion o activar el ciclo de vida hay que completar este prerrequisito: ### Prerrequisito bloqueante: preparar PostgreSQL - Confirmar que existe la instancia y la base de datos que usara RAG en EasyPanel. - Obtener el hostname interno, puerto, nombre de base de datos, usuario y requisitos SSL. - Configurar `POSTGRES_URL`, `POSTGRES_SSL` y `LIFECYCLE_ADMIN_TOKEN` en el servicio RAG. - Arrancar las migraciones del esquema y verificar las tablas, permisos y `SELECT 1` desde RAG. - Revisar que no falten variables, red interna, credenciales, almacenamiento persistente o permisos de migracion. La configuracion de backups queda diferida al paquete del punto 7. - Inventariar las fuentes actuales de Qdrant y preparar su carga en el catalogo PostgreSQL. No ejecutar la migracion legacy, activar enforcement ni iniciar OCR hasta cerrar este prerrequisito. - Crear un catalogo de fuentes y versiones ingeridas. - Saber que documento esta vigente, obsoleto, reemplazado o pendiente de reingesta. - Evitar duplicados y permitir actualizaciones incrementales controladas. - Registrar fecha de indexacion, modelo de embeddings, proveedor y version del contenido. - Facilitar el reemplazo o rollback de una fuente sin depender de operaciones manuales dificiles de auditar. ### Paquete de mejora posterior: seguimiento del corpus en API y frontend **Prioridad:** Diferida, sin urgencia; no bloquea la preparacion de PostgreSQL ni el cierre funcional del punto 2. Retomar al trabajar en el frontend de gestion. - Exponer por API los documentos que componen cada version de una fuente. - Exponer el historial de intentos de ingesta, resultados y errores. - Incluir fechas y detalles de error de las versiones en las respuestas de la API. - Ampliar la vista basica del playground a una gestion de fuentes, documentos, versiones e ingestas con su estado e historial. - Incorporar al frontend las operaciones ya disponibles por API: activacion, rollback, reintento y purga. ## 3. OCR integrado en la ingesta **Diseño:** Contrato de implementacion cerrado en [`CONTRATO_CICLO_VIDA_Y_OCR.md`](./CONTRATO_CICLO_VIDA_Y_OCR.md). Su ejecucion queda bloqueada hasta completar el punto 2. - Detectar PDFs con capturas, imagenes o una capa textual insuficiente. - Ejecutar OCR automaticamente o bloquear la ingesta para revision cuando no pueda garantizarse la cobertura. - Generar un documento intermedio auditable cuando sea necesario. - Verificar el resultado antes de sustituir una fuente vigente. - Evitar que se repita el problema detectado con el PDF de FacturaTech. ## 4. Mejora del retrieval - Anadir busqueda hibrida semantica y textual para codigos exactos como `FAT07`, `504` o `SQLSTATE[23505]`. - Mejorar el ranking usando coincidencias de codigo, regla, modulo y mensaje, no solo proximidad semantica. - Crear un conjunto estable de consultas de evaluacion basado en casos reales. - Medir precision, resultados irrelevantes y consultas ambiguas. - Refinar retrieval y chunking con evidencia de uso, no mediante cambios generales sin medicion. ## 5. Seguridad de la API - Anadir autenticacion para consumidores autorizados. - Proteger especialmente uploads, cleanup y operaciones sobre logs. - Aplicar rate limiting y limites de tamano o tipo de archivo. - Revisar CORS, exposicion publica, registros sensibles y permisos por operacion. - Sustituir la configuracion sin credenciales de n8n cuando exista el mecanismo de autenticacion definitivo. - Actualizar Express/`qs` para cerrar los avisos moderados pendientes de `npm audit`. ## 6. Pruebas automatizadas - Incorporar un framework y scripts de pruebas; actualmente el proyecto no tiene suite automatizada. - Cubrir ingesta, parsing, chunking, scopes, cleanup y retrieval. - Probar contratos y respuestas de error de la API. - Anadir pruebas de regresion con consultas reales como las validadas para FacturaTech. - Separar pruebas unitarias, de integracion y verificaciones opcionales contra servicios remotos. ## 7. Operacion y mantenimiento - Resolver la colision de `sourceRef` al ingerir carpetas homonimas. - Separar claramente configuracion versionable y secretos locales. - Verificar y cerrar documentalmente la migracion del repositorio raiz de RAG y su despliegue en EasyPanel. - Revisar copias temporales o backups asociados a la migracion antes de eliminarlos. - Mantener un procedimiento fiable de despliegue, verificacion y rollback. ### Paquete de mejora posterior: backups manuales del RAG **Prioridad:** Diferida, sin urgencia; no bloquea la preparacion actual de PostgreSQL. Sin programacion automatica. - Configurar el destino de backups y diagnosticar el error observado al crearlo en EasyPanel. - Preparar copias manuales de la nueva base del RAG y snapshots de Qdrant; `db_gestion_flujos_n8n` es ajena a este alcance. - Definir una ventana sin escrituras para obtener copias coherentes de ambos almacenes. - Documentar y comprobar la restauracion, incluyendo la recuperacion de los permisos necesarios. - Este paquete difiere la solucion habitual de backups; el snapshot previo exigido por la migracion legacy sigue formando parte de esa operacion. ## 8. Sistema de evaluacion - Revisar periodicamente los logs de evaluacion almacenados en Qdrant. - Convertir incidencias reales en casos de prueba permanentes. - Anadir metricas de recuperacion, calidad y contexto insuficiente. - Mantener trazabilidad entre una incidencia, el cambio aplicado y la validacion posterior. - Diferenciar claramente observacion manual, alerta automatica y regresion confirmada. ## 9. Capa MCP - Exponer capacidades del RAG como tools MCP reutilizables. - Definir inicialmente retrieval y consulta de fuentes; limitar operaciones destructivas. - Mantener HTTP como API base y MCP como adaptador, evitando duplicar la logica del servicio. - Definir autenticacion, contratos y permisos antes de exponer operaciones adicionales. ## 10. Modelo de `answer` - Evaluar y sustituir `openai/gpt-4.1-mini` por el modelo definitivo de respuesta. - Comparar calidad, coste, latencia y dependencia del proveedor. - Mantener `answer` construido sobre `retrieve` y evitar un segundo camino de recuperacion. - Considerar esta tarea despues de las anteriores; integraciones como WhatsApp ya pueden usar `/retrieve` y dejar la respuesta final a su propio agente. ## Regla de mantenimiento - No cambiar este orden sin confirmacion del usuario. - Al completar un punto, registrar evidencia y marcar su estado sin renumerar silenciosamente los demas. - Las tareas detalladas pueden vivir en documentos independientes, pero este archivo conserva la prioridad global del modulo.