# Pendientes priorizados del RAG **Ultima actualizacion:** 2026-09-25 **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 La prioridad actual es publicar y desplegar la correccion de rechazo/purga OCR, completar la limpieza sin alterar FacturaTech v1 y decidir despues si aporta valor una nueva ingesta del PDF original. No aprobar, indexar ni activar contenido de prueba. ### 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` revision `960e04a5a9fc3a3ef108fa4ef19d5ff42dbdb1ae` desplegada y verificada conjuntamente en produccion. Las candidatas descartadas quedaron purgadas y FacturaTech v1 sigue activa. 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 fue rechazada posteriormente sin aplicar correcciones, indexar ni activar. 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 completo la revision no activa. La decision posterior fue rechazar y purgar v8, no aprobarla ni activarla. - [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. - [x] Resolver el destino de v8: rechazada sin aprobar, indexar ni activar; su purga espera el despliegue de la correccion de claves foraneas. #### 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 requeriria una futura candidata. La implementacion no reabre ni modifica v8, que fue rechazada. ##### 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. - [x] Publicar y desplegar RAG/OCR juntos segun la regla operativa vigente, con OCR habilitado y version, revision y etiquetas coincidentes. El scheduler se desplego en `bfb2d48` y la correccion final de limpieza en `960e04a5a9fc3a3ef108fa4ef19d5ff42dbdb1ae` el 2026-09-25. - [x] Verificar migraciones esperadas, health, scheduler rapido, reconciliador de cinco minutos, cola OCR, almacenamiento, PostgreSQL y Qdrant. La validacion productiva conjunta paso y la version activa permanecio intacta. ##### G. Validacion productiva sin activar contenido - [x] 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. La candidata sintetica valida `c4646668-30e4-409e-800d-23a8ee465a42` alcanzo `review_required` en menos de 18 segundos y el trabajo OCR termino en unos 6 segundos. - [x] Verificar seleccion de paginas, composicion, informe de calidad, candidata revisable, ausencia de activacion y continuidad del reconciliador como fallback. Pagina 1 `native`, pagina 2 `ocr`, `requested_pages={2}`, `next_attempt_at=NULL`, cola vacia y `activateRequested=false`. - [x] 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. La pagina OCR conservo 14 lineas, 333 caracteres no blancos, bounding boxes, confianzas, hashes y PNG durable `1654x2339`. - [x] Registrar IDs, estados, tiempos, hashes, versiones, revisiones y digests sin incorporar contenido del cliente al repositorio. La evidencia completa esta en `docs/HISTORIAL_SESIONES.md`; solo se uso contenido sintetico. ##### H. Limpieza de candidatas OCR y FacturaTech - [x] Confirmar que FacturaTech v1 `3fc78163-9cfb-4979-985c-1520a63327b0` sigue activa e intacta, purgar v2 y rechazar v8 sin indexarla ni activarla. - [x] Corregir la comparacion de `ocr_text_hash` para que las paginas `blank` con texto OCR vacio puedan aprobarse o rechazarse sin falso `REVIEW_CONFLICT`. - [x] Corregir la purga de versiones OCR para eliminar de forma transaccional las filas hijas de `rag_review_corrections`, `rag_document_pages` y `rag_ocr_jobs` antes de `rag_version_documents`, respetando las claves foraneas y la reanudacion desde `purging`. - [x] Eliminar idempotentemente los artefactos duraderos de la version antes de completar `purging -> purged`, evitando directorios huerfanos marcados como `retention_deleted`. - [x] Anadir pruebas de regresion para ambos defectos y ejecutar la bateria local completa. Las regresiones finales `47/47`, Node `124/124`, OCR `26/26`, typecheck, build y builds Docker RAG/OCR pasan. - [x] Publicar la correccion autorizada mediante commit/push y desplegar conjuntamente RAG/OCR con `BUILD_REVISION=960e04a5a9fc3a3ef108fa4ef19d5ff42dbdb1ae`. - [x] Rechazar y purgar la candidata sintetica blank `6011a4eb-3e42-4ea4-a7da-a3e930cc60ed`, completar la purga de la sintetica valida `c4646668-30e4-409e-800d-23a8ee465a42` y purgar FacturaTech v3-v8. - [x] Verificar que no quedan candidatas OCR de prueba utiles o bloqueadas y que FacturaTech v1 conserva el puntero activo con `36/36` puntos. Los estados finales son 7 versiones activas y 9 purgadas; no hay estados intermedios. - [ ] Decidir por separado, solo si aporta valor, si se realiza una nueva ingesta del PDF original de FacturaTech con el sistema ya validado. **Paquete posterior no bloqueante:** implementar recuperacion automatica si la purga se interrumpe despues de eliminar artefactos y antes del CAS `purging -> purged`, y alinear el contrato historico de retencion con el comportamiento real. La operacion actual es recuperable repitiendo `DELETE`; este paquete no requiere ampliar ahora la bateria de pruebas ni bloquea la publicacion. ##### I. Criterio de servicio completamente operativo - [x] 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. - [x] 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. - [x] Confirmar health, observabilidad, almacenamiento, cola, PostgreSQL, Qdrant, revision no activa y rollback documentado sin incidencias abiertas de severidad bloqueante. - [x] Declarar cerrado el trabajo tecnico con la evidencia registrada. RAG-OCR funciona completamente y las candidatas descartadas quedaron limpias; esto no implica una nueva ingesta de FacturaTech. 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, si aparece una futura candidata, deben corregirse explicitamente durante su revision, 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 actual:** `0.2.1` revision `960e04a5a9fc3a3ef108fa4ef19d5ff42dbdb1ae` supero el cierre A-I. Las candidatas descartadas estan purgadas, no quedan estados bloqueantes y FacturaTech v1 sigue activa con `36/36` puntos. Una nueva ingesta del PDF original sigue siendo una decision opcional separada. ## 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.