@arela/uploader 1.0.24 → 1.1.0

package/docs/WATCH_ARCHITECTURE.md

@@ -0,0 +1,395 @@
+# Arquitectura de Watch Mode con Auto-Processing Pipeline
+
+## 🏗️ Diagrama de Componentes
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           arela watch                                   │
+│                         (index.js - CLI)                                │
+└──────────────────────────┬──────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      WatchCommand.js                                    │
+│  • Parsea directorios con JSON (WATCH_DIRECTORY_CONFIGS)              │
+│  • Crea configuraciones de directorio con folderStructure              │
+│  • Inicializa WatchService con directoryConfigs                        │
+│  • Habilita auto-processing                                           │
+└──────────────────────────┬──────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      WatchService.js                                    │
+│  ┌──────────────────────────────────────────────────────────┐          │
+│  │ Watchers (chokidar)                                      │          │
+│  │ • Monitorea cambios en filesystem                        │          │
+│  │ • Emite eventos: add, change, unlink                     │          │
+│  └──────────────────────────────────────────────────────────┘          │
+│                           │                                             │
+│  ┌──────────────────────┐▼──────────────────────┐                     │
+│  │ #handleFileAdded()   │ (evento: add)         │                     │
+│  └──────────────────────┬──────────────────────┘                     │
+│                           │                                             │
+│  ┌──────────────────────┐▼──────────────────────┐                     │
+│  │ #triggerAutoPipeline()│ (if autoProcessing)  │                     │
+│  └──────────────────────┬──────────────────────┘                     │
+│                           │                                             │
+│  ┌──────────────────────┐▼──────────────────────┐                     │
+│  │ directoryConfigs Map │ findWatchDirectory()  │                     │
+│  │ • watchDir -> config │ folderStructure       │                     │
+│  └──────────────────────┬──────────────────────┘                     │
+└──────────────────────────┼──────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│              AutoProcessingService.js                                   │
+│                  (4-Step Pipeline)                                      │
+│                                                                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
+│  │   STEP 1    │  │   STEP 2    │  │   STEP 3    │  │   STEP 4    │  │
+│  │   Stats     │→ │  Detect     │→ │ Propagate   │→ │   Upload    │  │
+│  │  Only       │  │  PDFs       │  │  Arela Path │  │   by RFC    │  │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘  │
+│       │                  │                 │               │           │
+│       ▼                  ▼                 ▼               ▼           │
+│    UploadCommand   DatabaseService  DatabaseService UploadCommand    │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## 📊 Flujo de Datos
+
+### Secuencia de Eventos
+
+```
+1. Usuario coloca archivo en directorio monitoreado
+                    ↓
+2. Chokidar detecta evento 'add'
+                    ↓
+3. WatchService.#handleFileAdded() es invocado
+                    ↓
+4. Si autoProcessingEnabled:
+   - WatchService.#triggerAutoPipeline(filePath) es llamado
+                    ↓
+5. Se identifica el watchDir correspondiente
+   - Se obtiene folderStructure de directoryConfigs
+                    ↓
+6. AutoProcessingService.executeProcessingPipeline() inicia
+                    ↓
+7. Secuencia de 4 pasos:
+   - Step 1: stats --stats-only
+   - Step 2: detect --detect-pdfs
+   - Step 3: detect --propagate-arela-path
+   - Step 4: upload --upload-by-rfc --folder-structure
+                    ↓
+8. Resultado es loguead y resumido
+```
+
+## 🔌 Integración de Componentes
+
+### config.js
+```javascript
+// Parsea WATCH_DIRECTORY_CONFIGS desde .env
+watch.directoryConfigs = JSON.parse(process.env.WATCH_DIRECTORY_CONFIGS)
+// Resultado:
+// {
+//   "../../Documents/2022": "estructura-2022",
+//   "../../Documents/2023": "estructura-2023"
+// }
+```
+
+### WatchCommand.js
+```javascript
+// Convierte configuración a array de objetos
+const directories = [
+  { path: "../../Documents/2022", folderStructure: "estructura-2022" },
+  { path: "../../Documents/2023", folderStructure: "estructura-2023" }
+]
+
+// Pasa directoryConfigs a WatchService
+for (const dirConfig of directories) {
+  await watchService.addWatcher(dirPath, options, dirConfig)
+}
+
+// Habilita auto-processing
+watchService.enableAutoProcessing({ batchSize: 10 })
+```
+
+### WatchService.js
+```javascript
+// Almacena configuración de directorios
+directoryConfigs = new Map([
+  ["path/to/Documents/2022", { path: "...", folderStructure: "estructura-2022" }],
+  ["path/to/Documents/2023", { path: "...", folderStructure: "estructura-2023" }]
+])
+
+// Cuando detecta archivo nuevo
+#handleFileAdded(filePath) {
+  if (this.autoProcessingEnabled) {
+    this.#triggerAutoPipeline(filePath)
+  }
+}
+
+// Encuentra configuración del directorio
+#triggerAutoPipeline(filePath) {
+  const watchDir = this.#findWatchDirectory(filePath)
+  const dirConfig = this.directoryConfigs.get(watchDir)
+  const folderStructure = dirConfig.folderStructure
+  
+  // Ejecuta pipeline con folderStructure
+  autoProcessingService.executeProcessingPipeline({
+    filePath,
+    watchDir,
+    folderStructure,
+    batchSize: 10
+  })
+}
+```
+
+### AutoProcessingService.js
+```javascript
+// Ejecuta 4 pasos secuencialmente
+async executeProcessingPipeline(options) {
+  // Step 1: stats
+  await this.#executeStatsOnly(options)
+  
+  // Step 2: detect
+  await this.#executeDetectPdfs(options)
+  
+  // Step 3: propagate
+  await this.#executePropagateArelaPath()
+  
+  // Step 4: upload with folderStructure
+  await this.#executeUploadByRfc({
+    ...options,
+    folderStructure: options.folderStructure  // ← Se usa aquí
+  })
+}
+```
+
+## 📁 Estructura de Archivos Modificados
+
+```
+src/
+├── index.js                              (Sin cambios mayores)
+├── config/
+│   └── config.js                         (✅ Actualizado: #loadWatchConfig)
+├── commands/
+│   ├── WatchCommand.js                   (✅ Actualizado: #parseDirectories, auto-processing)
+│   └── UploadCommand.js                  (Sin cambios)
+├── services/
+│   ├── WatchService.js                   (✅ Actualizado: directoryConfigs, auto-pipeline)
+│   ├── AutoProcessingService.js          (🆕 Creado: 4-step pipeline)
+│   ├── DatabaseService.js                (Sin cambios)
+│   └── LoggingService.js                 (Sin cambios)
+└── utils/
+    └── WatchEventHandler.js              (✅ Actualizado: processNewFilesWithPipeline)
+
+.env                                      (✅ Actualizado: WATCH_DIRECTORY_CONFIGS)
+.env.template                             (✅ Actualizado: nueva configuración)
+docs/
+└── WATCH_AUTO_PIPELINE.md                (🆕 Creado: esta documentación)
+```
+
+## 🔄 Estados y Transiciones
+
+### WatchService Estados
+
+```
+┌──────────┐
+│ IDLE     │
+│(created) │
+└────┬─────┘
+     │ addWatcher()
+     ▼
+┌──────────────┐
+│ WATCHING     │ ← directoryConfigs se cargan aquí
+│              │
+└────┬─────────┘
+     │ autoProcessing = true
+     ▼
+┌──────────────────────┐
+│ AUTO-PROCESSING      │
+│ ENABLED              │
+└────┬─────────────────┘
+     │ detecta archivo new
+     ▼
+┌──────────────────────┐
+│ EXECUTING PIPELINE   │
+│ (AutoProcessing      │
+│  Service)            │
+└────┬─────────────────┘
+     │ pipeline completa
+     ▼
+┌──────────────┐
+│ WATCHING     │ ← Vuelve a estado de espera
+└──────────────┘
+```
+
+### Pipeline Estados
+
+```
+┌──────────┐
+│ PENDING  │
+└────┬─────┘
+     │ executeProcessingPipeline()
+     ▼
+┌──────────────┐
+│ STEP 1       │
+│ STATS ONLY   │
+└────┬─────────┘
+     │ success
+     ▼
+┌──────────────┐
+│ STEP 2       │
+│ DETECT PDFS  │
+└────┬─────────┘
+     │ success
+     ▼
+┌──────────────┐
+│ STEP 3       │
+│ PROPAGATE    │
+└────┬─────────┘
+     │ success/warning
+     ▼
+┌──────────────┐
+│ STEP 4       │
+│ UPLOAD RFC   │
+└────┬─────────┘
+     │ success/fail
+     ▼
+┌──────────────┐
+│ COMPLETED    │
+└──────────────┘
+```
+
+## 🎯 Caso de Uso Detallado
+
+### Escenario: Nuevo archivo en Documents/2022
+
+#### Configuración
+```env
+WATCH_DIRECTORY_CONFIGS={"../../Documents/2022":"estructura-2022"}
+WATCH_ENABLED=true
+```
+
+#### Ejecución
+
+1. **Evento del Filesystem**
+   - Usuario: `cp documento.pdf ../../Documents/2022/`
+   - Chokidar: Detecta evento 'add' para el archivo
+
+2. **WatchService**
+   ```
+   #handleFileAdded(filePath) →
+   #triggerAutoPipeline(filePath) →
+   #findWatchDirectory() → "../../Documents/2022" →
+   directoryConfigs.get() → { folderStructure: "estructura-2022" } →
+   autoProcessingService.executeProcessingPipeline()
+   ```
+
+3. **AutoProcessingService - Step 1**
+   ```
+   #executeStatsOnly() →
+   UploadCommand.execute({ statsOnly: true }) →
+   Database: INSERT INTO uploads VALUES (...)
+   ```
+
+4. **AutoProcessingService - Step 2**
+   ```
+   #executeDetectPdfs() →
+   DatabaseService.detectPedimentosInDatabase() →
+   Database: UPDATE uploads SET document_type = 'pedimento-simplificado' WHERE ...
+   ```
+
+5. **AutoProcessingService - Step 3**
+   ```
+   #executePropagateArelaPath() →
+   DatabaseService.propagateArelaPath() →
+   Database: UPDATE uploads SET arela_path = ... WHERE original_path = ...
+   ```
+
+6. **AutoProcessingService - Step 4**
+   ```
+   #executeUploadByRfc() →
+   DatabaseService.uploadFilesByRfc({ folderStructure: "estructura-2022" }) →
+   UploadService: POST /api/upload/file (with folderStructure header/param) →
+   Result: File uploaded to Arela with path bucket/estructura-2022/...
+   ```
+
+7. **Resultado Final**
+   ```
+   ✅ Pipeline execution complete
+   - Stats collected
+   - PDFs detected
+   - Arela paths propagated
+   - Files uploaded with structure
+   - All 4 steps successful
+   ```
+
+## 🧪 Testing
+
+### Unit Tests Recomendados
+
+```javascript
+// Test: directoryConfigs se cargan correctamente
+describe('WatchService', () => {
+  it('should load directory configs from addWatcher', () => {
+    const dirConfig = { path: 'test', folderStructure: 'test-struct' }
+    watchService.addWatcher('test', {}, dirConfig)
+    expect(watchService.directoryConfigs.get(path.resolve('test'))).toEqual(...)
+  })
+})
+
+// Test: auto-processing se habilita
+it('should enable auto-processing', () => {
+  watchService.enableAutoProcessing({ batchSize: 10 })
+  expect(watchService.isAutoProcessingEnabled()).toBe(true)
+})
+
+// Test: pipeline se ejecuta en archivo nuevo
+it('should trigger pipeline on file added', async () => {
+  // Mock AutoProcessingService
+  // Simulate #handleFileAdded
+  // Verify pipeline was called
+})
+```
+
+## 📈 Métricas y Monitoreo
+
+### Stats Disponibles
+
+```javascript
+// WatchService stats
+{
+  filesAdded: 42,
+  filesModified: 15,
+  filesRemoved: 3,
+  uploadsTriggered: 10,
+  pipelinesTriggered: 8,        // ← Novo
+  errorsEncountered: 0,
+  watchedDirectories: 2,
+  activeWatchers: 2,
+  isRunning: true,
+  autoProcessingEnabled: true   // ← Novo
+}
+```
+
+## 🔐 Consideraciones de Seguridad
+
+1. **Validación de Ruta**
+   - Se valida que el archivo está en directorio vigilado
+   - Se previene procesamiento de archivos fuera del scope
+
+2. **Prevención de Concurrencia**
+   - Solo un pipeline por vez (`this.isProcessing`)
+   - Se colan nuevas solicitudes mientras uno está en ejecución
+
+3. **Manejo de Errores**
+   - Errores en pasos iniciales detienen el pipeline
+   - Errores posteriores se loguean pero continúan
+   - No se pierden datos incluso con fallos
+
+---
+
+Para implementación y uso, ver [WATCH_AUTO_PIPELINE.md](WATCH_AUTO_PIPELINE.md)