@arela/uploader 1.0.24 → 1.1.0

package/docs/WATCH_AUTO_PIPELINE.md

@@ -0,0 +1,334 @@
+# Watch Mode - Automatic Processing Pipeline
+
+## 📋 Overview
+
+El sistema de Watch Mode ahora incluye un **pipeline automático de 4 pasos** que se ejecuta automáticamente cuando se detecta un archivo nuevo en los directorios monitoreados.
+
+## 🔄 Pipeline de 4 Pasos
+
+Cuando se detecta un nuevo archivo en watch mode, se ejecuta automáticamente:
+
+### Paso 1: Recopilación de Estadísticas (Stats)
+```bash
+stats --stats-only
+```
+- **Objetivo**: Recopilar información del archivo en la base de datos
+- **Resultado**: Archivo registrado en tabla `uploads`
+
+### Paso 2: Detección de Pedimentos (PDF Detection)
+```bash
+detect --detect-pdfs
+```
+- **Objetivo**: Identificar si existe un pedimento simplificado
+- **Resultado**: Si no hay pedimento, otros documentos en el mismo directorio no se subirán
+- **Importancia**: Crucial para mantener integridad de datos
+
+### Paso 3: Propagación de Arela Path
+```bash
+detect --propagate-arela-path
+```
+- **Objetivo**: Propagar el `arela_path` desde pedimentos a documentos relacionados
+- **Resultado**: Todos los documentos en el mismo directorio tienen referencia válida
+
+### Paso 4: Upload por RFC con Estructura
+```bash
+upload --upload-by-rfc --folder-structure <estructura>
+```
+- **Objetivo**: Subir archivos al bucket Arela con estructura de carpetas
+- **Resultado**: Archivos organizados según `folderStructure` configurada
+
+## ⚙️ Configuración
+
+### 1. Configurar Directorios en `.env`
+
+Usar formato JSON con configuración por directorio:
+
+```env
+WATCH_DIRECTORY_CONFIGS={"../../Documents/2022":"estructura-2022","../../Documents/2023":"estructura-2023"}
+```
+
+**Formato del JSON:**
+- **Clave**: Ruta del directorio a monitorear
+- **Valor**: `folderStructure` a usar en el upload
+
+### 2. Iniciar Watch Mode
+
+```bash
+# Activar watch mode con auto-processing (default)
+arela watch
+
+# O especificar directorios:
+arela watch -d "../../Documents/2022,../../Documents/2023"
+
+# Deshabilitar auto-processing si lo necesitas:
+arela watch --no-auto-processing
+```
+
+## 📊 Estadísticas y Logging
+
+Cada ejecución del pipeline genera:
+
+1. **ID de Pipeline**: ID único para rastrear la ejecución
+2. **Logs Detallados**: Cada paso registra su progreso
+3. **Summary**: Resumen final con estado de éxito/fallo
+
+### Ejemplo de Output:
+
+```
+🔄 Starting processing pipeline pipeline-1731557400000-abc123def for file: ../../Documents/2022/documento.pdf
+   Watch directory: ../../Documents/2022
+   Folder structure: estructura-2022
+
+📊 [Step 1/4] Running stats collection (stats-only)...
+✅ Stats collection completed in 1250ms
+
+🔍 [Step 2/4] Running PDF detection (detect --detect-pdfs)...
+✅ PDF detection completed in 2340ms
+   📊 Results: 5 detected, 150 processed
+
+🔄 [Step 3/4] Running arela_path propagation (detect --propagate-arela-path)...
+✅ Arela path propagation completed in 890ms
+   📊 Results: 150 processed, 145 updated
+
+📤 [Step 4/4] Running RFC-based upload with folder structure...
+✅ RFC upload completed in 5600ms
+   📊 Results: 145 processed, 140 uploaded
+
+✅ Processing pipeline pipeline-1731557400000-abc123def completed in 10080ms
+   Summary: ✅ All 4 steps completed successfully!
+```
+
+## 🎯 Casos de Uso
+
+### Caso 1: Upload Automático de Nuevos Documentos
+
+1. Usuario coloca documento en `Documents/2022`
+2. WatchService detecta el archivo
+3. Pipeline se ejecuta automáticamente
+4. Documento se sube a Arela con estructura definida
+
+**Ventaja**: Sin intervención manual
+
+### Caso 2: Validación de Pedimentos
+
+1. Se carga pedimento simplificado
+2. Step 2 (PDF Detection) lo identifica
+3. Step 3 (Path Propagation) vincula documentos relacionados
+4. Step 4 (Upload) sube todo con estructura
+
+**Ventaja**: Garantiza integridad de datos
+
+### Caso 3: Múltiples Directorios con Estructuras Diferentes
+
+```env
+WATCH_DIRECTORY_CONFIGS={
+  "../../Documents/2022":"estructura-2022",
+  "../../Documents/2023":"estructura-2023",
+  "../../Invoices":"estructura-facturas"
+}
+```
+
+**Ventaja**: Cada directorio usa su propia estructura
+
+## 🛠️ Componentes Técnicos
+
+### AutoProcessingService (`src/services/AutoProcessingService.js`)
+
+**Responsabilidades**:
+- Orquestar la ejecución de 4 pasos
+- Prevenir procesamiento concurrente
+- Generar logs detallados
+- Crear resumen de resultados
+
+**Métodos Principales**:
+- `executeProcessingPipeline(options)` - Ejecuta todo el flujo
+- `getStats()` - Obtiene estadísticas
+- `resetStats()` - Reinicia contador
+
+### WatchService (`src/services/WatchService.js`)
+
+**Enhancements**:
+- Mapeo de directorios con configuración (`directoryConfigs`)
+- Métodos de auto-processing:
+  - `enableAutoProcessing(options)` - Habilita pipeline
+  - `disableAutoProcessing()` - Deshabilita pipeline
+  - `isAutoProcessingEnabled()` - Verifica estado
+
+### WatchCommand (`src/commands/WatchCommand.js`)
+
+**Enhancements**:
+- Parsea configuración JSON de directorios
+- Pasa `directoryConfigs` a `WatchService`
+- Soporta opción CLI `--no-auto-processing`
+
+## 📝 Consideraciones Importantes
+
+### 1. Requisitos de Base de Datos
+
+El pipeline requiere que la base de datos esté configurada:
+```env
+SUPABASE_URL=...
+SUPABASE_KEY=...
+SUPABASE_BUCKET=...
+```
+
+### 2. Dependencias de Servicios
+
+Asegúrate de que están disponibles:
+- `DatabaseService` - Para stats y detection
+- `UploadServiceFactory` - Para RFC upload
+- Logger configurado
+
+### 3. Validación de Directorio
+
+El sistema valida:
+- ✅ Directorio existe
+- ✅ Archivo es válido (no temporal)
+- ✅ Configuración está definida
+
+### 4. Manejo de Errores
+
+Si algún paso falla:
+- Se loguea el error
+- Pipeline continúa (excepto si falla step 1)
+- Se genera resumen con estado de fallo
+
+## 🔧 Configuración Avanzada
+
+### Desabilitar Pipeline Temporalmente
+
+```bash
+# CLI
+arela watch --no-auto-processing
+
+# O en código
+watchService.disableAutoProcessing()
+```
+
+### Cambiar Batch Size
+
+```bash
+# En CLI
+arela watch -b 20
+
+# O en config
+WATCH_BATCH_SIZE=20
+```
+
+### Ignorar Patrones de Archivos
+
+```env
+WATCH_IGNORE_PATTERNS=*.tmp,*.bak,*.swp,._*
+```
+
+## 📈 Monitoreo
+
+### Ver Estadísticas en Tiempo Real
+
+El WatchService mantiene estadísticas:
+```javascript
+const stats = watchService.getStats();
+console.log(stats.pipelinesTriggered); // Número de pipelines ejecutados
+```
+
+### Logs Detallados
+
+Habilita verbose logging:
+```bash
+arela watch -v
+```
+
+O en `.env`:
+```env
+VERBOSE_LOGGING=true
+```
+
+## ❓ Troubleshooting
+
+### Pipeline no se ejecuta
+
+**Causa**: Auto-processing deshabilitado
+```bash
+# Verificar estado
+arela watch
+
+# Si necesitas habilitar
+arela watch (se habilita por defecto)
+```
+
+### Errores en Step 2 (PDF Detection)
+
+**Causa**: Base de datos no configurada
+```env
+SUPABASE_URL=...
+SUPABASE_KEY=...
+```
+
+### Archivos no se suben
+
+**Causa**: No hay RFC válido
+```bash
+# Verificar RFCs configurados
+arela config
+```
+
+## 📚 Comandos Relacionados
+
+```bash
+# Ver configuración
+arela config
+
+# Ejecutar pasos manualmente
+arela stats --stats-only
+arela detect --detect-pdfs
+arela detect --propagate-arela-path
+arela upload --upload-by-rfc --folder-structure estructura-2022
+
+# Query
+arela query --ready-files
+```
+
+## 🎓 Ejemplo Completo
+
+### 1. Configurar `.env`
+
+```env
+WATCH_ENABLED=true
+WATCH_DIRECTORY_CONFIGS={"../../Documents":"estructura-principal"}
+WATCH_STRATEGY=batch
+WATCH_BATCH_SIZE=10
+```
+
+### 2. Iniciar Watch Mode
+
+```bash
+node src/index.js watch -v
+```
+
+### 3. Colocar Archivo
+
+```bash
+cp documento.pdf ../../Documents/
+```
+
+### 4. Observar Pipeline
+
+```
+[AutoPipeline] Triggering 4-step processing pipeline for: ../../Documents/documento.pdf
+[Step 1/4] Running stats collection...
+✅ Stats collection completed
+[Step 2/4] Running PDF detection...
+✅ PDF detection completed
+[Step 3/4] Running arela_path propagation...
+✅ Arela path propagation completed
+[Step 4/4] Running RFC-based upload...
+✅ RFC upload completed
+✅ Processing pipeline completed successfully!
+```
+
+---
+
+Para más información, consulta:
+- [WATCH_CONFIGURATION.md](WATCH_CONFIGURATION.md)
+- [PHASE_2_API_INTEGRATION.md](PHASE_2_API_INTEGRATION.md)
+- [PHASE_3_DATABASE_MANAGEMENT.md](PHASE_3_DATABASE_MANAGEMENT.md)

