rag-service/docs/PENDIENTES_RAG.md

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. 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. 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.