# Pendientes priorizados del RAG **Ultima actualizacion:** 2026-09-24 **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. ## Hoja de ruta OCR prioritaria Esta secuencia tiene prioridad sobre la aceptacion productiva pendiente de FacturaTech. No cerrar v4, crear una candidata nueva, reingestar FacturaTech, aprobar, indexar ni activar contenido fuera del orden indicado. ### Fase 1. Corregir y verificar el codigo **Estado:** Completada funcionalmente y verificada en produccion el 2026-09-17. 1. Completado: errores OCR estructurados, seguros y accionables. 2. Completado: recuperacion administrativa autenticada y auditada para candidatas con evidencia invalida. 3. Completado: RAG y OCR exponen versiones; los digests identifican las imagenes desplegadas. 4. Completado: errores, recuperacion, reinicios y versiones cubiertos localmente y verificados en produccion sin modificar v4. **Salida:** el comportamiento nuevo esta validado y v4 permanece intacta. La etiqueta OCI de revision legible sigue como mejora operativa no bloqueante: actualmente el digest es la identidad verificable de la imagen. ### Fase 2. Resolver la candidata v4 **Estado:** Completada en produccion el 2026-09-20, con aprobacion explicita del usuario. 1. Completado: v4 respondio `409 OCR_ARTIFACT_UNAVAILABLE` y accion `use_admin_recovery` mediante el contrato autenticado. 2. Completado: confirmada la ausencia de la evidencia durable necesaria para su revision. 3. Completado: recuperacion administrativa auditada aplicada sobre la unica candidata heredada. 4. Completado: v4 quedo en estado `failed`, no activa, sin indexacion ni activacion; la fuente conserva su version activa. 5. Completado: no quedan candidatas `pending`, `indexing` ni `review_required` que bloqueen la fuente. **Salida:** v4 queda resuelta de forma auditable como `failed`, sin crear otra candidata. ### Fase 3. Hardening OCR y aceptacion de FacturaTech **Estado:** `0.2.1` desplegada y verificada conjuntamente en produccion. v8 completo la aceptacion no activa y esta `READY_FOR_APPROVAL`; la aprobacion/indexacion y la activacion permanecen separadas y requieren sus autorizaciones. La candidata v5 `5f2317c6-7a8a-4e08-a614-f8189602ebb8` completo 25/25 paginas OCR, pero fallo despues cuando RAG solicito 25 imagenes de revision en paralelo. El rerender concurrente provoco un `SIGSEGV` de PDFium/FreeType, salida `139` y reinicio del contenedor; no hubo OOM. La candidata quedo fallida y la version activa no cambio. #### Fase 3A. Hardening del runtime 1. Completado localmente: cola SQLite durable con un unico worker real y recuperacion tras reinicio. 2. Completado localmente: PNG privados durante el render inicial y servicio desde fichero sin volver a ejecutar PDFium. 3. Completado localmente: transferencia RAG secuencial, idempotente y reanudable mediante comprobantes privados por pagina. 4. Completado localmente: exclusion mutua defensiva de PDFium y cierre determinista de recursos. 5. Completado localmente: observabilidad segura, limites de cola/tiempo/disco, recuperacion por lease, sweeper periodico y vacuum incremental. 6. Completado: validacion independiente con PDF real de 25 paginas, reinicio durante el trabajo, concurrencia, reanudacion, ausencia de duplicados y limpieza cuantitativa. #### Fase 3B. Aceptacion productiva **Estado:** Ejecutada y no superada. v6 fallo por colision idempotente con un trabajo terminal `ocr-v1`. Tras la limpieza automatica, v7 proceso 25/25 paginas y persistio 25 PNG validos, pero un falso negativo de `p10Confidence` la cerro como `OCR_QUALITY_BLOCKED`. Las 34 entradas estan presentes; `FAT07`, `NSAV06` y `DSAU04` requieren correccion humana por confusion `0/o`. La version activa no cambio. 1. Completado: desplegados juntos OCR y RAG `0.2.0` con revision verificable. 2. Completado: candidatas v6 y v7 creadas con `activate=false`; ninguna fue indexada ni activada. 3. Completado: evidencia durable de v7, 25 imagenes y 34 entradas verificadas. 4. No superado: la puerta de calidad impidio llegar a revision y dos de los cuatro codigos criticos no son exactos antes de correccion humana. 5. Completado: version activa anterior confirmada intacta. #### Fase 3C. Correccion post-aceptacion `0.2.1` **Estado:** R1-R5 completados. `0.2.1` se centralizo en `VERSION`, supero la validacion local y se desplego conjuntamente en produccion con revision y digests verificables. La migracion `004`, health, cola, almacenamiento, PostgreSQL, Qdrant y reconciliador quedaron sanos. v8 completo la aceptacion no activa y conserva las correcciones conocidas pendientes de aplicar durante su revision. Contrato completo en `CONTRATO_CICLO_VIDA_Y_OCR.md`, anexo "Hallazgos productivos v6-v7". 1. Completado localmente: R1, identidad `ocr-v2` completa, acknowledgement de los cuatro estados, recuperacion posterior a `succeeded` sin reenviar OCR y rechazo fail-closed de respuestas incompatibles. 2. Completado localmente: R2, `p10Confidence` bajo aislado como advertencia, bloqueos reales preservados y diagnostico determinista por pagina. 3. Completado localmente: R3, migracion `004` preparada sin aplicar, cadena de hashes durable, `quality-report.json` privado e inmutable y diagnostico seguro. 4. Completado localmente: R4, suites, revision independiente, fixture autocontenido de 25 paginas, simulaciones de recuperacion tras cada frontera de persistencia y hardening de errores administrativos. `004` se aplico mediante el runner en PostgreSQL Docker local aislado despues de controlar `001-003`; se verificaron la fila historica, columnas, restriccion, historial `001-004` e idempotencia. El contenedor reutilizable queda detenido; nunca se uso EasyPanel ni produccion. 5. Completado: R5 consumio `0.2.1` desde un unico `VERSION`, valido health y etiquetas OCI, desplego y probo RAG/OCR como una unica operacion y completo la aceptacion no activa con revision visual independiente del agente. #### Checklist ejecutable de R5 R5 esta completada hasta `READY_FOR_APPROVAL`. La aprobacion/indexacion y la activacion de v8 siguen pendientes y conservan autorizaciones separadas. - [x] Crear `VERSION` en la raiz con `0.2.1` y convertirlo en la unica fuente de version para RAG, OCR, health, pruebas y builds; cualquier version duplicada o divergente debe fallar. - [x] Ejecutar la validacion local completa de RAG, OCR e imagenes y actualizar la documentacion afectada. - [x] Revisar el worktree, crear un unico commit de entrega y hacer push a `main`; RAG y OCR se publicaron desde `0654ce5` y el registro documental se completo en `ec0d233`. - [x] Antes del despliegue, identificar explicitamente la base y el entorno productivos, revisar `rag_schema_migrations` y confirmar que solo estan pendientes las migraciones esperadas. Preflight de solo lectura en VPS2 (2026-09-23): RAG usa `db_rag` con el rol `usr_rag`; `001-003` estan aplicadas con checksums coincidentes y solo queda `004_ocr_quality_diagnostics.sql`. - [x] Configurar en ambos servicios `BUILD_REVISION=` y mantener `OCR_INGEST_ENABLED=true`. Ambos servicios se construyeron con `BUILD_REVISION=0654ce5` y RAG conserva OCR habilitado. - [x] Desplegar RAG y OCR desde el mismo commit como una unica operacion en EasyPanel; ambos servicios quedaron en ejecucion el 2026-09-23 con `BUILD_REVISION=0654ce5` y OCR habilitado. - [x] Verificar conjuntamente `version=0.2.1`, revision, etiquetas OCI, digests, migracion `004`, health, cola OCR, almacenamiento, PostgreSQL, Qdrant y reconciliador. RAG: `sha256:9a22730406c09c6b773891d8953f451e6263bf9fb0033188f4479f0b93ec8bbf`; OCR: `sha256:6725991d3893a4f16ae6c75f28e9dd59b051bdbc344b28d79f1292224ddceda1`. Ambos exponen `0.2.1` y `0654ce5`; `004` esta aplicada, OCR esta `live/ready`, cola vacia y almacenamiento disponible. - [x] Confirmar el estado auditado de v7 sin aprobarla, indexarla ni activarla. v7 `c9756e59-f91d-4b57-8f31-e7b5b2b09558` sigue `failed` por `OCR_QUALITY_BLOCKED`, conserva artefactos y la version activa anterior `3fc78163-9cfb-4979-985c-1520a63327b0` permanece intacta. - [x] Crear una candidata nueva de FacturaTech con `activate=false` y supervisarla hasta `review_required` o fallo. v8 `f4fd1502-1d4d-454f-bbfb-4c3b6820ee97` alcanzo `review_required` sin activacion: 25/25 paginas OCR, 25 imagenes verificadas, 22 paginas aceptadas, tres advertencias `LOW_P10_CONFIDENCE` (2, 20 y 21) y cero bloqueos. - [x] Ejecutar y reauditar la revision visual independiente definida en el contrato: v8 se revalido antes y despues, se descargaron temporalmente 25 imagenes, un modelo visual las transcribio sin recibir primero el OCR productivo, y se compararon despues imagen/candidata/referencia. La auditoria con un modelo mas potente corrigio el veredicto inicial: resultado `READY_FOR_APPROVAL`, 34/34 entradas, cero duplicados, cero ausencias y cero casos sin resolver. `CBG04a` y `DSAU08` ya son exactos; deben proponerse `FATo7` -> `FAT07`, `NSAvo6` -> `NSAV06` y `DSAUo4` -> `DSAU04`. El recorte de la pagina 22 pertenece a la imagen fuente y la candidata conserva el contenido visible. No hubo cambios productivos. - [ ] Solicitar autorizacion separada antes de aprobar o indexar y una confirmacion adicional antes de activar. #### Plan ejecutable Antes de ejecutar este plan, leer `SISTEMA_RAG_BASE.md`, esta seccion y el bloque `Revision de FacturaTech` de `CONTRATO_CICLO_VIDA_Y_OCR.md`. No desplegar, aprobar, indexar ni activar sin la autorizacion correspondiente. ##### A. Diagnostico de las confusiones `o/0` - completado Este diagnostico se completo sin modificar codigo, configuracion, modelos, preprocesado, reconstruccion ni postproceso. 1. [x] Revalidar las referencias exactas: `FAT07` en pagina 8, `NSAV06` en pagina 15 y `DSAU04` en pagina 16; mantener separadas estas confusiones de precision de las advertencias `LOW_P10_CONFIDENCE` de las paginas 2, 20 y 21. 2. [x] Inventariar la evidencia durable ya existente para las paginas 8, 15 y 16: imagenes, resultado OCR, lineas, bounding boxes, confianzas, manifiestos, hashes, candidata y configuracion efectiva. 3. [x] Mapear el recorrido exacto del dato entre PDF, render a 200 DPI, entrada del reconocedor, adaptador de PaddleOCR, respuesta API, artefacto durable de RAG, reconstruccion de lineas y candidata. 4. [x] Construir una linea base por pagina e identificar la primera frontera observable de cada diferencia. 5. [x] Confirmar que los artefactos productivos existentes bastan para localizar la causa. 6. [x] Descartar la repeticion focalizada: no fue necesaria porque la evidencia durable resulto suficiente. 7. [x] Comparar imagen, respuesta OCR, artefactos RAG y candidata y clasificar la causa. 8. [x] Registrar confianzas, limites de reproducibilidad y efectos sobre el quality gate. 9. [x] Redactar el informe de diagnostico. 10. [x] Presentar el informe y obtener la aceptacion del usuario. **Resultado:** los PNG verificados muestran `FAT07`, `NSAV06` y `DSAU04`; `ocr-result.json` ya contiene `FATo7`, `NSAvo6` y `DSAUo4`, con confianzas de linea `0.9775`, `0.9903` y `0.9808`. `candidate-pages.json` conserva exactamente esos valores. La primera frontera observable es imagen correcta -> reconocimiento PaddleOCR incorrecto. RAG, la reconstruccion y la composicion no sustituyen caracteres. **Decision de aceptacion:** para la fase actual se acepta el OCR como servicio best-effort autonomo. Estos errores semanticos puntuales de alta confianza son una limitacion conocida, no un bloqueo tecnico. La ingesta sera orquestada por un agente y no dependera de una GUI ni de una persona corrigiendo cada documento. Esto no convierte el texto OCR en exacto ni elimina las correcciones y autorizaciones requeridas para una candidata concreta. ##### B. Mejora futura de precision OCR - no bloqueante Este bloque queda diferido. No forma parte del cierre operativo actual y solo se reabrira con una decision explicita. - [ ] Comparar sobre la linea base alternativas acotadas y generales, por ejemplo resolucion o preprocesado de imagen, configuracion del reconocedor o tratamiento de caracteres ambiguos respaldado por confianza y evidencia visual. - [ ] Elegir la intervencion minima que actue en la etapa donde se demostro la causa. Documentar por que se descartan las demas alternativas y su impacto esperado en tiempo, memoria y compatibilidad. - [ ] Implementar la mejora sin reglas especificas para FacturaTech ni sustituciones silenciosas como cambiar toda `o` por `0`. - [ ] Conservar identidad, hashes, orden de lineas, bounding boxes, metricas, idempotencia y contrato `ocr-v2`; si la configuracion efectiva cambia semanticamente, versionarla y no reutilizar trabajos incompatibles. - [ ] Mantener separadas la mejora general del OCR y las correcciones exactas que requiere la candidata v8. La implementacion no modifica por si sola la candidata ya creada. ##### C. Validacion futura de mejoras de precision - no bloqueante Este bloque se ejecutara solo si se implementa el bloque B. - [ ] Crear fixtures no sensibles que reproduzcan caracteres ambiguos en codigos y texto normal, con casos donde `o`, `O`, `0`, `u` y `U` sean correctos y deban conservarse. - [ ] Ejecutar pruebas unitarias y de integracion sobre renderizado, reconocimiento, reconstruccion y resultado API segun la etapa modificada. - [ ] Repetir, con autorizacion y fuera del repositorio, el OCR real exclusivamente para las paginas `[8, 15, 16]`; exigir `FAT07`, `NSAV06` y `DSAU04` exactos y confirmar que no se degradan el resto de sus lineas, posiciones ni metricas relevantes. - [ ] Comparar antes y despues con evidencia estructurada. La mejora no pasa si solo corrige los tres tokens mediante una regla particular, introduce falsos cambios `o/0` o `u/U`, pierde contenido o rompe identidades y hashes. - [ ] Medir tiempo y memoria de las tres paginas y ejecutar la suite Python completa. Si la alternativa aumenta materialmente el coste, justificarlo antes de integrarla. ##### D. Seguimiento rapido RAG -> OCR - siguiente bloque - [x] Disenar un scheduler durable en RAG que use `next_attempt_at` como reloj de los trabajos OCR pendientes y mantenga un unico temporizador para el vencimiento mas cercano. - [x] Al despertar, reclamar trabajos vencidos mediante PostgreSQL y `FOR UPDATE SKIP LOCKED`, consultar el estado remoto y reprogramar solo `queued` o `running` con backoff de 2 a 15 segundos. - [x] Finalizar y dejar de seguir inmediatamente los trabajos `succeeded` o `failed`; conservar la transferencia durable, validacion de identidad y composicion existentes. - [x] Reconstruir el scheduler al arrancar RAG y mantener `dispatchAvailable()` idempotente ante llamadas simultaneas. - [x] Mantener el reconciliador de cinco minutos como red de seguridad global; no convertirlo en el mecanismo normal de latencia ni detenerlo cuando termine un trabajo. - [x] Eliminar `pollUntilTerminal()` y su prueba especifica: el scheduler no usa un bucle en memoria sin limite, persistencia ni renovacion de lease. El dispatcher conserva las consultas discretas y persiste el backoff mediante `next_attempt_at`. - [x] Retirar `OCR_PAGE_TIMEOUT_MS` y `OCR_TOTAL_TIMEOUT_MS`: eran configuracion no consumida y no representaban garantias reales del runtime RAG. ##### E. Validacion local conjunta - [x] Probar que un trabajo que termina antes de cinco minutos se recupera en el siguiente intervalo corto sin esperar al reconciliador. - [x] Probar secuencias `queued -> running -> succeeded` y `queued -> failed`, y que no quedan temporizadores activos para trabajos terminales. - [x] Probar reinicio de RAG entre consultas: `next_attempt_at`, `remoteJobId` e idempotency key permiten continuar sin repetir PaddleOCR. - [x] Probar dos dispatchers concurrentes y confirmar que `SKIP LOCKED`, leases y `activeDrain` evitan doble procesamiento. - [x] Probar caida durante resultado, imagenes, informe y candidata; el reconciliador de cinco minutos sigue recuperando exactamente una vez. - [x] Ejecutar una ingesta local end-to-end con un PDF controlado que combine paginas nativas y paginas OCR. La ejecucion fresca `94f1af75-b6b0-4fb1-8a93-f0f5c0c5f0a0` alcanzo `review_required` en 7 segundos: pagina 1 nativa, pagina 2 OCR, `2/2`, quality report y candidata durables, revision autenticada e imagen protegida correctas, `activateRequested=false` y cola OCR vacia. La prueba descubrio y corrigio el doble conteo de paginas OCR clasificadas como blank y la exigencia incorrecta de imagen OCR para paginas nativas. - [x] Ejecutar suites Node/Python, regresiones focalizadas, chequeos de tipos, build de RAG y OCR, health de contenedores, validacion de imagenes y `git diff --check` antes de publicar. Validacion completada: suite Node `121/121`, suite OCR `26/26`, regresiones del scheduler y reconciliador, `npm run check`, build RAG, PostgreSQL local con cuatro migraciones, builds finales de ambas imagenes `0.2.1`, health OCR con modelo, worker, sweeper y almacenamiento preparados, imagen de revision correcta y `git diff --check` superado. La revision final corrigio el `documentId` de las correcciones del playground, la nulabilidad OpenAPI 3.1 y las incoherencias de contrato y rollback. No existe Qdrant local: Qdrant y el health RAG completo se verifican exclusivamente en el gate productivo posterior al despliegue autorizado. ##### F. Publicacion y despliegue conjunto - [x] Preparar una unidad versionada para el scheduler durable y la operacion autonoma, revisar el diff y registrar codigo, pruebas, contrato, operativa y rollback. - [x] Solicitar y recibir autorizacion para commit/push. El despliegue conserva una autorizacion explicita posterior y separada. - [ ] Publicar y desplegar RAG/OCR juntos segun la regla operativa vigente, con OCR habilitado y version, revision, etiquetas y digests coincidentes. - [ ] Verificar migraciones esperadas, health, scheduler rapido, reconciliador de cinco minutos, cola OCR, almacenamiento, PostgreSQL y Qdrant. Ante fallo, revertir RAG y OCR como una unidad y conservar intacta la version activa. ##### G. Validacion productiva sin activar contenido - [ ] Ejecutar una ingesta productiva controlada y no activa para validar el circuito RAG -> OCR -> RAG, incluyendo que el scheduler recupera el resultado en el intervalo corto sin esperar cinco minutos. - [ ] Verificar seleccion de paginas, composicion, informe de calidad, candidata revisable, ausencia de activacion y continuidad del reconciliador como fallback. - [ ] Confirmar que cualquier error semantico residual conserva imagen, texto, lineas, bounding boxes, confianzas, hashes y trazabilidad suficientes para revision posterior; no exigir exactitud textual total al OCR best-effort. - [ ] Registrar IDs, estados, tiempos, hashes, versiones, revisiones y digests sin incorporar contenido del cliente al repositorio. ##### H. Cierre de FacturaTech v8 - [ ] Revalidar antes de aprobar que v8 sigue `review_required`, que no cambio su `candidateSha256`, que `activateRequested=false` y que la activa coincide con `baseActiveVersionId`. - [ ] Preparar el payload exacto de correcciones por linea, incluyendo hashes vigentes, sin aplicarlo todavia. - [ ] Solicitar autorizacion explicita para aprobar e indexar v8 con las correcciones verificadas. - [ ] Tras la autorizacion, aprobar, generar el artefacto revisado, crear chunks y embeddings, escribir Qdrant y verificar estado `ready` con recuentos correctos. - [ ] Solicitar una segunda autorizacion para activar v8. - [ ] Tras la autorizacion, activar, verificar retrieval real y conservar rollback hacia `3fc78163-9cfb-4979-985c-1520a63327b0`. ##### I. Criterio de servicio completamente operativo - [ ] Confirmar en produccion que el PDF controlado hibrido no envia las paginas nativas, envia solo las visuales y compone un documento unico sin duplicar texto dentro de una pagina. - [ ] Confirmar que las limitaciones de precision conocidas quedan trazables, el scheduler corto funciona tras reinicio, los leases evitan dobles procesamientos y el reconciliador recupera fallos residuales. - [ ] Confirmar health, observabilidad, almacenamiento, cola, PostgreSQL, Qdrant, revision no activa y rollback documentado sin incidencias abiertas de severidad bloqueante. - [ ] Declarar cerrado el trabajo tecnico solo cuando toda la evidencia anterior este registrada. Este cierre significa que el servicio RAG-OCR esta funcionando completamente; no implica por si mismo aprobar, indexar ni activar FacturaTech v8. Las advertencias `LOW_P10_CONFIDENCE` de las paginas 2, 20 y 21 no son un defecto de comunicacion ni un bloqueo pendiente de codigo. Son senales de revision. Las confusiones puntuales `o/0` de las paginas 8, 15 y 16 son una limitacion aceptada del reconocimiento best-effort y deben corregirse explicitamente en la revision de v8, nunca mediante una autocorreccion silenciosa. Una futura consola podra incorporar revision humana y un revisor visual por IA podra proponer correcciones con imagen y contexto; ambos quedan fuera de esta fase. Si aparece un fallo real cuyos sintomas justifiquen aislar servicios, valorar entonces `OCR_INGEST_ENABLED=false` y el despliegue por etapas. No aplicar ese modo preventivamente. **Regla de despliegue:** R1-R4 no despliegan ni prueban produccion. Solo R5 puede desplegar; RAG y OCR se despliegan juntos con `OCR_INGEST_ENABLED=true` y la entrega no se considera completada hasta que ambos coincidan en version/revision y superen juntos la bateria de salud. No se desactiva OCR ni se despliega por etapas de forma preventiva: ese modo queda reservado para un fallo real cuyos sintomas justifiquen aislar un servicio. `BUILD_REVISION` sigue manual para esta entrega y se contrasta con el commit; los digests son la identidad exacta. No se introduce CI, registry ni automatizacion de EasyPanel sin aprobacion separada. **Regla PostgreSQL de R4:** no usar la base configurada en EasyPanel ni cargar los ficheros locales que contienen sus secretos. Usar un contenedor local aislado y reutilizable, pasar una URL local solo al proceso de prueba y comprobar la secuencia de migraciones. El contenedor conserva su volumen para futuras pruebas, no tiene reinicio automatico y debe quedar detenido al terminar para que PostgreSQL no consuma CPU ni RAM activa. No apagar ni limpiar Docker globalmente. El runner aplica todas las migraciones pendientes. La aplicacion de `004` en produccion pertenece a R5 y necesita autorizacion explicita independiente. **Evidencia:** las pruebas automatizadas deben ser autocontenidas. La comparacion con el documento manual de FacturaTech es evidencia externa producida por el agente mediante un modelo visual independiente y se registra separada del PASS automatizado. R5 debe dejar IDs, estados, recuentos, hashes, versiones, revisiones y digests suficientes para auditar la aceptacion sin depender de memoria conversacional. El SDD `ocr-ingest-integration` se archiva con 29/30 tareas completas y 7.4 incompleta. La continuidad del hardening y de la aceptacion se controla mediante el contrato ODD canónico, sin declarar retrospectivamente superada la aceptacion fallida. **Salida anterior:** `0.2.1` supero los criterios del anexo y FacturaTech alcanzo `review_required` con evidencia completa. El nuevo bloque A-I solo se cierra cuando cumple el criterio de servicio completamente operativo; FacturaTech v8 solo se aprueba o activa con sus autorizaciones explicitas separadas. ## 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:** Completado y validado en produccion el 2026-09-13. 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. - Ejecutar las migraciones del esquema y verificar las tablas, permisos y `SELECT 1` desde RAG. Completado el 2026-09-13. - Revisar que no falten variables, red interna, credenciales, almacenamiento persistente o permisos de migracion. Completado el 2026-09-13; la configuracion completa de backups queda diferida al paquete del punto 7. - Inventariar las fuentes actuales de Qdrant y preparar su carga en el catalogo PostgreSQL. ### Resultado del dry-run legacy - Ejecutado el 2026-09-13 sin `--apply`. - Detectados 22.605 puntos en 7 fuentes de `rag_chunks`. - `ok: true`; no se encontraron `blockedReasons`. - Ventana de mantenimiento ejecutada con `INGEST_WRITES_ENABLED=false` y `rag_system_state.maintenance=true`. - Migracion aplicada con el lote `17f05cae-c5a7-49a5-b3ad-729958e1a342` usando snapshot Qdrant remoto con checksum `a55b13d3b6b791e9b148f87491b9b2788ce5797ee997a9f6be2a6d424eb92302`. - Catalogadas 7 fuentes y 22.605 puntos; todas las versiones quedaron `active` y sus recuentos PostgreSQL/Qdrant coinciden. - `KNOWLEDGE_LIFECYCLE_ENFORCED=true`, `INGEST_WRITES_ENABLED=true`, `maintenance=false` y retrieval validado en produccion. El punto 2 queda cerrado. El punto 3, OCR integrado en la ingesta, puede comenzar respetando el contrato secuencial. - 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). El punto 2 ya fue validado en produccion; su ejecucion queda habilitada. - 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. ### Paquete de mejora posterior: OCR reutilizable para entradas visuales **Prioridad:** Diferida; no bloquea la correccion actual ni la aceptacion de FacturaTech. - Mantener el contrato actual de trabajos PDF. - Aceptar directamente `image/jpeg` y `image/png`, ademas de PDF. - Normalizar cada entrada visual a un resultado por pagina con texto, lineas, posiciones y metricas. - Emitir resultados OCR o errores estructurados sin depender del RAG. - Mantener RAG como consumidor opcional del OCR y responsable de versionado, revision e indexacion de conocimiento. - Definir limites de tamano, dimensiones y paginas, autenticacion, retencion y pruebas para cada formato. ## 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. **Estado de la propuesta:** Diseno guardado para completar e implementar mas adelante. - 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. #### Diseno propuesto - Mantener los datos primarios separados: PostgreSQL conserva el catalogo, Qdrant conserva chunks y embeddings, y un volumen privado del RAG conserva originales y artefactos. - Montar un volumen `rag-ingestions` en `/data/ingestions` para conservar originales, manifiestos y futuros artefactos OCR por version. - Cambiar la ingesta para guardar el original antes de procesarlo; el flujo actual usa `/tmp` y elimina los uploads al terminar. - Respaldar PostgreSQL con un dump portable de `db_rag` y, cuando quede configurado, con Database Backups de EasyPanel hacia un destino S3-compatible. - Respaldar Qdrant con snapshot de la coleccion o del almacenamiento completo, preferentemente hacia el mismo destino externo. - Incluir los artefactos del volumen en el plan de backup y probar una restauracion completa antes de considerar portable el servicio. - No tratar un volumen Docker del mismo VPS como backup externo: protege frente a reinicios, no frente a perdida del servidor. - Mantener fuera de este alcance `db_gestion_flujos_n8n`. ## 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.