@arela/uploader 1.0.24 → 1.1.1

package/docs/WATCH_USAGE_GUIDE.md

@@ -0,0 +1,567 @@
+# Watch Mode - Guía Práctica de Uso
+
+## 🚀 Inicio Rápido
+
+### 1. Configuración Básica
+
+**Editar `.env`:**
+
+```env
+WATCH_ENABLED=true
+WATCH_DIRECTORY_CONFIGS={"../../Documents/2022":"estructura-2022"}
+```
+
+### 2. Iniciar Watch Mode
+
+```bash
+# Básico
+node src/index.js watch
+
+# Con verbose logging
+node src/index.js watch -v
+
+# Sin auto-processing
+node src/index.js watch --no-auto-processing
+```
+
+### 3. Colocar Archivo y Observar
+
+```bash
+# Terminal 1: Iniciar watch
+$ node src/index.js watch -v
+
+# Terminal 2: Copiar archivo
+$ cp /path/to/documento.pdf ../../Documents/2022/
+
+# Terminal 1: Ver pipeline ejecutándose
+🔄 Starting processing pipeline pipeline-1731557400000-xyz123...
+📊 [Step 1/4] Running stats collection...
+✅ Stats collection completed in 1250ms
+...
+```
+
+---
+
+## 📋 Ejemplos de Configuración
+
+### Ejemplo 1: Un Directorio Simple
+
+```env
+# .env
+WATCH_DIRECTORY_CONFIGS={"../../Documents":"estructura-principal"}
+```
+
+```bash
+node src/index.js watch
+```
+
+**Comportamiento:**
+- Monitorea `../../Documents`
+- Todos los archivos se suben con `estructura-principal`
+
+---
+
+### Ejemplo 2: Múltiples Directorios con Estructuras Diferentes
+
+```env
+# .env
+WATCH_DIRECTORY_CONFIGS={"../../Documents/2022":"estructura-2022","../../Documents/2023":"estructura-2023","../../Invoices":"estructura-facturas"}
+```
+
+```bash
+node src/index.js watch -v
+```
+
+**Comportamiento:**
+```
+Archivo en Documents/2022/documento.pdf
+  → estructura-2022
+
+Archivo en Documents/2023/contrato.pdf
+  → estructura-2023
+
+Archivo en Invoices/factura.pdf
+  → estructura-facturas
+```
+
+---
+
+### Ejemplo 3: Configuración Avanzada con Opciones
+
+```env
+# .env
+WATCH_DIRECTORY_CONFIGS={"../../Documents":"estructura-docs"}
+WATCH_STRATEGY=batch
+WATCH_BATCH_SIZE=20
+WATCH_DEBOUNCE_MS=2000
+WATCH_STABILITY_THRESHOLD=500
+```
+
+```bash
+# CLI
+node src/index.js watch -b 25 --debounce 2500
+```
+
+**Parámetros:**
+- `WATCH_STRATEGY=batch` - Procesa en lotes
+- `WATCH_BATCH_SIZE=20` - 20 archivos por lote
+- `WATCH_DEBOUNCE_MS=2000` - Espera 2s entre eventos
+- `WATCH_STABILITY_THRESHOLD=500` - Archivo debe estar estable 500ms
+
+---
+
+### Ejemplo 4: Ignorar Archivos Temporales
+
+```env
+# .env
+WATCH_IGNORE_PATTERNS=*.tmp,*.bak,*.swp,._*,.DS_Store
+WATCH_DIRECTORY_CONFIGS={"../../Documents":"estructura-principal"}
+```
+
+```bash
+node src/index.js watch -v
+```
+
+**Archivos ignorados:**
+- `documento.tmp` ✗
+- `documento.bak` ✗
+- `.documento.swp` ✗
+- `._documento` ✗
+- `.DS_Store` ✗
+- `documento.pdf` ✓
+
+---
+
+## 🔄 Casos de Uso Completos
+
+### Caso 1: Empresa de Logística - Documentos por Año
+
+**Estructura del Negocio:**
+- Archivos de 2022 → Estructura "logistica-2022"
+- Archivos de 2023 → Estructura "logistica-2023"
+- Archivos de 2024 → Estructura "logistica-2024"
+
+**Configuración:**
+
+```env
+# .env
+WATCH_ENABLED=true
+WATCH_DIRECTORY_CONFIGS={
+  "/var/data/shipments/2022":"logistica-2022",
+  "/var/data/shipments/2023":"logistica-2023",
+  "/var/data/shipments/2024":"logistica-2024"
+}
+WATCH_STRATEGY=batch
+WATCH_BATCH_SIZE=50
+WATCH_AUTO_DETECT=true
+```
+
+**Pipeline por archivo:**
+
+```
+Nuevo archivo: shipment-2024-001.pdf
+
+1️⃣ Stats: Se registra en base de datos
+2️⃣ Detect: Se identifica tipo de documento
+3️⃣ Propagate: Se vinculan documentos relacionados
+4️⃣ Upload: Se sube a bucket con estructura "logistica-2024"
+
+Resultado: bucket/logistica-2024/shipment-2024-001.pdf
+```
+
+---
+
+### Caso 2: Despacho de Aduanas - Pedimentos y Anexos
+
+**Estructura del Negocio:**
+- Pedimentos simplificados (detecta automáticamente)
+- Documentos anexos (solo se suben si hay pedimento)
+
+**Configuración:**
+
+```env
+# .env
+WATCH_ENABLED=true
+WATCH_DIRECTORY_CONFIGS={"../../Pedimentos":"estructura-aduanas"}
+WATCH_AUTO_DETECT=true
+WATCH_STABILITY_THRESHOLD=1000
+```
+
+**Flujo de Trabajo:**
+
+```
+Usuario coloca 3 archivos en Pedimentos/:
+  1. pedimento-simplificado.pdf   (pedimento)
+  2. factura.pdf                  (anexo)
+  3. packing-list.pdf             (anexo)
+
+Step 1 (Stats):
+  ✅ Registra los 3 archivos en uploads
+
+Step 2 (Detect):
+  ✅ Identifica pedimento-simplificado.pdf como "pedimento-simplificado"
+  
+Step 3 (Propagate):
+  ✅ Vincula factura.pdf a pedimento
+  ✅ Vincula packing-list.pdf a pedimento
+  
+Step 4 (Upload):
+  ✅ Sube los 3 con estructura "estructura-aduanas"
+  
+Resultado en Arela:
+  bucket/estructura-aduanas/pedimento-simplificado.pdf
+  bucket/estructura-aduanas/factura.pdf
+  bucket/estructura-aduanas/packing-list.pdf
+```
+
+---
+
+### Caso 3: Agencia de Viajes - Documentos por Cliente
+
+**Estructura del Negocio:**
+- Cada cliente tiene carpeta: `/clients/{cliente-code}/`
+- Documentos varían según tipo
+
+**Configuración:**
+
+```env
+# .env
+WATCH_ENABLED=true
+WATCH_DIRECTORY_CONFIGS={
+  "/data/clients/CLIENT001":"cliente-001",
+  "/data/clients/CLIENT002":"cliente-002",
+  "/data/clients/CLIENT003":"cliente-003"
+}
+WATCH_IGNORE_PATTERNS=~*,*.tmp
+```
+
+**Mantenimiento:**
+
+```bash
+# Agregar nuevo cliente dinámicamente
+# (Requiere reiniciar watch, pero mantiene otros activos)
+
+# Editar .env
+WATCH_DIRECTORY_CONFIGS={
+  "/data/clients/CLIENT001":"cliente-001",
+  "/data/clients/CLIENT002":"cliente-002",
+  "/data/clients/CLIENT003":"cliente-003",
+  "/data/clients/CLIENT004":"cliente-004"
+}
+
+# Reiniciar
+Ctrl+C
+node src/index.js watch -v
+```
+
+---
+
+## 🛑 Detener y Reiniciar
+
+### Parada Graceful
+
+```bash
+# Presionar Ctrl+C
+^C
+👋 Received SIGINT. Gracefully shutting down...
+
+# Output:
+✅ WatchService stopped successfully
+
+Final Stats:
+├─ Files Added: 45
+├─ Files Modified: 12
+├─ Files Removed: 3
+├─ Uploads Triggered: 10
+├─ Pipelines Triggered: 8
+└─ Errors Encountered: 0
+```
+
+### Reiniciar Rápidamente
+
+```bash
+# Usar -v para verbose y --clear-log para log limpio
+node src/index.js watch -v --clear-log
+```
+
+---
+
+## 📊 Monitoreo Mientras Funciona
+
+### Abrir Nueva Terminal
+
+```bash
+# Terminal 1: Watch está corriendo
+$ node src/index.js watch -v
+
+# Terminal 2: Ver configuración
+$ node src/index.js config
+
+# Terminal 3: Verificar archivos listos
+$ node src/index.js query --ready-files
+
+# Terminal 4: Procesar manualmente si necesitas
+$ node src/index.js stats --stats-only
+$ node src/index.js detect --detect-pdfs
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Problema: Pipeline no se ejecuta
+
+**Síntoma:**
+```
+📄 File added: documento.pdf
+⚡ Processing event: add - documento.pdf
+```
+
+Falta el `[AutoPipeline]` log.
+
+**Causa**: Auto-processing deshabilitado
+
+**Solución:**
+```bash
+# Verificar que está habilitado (default)
+node src/index.js watch
+
+# O remover flag --no-auto-processing si está presente
+node src/index.js watch --no-auto-processing  # ❌ Deshabilita
+node src/index.js watch                        # ✅ Habilita (default)
+```
+
+---
+
+### Problema: Errores en Step 2 (Detect PDFs)
+
+**Síntoma:**
+```
+[AutoPipeline] ❌ Pipeline failed: 
+  Cannot read property 'detectPedimentosInDatabase' of undefined
+```
+
+**Causa**: DatabaseService no está disponible
+
+**Solución:**
+```env
+# Verificar configuración Supabase en .env
+SUPABASE_URL=http://127.0.0.1:54321
+SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+SUPABASE_BUCKET=arela
+```
+
+```bash
+# Reiniciar
+node src/index.js watch -v --clear-log
+```
+
+---
+
+### Problema: Archivos no se suben (Step 4)
+
+**Síntoma:**
+```
+[Step 4/4] Running RFC-based upload...
+✅ RFC upload completed in 1500ms
+   📊 Results: 0 processed, 0 uploaded
+```
+
+**Causa**: No hay RFCs válidos configurados o archivos no cumplían requisitos
+
+**Solución:**
+```bash
+# Ver configuración
+node src/index.js config
+
+# Verificar RFCs configurados
+# Expected output:
+# 🎯 Service Availability:
+# RFCs: AKS151005E46|IMS030409FZ0|RDG1107154L7|...
+
+# Si está vacío, agregar en .env
+UPLOAD_RFCS=AKS151005E46|IMS030409FZ0|RDG1107154L7
+```
+
+---
+
+### Problema: Archivos duplicados en upload
+
+**Síntoma:**
+```
+🔄 Triggering 4-step processing pipeline...
+(Se ejecuta 2-3 veces para el mismo archivo)
+```
+
+**Causa**: Debounce muy bajo, múltiples eventos del mismo archivo
+
+**Solución:**
+```env
+# Aumentar debounce
+WATCH_DEBOUNCE_MS=3000  # 3 segundos
+WATCH_STABILITY_THRESHOLD=1000  # 1 segundo
+```
+
+---
+
+### Problema: Consumo alto de CPU
+
+**Síntoma:**
+```
+watch: cpu > 50%
+```
+
+**Causa**: Demasiados watchers o archivo inestable (escritura continua)
+
+**Solución:**
+```env
+# Aumentar estabilidad y debounce
+WATCH_STABILITY_THRESHOLD=2000
+WATCH_DEBOUNCE_MS=5000
+
+# Ignorar más patrones
+WATCH_IGNORE_PATTERNS=*.tmp,*.bak,*.lock,*.swp,._*
+
+# O reducir directorios a monitorear
+# Solo monitorear directorios específicos
+WATCH_DIRECTORY_CONFIGS={"../../Critical/2024":"critico-2024"}
+```
+
+---
+
+## 📚 Comandos Relacionados
+
+```bash
+# Ver todos los comandos
+node src/index.js --help
+
+# Ver configuración actual
+node src/index.js config
+
+# Ver estadísticas sin upload
+node src/index.js stats --stats-only
+
+# Detectar PDFs manualmente
+node src/index.js detect --detect-pdfs
+
+# Propagar arela_path manualmente
+node src/index.js detect --propagate-arela-path
+
+# Upload manual por RFC
+node src/index.js upload --upload-by-rfc
+
+# Query de archivos listos
+node src/index.js query --ready-files
+
+# Verbose mode
+node src/index.js watch -v
+
+# Limpiar log
+node src/index.js watch --clear-log
+```
+
+---
+
+## 💡 Tips y Mejores Prácticas
+
+### 1. Iniciar Sesiones Nombradas (tmux/screen)
+
+```bash
+# Con tmux
+tmux new-session -d -s arela-watch "node src/index.js watch -v"
+
+# Ver logs
+tmux attach -t arela-watch
+
+# Detener
+tmux kill-session -t arela-watch
+```
+
+### 2. Usar Systemd para Arranque Automático
+
+```bash
+# /etc/systemd/system/arela-watch.service
+[Unit]
+Description=Arela Uploader Watch Mode
+After=network.target
+
+[Service]
+Type=simple
+User=arela
+WorkingDirectory=/opt/arela-uploader
+ExecStart=/usr/bin/node src/index.js watch -v
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable arela-watch
+sudo systemctl start arela-watch
+sudo systemctl logs -u arela-watch -f
+```
+
+### 3. Monitoreo con Logs Centralizados
+
+```bash
+# Redirigir logs
+node src/index.js watch -v >> /var/log/arela-watch.log 2>&1 &
+
+# Seguir logs
+tail -f /var/log/arela-watch.log
+
+# Con rotación
+/var/log/arela-watch.log {
+  daily
+  rotate 7
+  compress
+  missingok
+  notifempty
+}
+```
+
+### 4. Variables de Entorno para Producción
+
+```env
+# .env.production
+NODE_ENV=production
+VERBOSE_LOGGING=false
+WATCH_DEBOUNCE_MS=3000
+WATCH_BATCH_SIZE=100
+BATCH_DELAY=500
+MAX_API_CONNECTIONS=20
+```
+
+```bash
+NODE_ENV=production node src/index.js watch
+```
+
+---
+
+## ✅ Checklist de Configuración
+
+- [ ] `.env` configurado con `WATCH_DIRECTORY_CONFIGS`
+- [ ] Directorios a monitorear existen y son accesibles
+- [ ] Credenciales Supabase configuradas
+- [ ] RFCs configurados en `UPLOAD_RFCS`
+- [ ] Base de datos está disponible
+- [ ] API endpoint configurado (si usas API mode)
+- [ ] Patterns de ignore configurados (si necesitas)
+- [ ] Verbose logging habilitado para troubleshooting
+
+---
+
+## 📞 Soporte
+
+Si encuentras problemas:
+
+1. Habilita verbose logging: `node src/index.js watch -v`
+2. Revisa el archivo log: `cat arela-upload.log`
+3. Consulta [WATCH_ARCHITECTURE.md](WATCH_ARCHITECTURE.md)
+4. Consulta [WATCH_AUTO_PIPELINE.md](WATCH_AUTO_PIPELINE.md)
+
+---
+
+Última actualización: 2025-11-14

package/docs/commands.md

@@ -0,0 +1,14 @@
+node src/index.js --stats-only
+node src/index.js --detect-pdfs
+node src/index.js --propagate-arela-path
+node src/index.js --upload-by-rfc --folder-structure palco
+
+UPLOAD_RFCS="RFC1|RFC2" node src/index.js --upload-by-rfc --folder-structure target-folder
+
+
+
+
+node src/index.js stats --stats-only
+node src/index.js detect --detect-pdfs
+node src/index.js detect --propagate-arela-path
+node src/index.js upload --upload-by-rfc --folder-structure palco

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arela/uploader",
-  "version": "1.0.24",
+  "version": "1.1.1",
   "description": "CLI to upload files/directories to Arela",
   "bin": {
     "arela": "./src/index.js"

package/src/commands/IdentifyCommand.js

@@ -248,6 +248,14 @@ export class IdentifyCommand {
       logger.info(`   Duration: ${duration}s`);
       logger.info(`   Speed: ${avgSpeed} files/sec`);
 
+      // Classification distribution for the run (observability: detect shifts /
+      // rising unmatched rate, and which detection mode was used).
+      if (
+        typeof this.detectionService.logClassificationSummary === 'function'
+      ) {
+        this.detectionService.logClassificationSummary(logger);
+      }
+
       if (options.showStats) {
         this.#showDetailedStats(
           startTime,
@@ -303,6 +311,9 @@ export class IdentifyCommand {
       return {
         processed: 0,
         detected: 0,
+        // Must include every field totalStats accumulates — omitting proformas
+        // made `totalStats.proformas += undefined` = NaN in the final summary.
+        proformas: 0,
         errors: 0,
       };
     }

package/src/config/config.js

@@ -37,10 +37,10 @@ class Config {
       const __dirname = path.dirname(__filename);
       const packageJsonPath = path.resolve(__dirname, '../../package.json');
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-      return packageJson.version || '1.0.24';
+      return packageJson.version || '1.1.0';
     } catch (error) {
       console.warn('⚠️ Could not read package.json version, using fallback');
-      return '1.0.24';
+      return '1.1.0';
     }
   }
 

package/src/file-detection.js

@@ -89,6 +89,13 @@ export class FileDetectionService {
     // Best-match matchers (adapted from the API). When set, classification uses
     // the scoring engine; otherwise it falls back to legacy first-match-wins.
     this.matchers = null;
+    // Per-run classification tally for observability (distribution + unmatched).
+    this.classificationStats = {
+      total: 0,
+      matched: 0,
+      unmatched: 0,
+      byType: {},
+    };
   }
 
   /** Provide the resolved+adapted matcher set for scoring-based classification. */
@@ -96,12 +103,46 @@ export class FileDetectionService {
     this.matchers = matchers && matchers.length ? matchers : null;
   }
 
+  /**
+   * Detect document type, tallying the outcome for a per-run summary. Wraps the
+   * implementation so every return path is counted from one place.
+   */
+  async detectFile(filePath) {
+    const result = await this.#detectFileImpl(filePath);
+    const type = result?.detectedType ?? null;
+    this.classificationStats.total += 1;
+    if (type) {
+      this.classificationStats.matched += 1;
+      this.classificationStats.byType[type] =
+        (this.classificationStats.byType[type] ?? 0) + 1;
+    } else {
+      this.classificationStats.unmatched += 1;
+    }
+    return result;
+  }
+
+  /** Log the classification distribution for the run (call after processing). */
+  logClassificationSummary(logger) {
+    const s = this.classificationStats;
+    if (!s.total) return;
+    const mode = this.matchers ? 'scoring' : 'legacy';
+    const dist = Object.entries(s.byType)
+      .sort((a, b) => b[1] - a[1])
+      .map(([t, n]) => `${t}=${n}`)
+      .join(', ');
+    const log = logger?.info ? logger : console;
+    log.info(
+      `🧩 Classification summary (${mode}): ${s.total} docs, ${s.matched} matched, ` +
+        `${s.unmatched} unmatched${dist ? ` — ${dist}` : ''}`,
+    );
+  }
+
   /**
    * Detect document type from a file
    * @param {string} filePath - Path to the file to analyze
    * @returns {Promise<{detectedType: string|null, fields: Array, detectedPedimento: string|null, detectedPedimentoYear: number|null, text: string}>}
    */
-  async detectFile(filePath) {
+  async #detectFileImpl(filePath) {
     try {
       const fileExtension = path
         .extname(filePath)