package/docs/WATCH_CONFIGURATION.md

@@ -0,0 +1,267 @@
+# 🔧 Configuración del Watch Mode - Fase 3
+
+## Variables de Ambiente
+
+El Watch Mode puede configurarse mediante variables de ambiente en el archivo `.env`:
+
+```bash
+# Habilitar watch mode (opcional, puede usarse el comando CLI directamente)
+WATCH_ENABLED=true
+
+# Directorios a observar (separados por coma)
+WATCH_DIRECTORIES=/ruta/carpeta1,/ruta/carpeta2,/ruta/carpeta3
+
+# Estrategia de upload (opciones: individual|batch|full-structure)
+# - individual: Sube solo el archivo modificado más reciente
+# - batch: Sube un lote de N archivos recientes
+# - full-structure: Sube la estructura completa de carpetas
+WATCH_STRATEGY=batch
+
+# Debouncing en milisegundos (esperar entre eventos antes de procesar)
+WATCH_DEBOUNCE_MS=1000
+
+# Tamaño de batch para strategy batch
+WATCH_BATCH_SIZE=10
+
+# Usar polling en lugar de eventos nativos del filesystem
+# Útil para sistemas de archivos remotos o NFS
+WATCH_USE_POLLING=false
+
+# Interval de polling en milisegundos (solo si WATCH_USE_POLLING=true)
+WATCH_POLL_INTERVAL=100
+
+# Umbral de estabilidad en ms (esperar a que el archivo deje de cambiar)
+WATCH_STABILITY_THRESHOLD=300
+
+# Patrones a ignorar (separados por coma, se usan como regex)
+WATCH_IGNORE_PATTERNS=*.tmp,*.bak,*.swp
+
+# Detección automática de tipos de documento
+WATCH_AUTO_DETECT=false
+
+# Organización automática de archivos
+WATCH_AUTO_ORGANIZE=false
+```
+
+## Opciones de Línea de Comandos
+
+```bash
+arela watch [options]
+
+Opciones:
+  -d, --directories <paths>      Directorios a observar (separados por coma)
+  -s, --strategy <strategy>      Estrategia: individual|batch|full-structure
+                                 (default: "batch")
+  --debounce <ms>                Debounce en milisegundos (default: 1000)
+  -b, --batch-size <size>        Tamaño de batch (default: 10)
+  --poll <ms>                    Usar polling con este intervalo
+  --ignore <patterns>            Patrones a ignorar (separados por coma)
+  --auto-detect                  Habilitar detección automática
+  --auto-organize                Habilitar organización automática
+  --dry-run                      Simular cambios sin subir
+  --verbose                      Modo verbose para logging
+  -h, --help                     Mostrar ayuda
+```
+
+## Prioridad de Configuración
+
+La configuración se aplica en este orden (primero gana):
+
+1. **Opciones CLI** (línea de comandos) - Mayor prioridad
+2. **Variables de Ambiente** (.env)
+3. **Valores por Defecto** - Menor prioridad
+
+Ejemplo: Si especificas `--strategy individual` en CLI pero `WATCH_STRATEGY=batch` en .env, se usará `individual`.
+
+## Ejemplos de Uso
+
+### Ejemplo 1: Configuración Mínima
+
+```bash
+# Solo especificar directorios
+arela watch --directories /ruta/carpeta
+
+# O usar variable de ambiente
+export WATCH_DIRECTORIES=/ruta/carpeta
+arela watch
+```
+
+### Ejemplo 2: Batch Upload con Debouncing
+
+```bash
+arela watch \
+  --directories /documentos,/pdfs \
+  --strategy batch \
+  --batch-size 20 \
+  --debounce 2000 \
+  --verbose
+```
+
+### Ejemplo 3: Full Structure Upload
+
+```bash
+arela watch \
+  --directories /datos \
+  --strategy full-structure \
+  --debounce 1000
+```
+
+### Ejemplo 4: Individual Uploads
+
+```bash
+arela watch \
+  --directories /uploads \
+  --strategy individual \
+  --debounce 500 \
+  --auto-detect
+```
+
+### Ejemplo 5: Usando Polling (Sistemas Remotos)
+
+```bash
+arela watch \
+  --directories /mnt/nfs/compartido \
+  --poll 1000 \
+  --ignore "*.tmp,*.lock,.DS_Store"
+```
+
+### Ejemplo 6: Dry Run (Prueba sin Subir)
+
+```bash
+arela watch \
+  --directories /test \
+  --dry-run \
+  --verbose
+```
+
+### Ejemplo 7: Con .env File
+
+Crear archivo `.env`:
+
+```bash
+WATCH_DIRECTORIES=/documentos,/pdfs
+WATCH_STRATEGY=batch
+WATCH_DEBOUNCE_MS=1500
+WATCH_BATCH_SIZE=15
+WATCH_IGNORE_PATTERNS=*.tmp,*.bak
+WATCH_AUTO_DETECT=true
+```
+
+Luego ejecutar:
+
+```bash
+arela watch --verbose
+```
+
+## Configuración en config.js
+
+La configuración se carga automáticamente en `src/config/config.js`:
+
+```javascript
+appConfig.watch = {
+  enabled: false,                        // bool
+  directories: [],                       // string[]
+  strategy: 'batch',                     // 'individual'|'batch'|'full-structure'
+  debounceMs: 1000,                      // number
+  batchSize: 10,                         // number
+  usePolling: false,                     // bool
+  pollInterval: 100,                     // number (ms)
+  stabilityThreshold: 300,               // number (ms)
+  ignorePatterns: [],                    // string[] (regex patterns)
+  autoDetect: false,                     // bool
+  autoOrganize: false,                   // bool
+}
+```
+
+## Acceso a la Configuración en Código
+
+```javascript
+import appConfig from './config/config.js';
+
+// Obtener toda la configuración
+const watchConfig = appConfig.getWatchConfig();
+
+// Obtener directorios específicos
+const directories = appConfig.getWatchDirectories(cliDirs);
+
+// Validar configuración
+appConfig.validateWatchConfig(directories);
+```
+
+## Validación de Configuración
+
+El sistema valida automáticamente:
+
+✅ Al menos un directorio especificado
+✅ Estrategia válida (individual|batch|full-structure)
+✅ Debounce >= 0
+✅ Batch size >= 1
+✅ Directorios accesibles
+
+## Casos de Uso Recomendados
+
+### Use Case 1: Monitoreo Simple
+```bash
+arela watch --directories /upload
+```
+- Usa estrategia batch (por defecto)
+- Debounce: 1000ms
+- Ideal para: Usuarios ocasionales
+
+### Use Case 2: Monitoreo de Alto Volumen
+```bash
+arela watch \
+  --directories /datos \
+  --strategy batch \
+  --batch-size 50 \
+  --debounce 500
+```
+- Procesa más archivos por batch
+- Debounce más corto para reactividad
+- Ideal para: Muchos cambios rápidos
+
+### Use Case 3: Sincronización en Tiempo Real
+```bash
+arela watch \
+  --directories /sync \
+  --strategy individual \
+  --debounce 300
+```
+- Cada archivo se procesa casi inmediatamente
+- Overhead más alto
+- Ideal para: Cambios críticos
+
+### Use Case 4: Estructura Completa
+```bash
+arela watch \
+  --directories /backup \
+  --strategy full-structure
+```
+- Procesa estructura completa cada vez
+- Ideal para: Backups/snapshots
+
+## Troubleshooting
+
+### El watch no detecta cambios
+- Verificar que el directorio existe: `ls -la /ruta`
+- Intentar usar `--poll` para sistemas remotos
+- Aumentar `--debounce` si hay muchos cambios rápidos
+
+### Memory leak o CPU alto
+- Reducir `--batch-size`
+- Aumentar `--debounce`
+- Usar `--ignore` para excluir patrones innecesarios
+
+### Errores de permisos
+- Verificar permisos: `ls -ld /ruta`
+- Ejecutar con usuario apropiado
+
+### Archivos no se suben
+- Usar `--dry-run --verbose` para debug
+- Verificar patrones de ignore: `--ignore ""`
+- Revisar logs en `arela-upload.log`
+
+---
+
+**Documentación de Configuración - Fase 3**
+Última actualización: Nov 14, 2025