@arela/uploader 1.0.24 → 1.1.1

package/docs/COMPLETE_USAGE_GUIDE.md

@@ -0,0 +1,1363 @@
+# 📘 Complete Usage Guide - ARELA-UPLOADER v1.0
+
+Este es un manual comprensivo que muestra cómo usar todas las características de ARELA-UPLOADER en escenarios reales.
+
+## Tabla de Contenidos
+
+1. [Instalación y Configuración](#instalación-y-configuración)
+2. [Conceptos Básicos](#conceptos-básicos)
+3. [Guías por Fase](#guías-por-fase)
+4. [Casos de Uso Prácticos](#casos-de-uso-prácticos)
+5. [Ejemplos Avanzados](#ejemplos-avanzados)
+6. [Solución de Problemas](#solución-de-problemas)
+
+---
+
+## Instalación y Configuración
+
+### Requisitos Previos
+- Node.js v14+
+- npm o yarn
+- Base de datos PostgreSQL (opcional, para persistencia)
+- Cuenta Supabase (para uploads a la nube)
+
+### Instalación
+
+```bash
+# Clonar repositorio
+git clone https://github.com/inspiraCode/arela-uploader.git
+cd arela-uploader
+
+# Instalar dependencias
+npm install
+
+# Configurar variables de entorno
+cp .env.example .env
+
+# Editar archivo .env con tus credenciales
+# SUPABASE_URL=https://...
+# SUPABASE_ANON_KEY=...
+# DB_HOST=localhost
+# DB_USER=postgres
+# etc.
+```
+
+### Estructura de Directorios
+
+```
+arela-uploader/
+├── src/
+│   ├── commands/             (Comandos CLI)
+│   ├── services/             (Lógica de negocio)
+│   ├── utils/                (Utilidades)
+│   ├── errors/               (Manejo de errores)
+│   ├── config/               (Configuración)
+│   └── index.js              (Punto de entrada)
+├── tests/                    (Suite de tests)
+├── docs/                     (Documentación)
+├── logs/                     (Logs de ejecución)
+├── uploads/                  (Directorio de uploads)
+└── package.json
+```
+
+---
+
+## Conceptos Básicos
+
+### 1. Sessions (Sesiones)
+Una sesión representa una serie de uploads. Rastrea el progreso, estado y metadatos.
+
+```javascript
+// Una sesión contiene:
+{
+  id: 'session-uuid',
+  userId: 'user-123',
+  status: 'active',           // active, paused, completed, error
+  fileCount: 10,
+  successCount: 8,
+  errorCount: 2,
+  startTime: '2025-11-14T10:30:00Z',
+  endTime: null,
+  totalSize: 52428800,        // en bytes
+  metadata: { ... }
+}
+```
+
+### 2. Uploads
+Cada archivo subido es un upload en la sesión.
+
+```javascript
+// Un upload contiene:
+{
+  id: 'upload-uuid',
+  sessionId: 'session-uuid',
+  fileName: 'document.pdf',
+  fileSize: 2048000,
+  status: 'completed',        // pending, uploading, completed, failed
+  uploadedUrl: 'https://...',
+  attempts: 1,
+  startTime: '2025-11-14T10:30:00Z',
+  endTime: '2025-11-14T10:30:02Z'
+}
+```
+
+### 3. Events (Eventos)
+Los eventos registran actividades importantes durante una sesión.
+
+```javascript
+// Un evento contiene:
+{
+  id: 'event-uuid',
+  sessionId: 'session-uuid',
+  eventType: 'upload',        // upload, error, warning, info
+  message: 'Archivo uploadado exitosamente',
+  details: { fileName: 'document.pdf', size: 2048000 },
+  timestamp: '2025-11-14T10:30:02Z'
+}
+```
+
+---
+
+## Guías por Fase
+
+### Phase 1: File Detection & Validation
+
+**¿Qué hace?** Detecta y valida archivos antes de procesarlos.
+
+#### Ejemplo 1: Validar un Archivo
+
+```javascript
+const FileDetection = require('./src/file-detection');
+
+async function validateFile() {
+  const result = FileDetection.validateFile('/path/to/document.pdf');
+  
+  if (result.isValid) {
+    console.log('✅ Archivo válido:', result.file.name);
+    console.log('   Tamaño:', result.file.size / 1024, 'KB');
+    console.log('   Tipo:', result.file.mimeType);
+  } else {
+    console.log('❌ Archivo inválido:');
+    result.errors.forEach(err => console.log('   -', err));
+  }
+}
+
+validateFile();
+```
+
+#### Ejemplo 2: Detectar Archivos en Directorio
+
+```javascript
+const FileDetection = require('./src/file-detection');
+
+async function detectFiles() {
+  const files = FileDetection.detectFilesInDirectory('/Users/documents');
+  
+  console.log(`📁 Encontrados ${files.length} archivos:\n`);
+  
+  files.forEach(file => {
+    console.log(`  📄 ${file.name}`);
+    console.log(`     Tipo: ${file.type}`);
+    console.log(`     Tamaño: ${file.size} bytes\n`);
+  });
+}
+
+detectFiles();
+```
+
+#### Ejemplo 3: Procesar Archivos con Sanitización
+
+```javascript
+const FileDetection = require('./src/file-detection');
+const FileSanitizer = require('./src/utils/FileSanitizer');
+
+async function processFiles() {
+  const files = FileDetection.detectFilesInDirectory('/uploads');
+  
+  const processed = files.map(file => ({
+    original: file.name,
+    sanitized: FileSanitizer.sanitizeFileName(file.name),
+    valid: FileDetection.validateFile(file.path).isValid
+  }));
+  
+  console.log('📋 Archivos procesados:');
+  processed.forEach(p => {
+    console.log(`\n  Original: ${p.original}`);
+    console.log(`  Sanitizado: ${p.sanitized}`);
+    console.log(`  Válido: ${p.valid ? '✅' : '❌'}`);
+  });
+}
+
+processFiles();
+```
+
+---
+
+### Phase 2: API Service Integration
+
+**¿Qué hace?** Integra con servicios API para subir archivos a la nube.
+
+#### Ejemplo 1: Upload Básico
+
+```javascript
+const UploadServiceFactory = require('./src/services/upload/UploadServiceFactory');
+
+async function uploadFile() {
+  try {
+    // Crear servicio
+    const uploader = UploadServiceFactory.createUploadService('supabase');
+    
+    // Autenticar
+    console.log('🔐 Autenticando...');
+    await uploader.authenticate();
+    console.log('✅ Autenticado');
+    
+    // Subir archivo
+    console.log('⬆️  Subiendo archivo...');
+    const result = await uploader.uploadFile('/path/to/file.pdf', {
+      bucket: 'documents',
+      public: false
+    });
+    
+    console.log('✅ Upload completado');
+    console.log('   URL:', result.url);
+    console.log('   Tamaño:', result.size, 'bytes');
+    
+    return result;
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+uploadFile();
+```
+
+#### Ejemplo 2: Upload con Reintentos
+
+```javascript
+const UploadServiceFactory = require('./src/services/upload/UploadServiceFactory');
+
+async function uploadWithRetry() {
+  try {
+    const uploader = UploadServiceFactory.createUploadService('supabase');
+    await uploader.authenticate();
+    
+    console.log('⬆️  Intentando upload con reintentos...');
+    
+    const result = await uploader.uploadFileWithRetry(
+      '/path/to/file.pdf',
+      { bucket: 'documents', public: false },
+      5  // máximo 5 intentos
+    );
+    
+    console.log('✅ Éxito después de', result.metadata.attempts, 'intento(s)');
+    return result;
+  } catch (error) {
+    console.error('❌ Falló después de reintentos:', error.message);
+  }
+}
+
+uploadWithRetry();
+```
+
+#### Ejemplo 3: Upload Múltiple
+
+```javascript
+const UploadServiceFactory = require('./src/services/upload/UploadServiceFactory');
+
+async function uploadMultiple() {
+  const files = [
+    '/path/to/file1.pdf',
+    '/path/to/file2.pdf',
+    '/path/to/file3.pdf'
+  ];
+  
+  try {
+    const uploader = UploadServiceFactory.createUploadService('supabase');
+    await uploader.authenticate();
+    
+    console.log(`⬆️  Subiendo ${files.length} archivos...`);
+    
+    const results = await Promise.all(
+      files.map(file =>
+        uploader.uploadFile(file, {
+          bucket: 'documents',
+          public: false
+        })
+      )
+    );
+    
+    const successful = results.filter(r => r.success).length;
+    console.log(`✅ ${successful}/${files.length} archivos subidos`);
+    
+    return results;
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+uploadMultiple();
+```
+
+---
+
+### Phase 3: Database Management
+
+**¿Qué hace?** Gestiona persistencia de datos en base de datos.
+
+#### Ejemplo 1: Crear y Gestionar Sesión
+
+```javascript
+const DatabaseService = require('./src/services/DatabaseService');
+
+async function manageSession() {
+  const db = new DatabaseService();
+  
+  try {
+    // Conectar
+    console.log('🔌 Conectando a BD...');
+    await db.connect();
+    console.log('✅ Conectado');
+    
+    // Crear sesión
+    console.log('📝 Creando sesión...');
+    const session = await db.createSession({
+      userId: 'user-123',
+      status: 'active',
+      startTime: new Date()
+    });
+    console.log('✅ Sesión creada:', session.id);
+    
+    // Actualizar sesión
+    await db.updateSession(session.id, {
+      fileCount: 5
+    });
+    console.log('✅ Sesión actualizada');
+    
+    // Desconectar
+    await db.disconnect();
+    console.log('✅ Desconectado');
+    
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+manageSession();
+```
+
+#### Ejemplo 2: Registrar Uploads
+
+```javascript
+const DatabaseService = require('./src/services/DatabaseService');
+const FileDetection = require('./src/file-detection');
+
+async function registerUploads() {
+  const db = new DatabaseService();
+  
+  try {
+    await db.connect();
+    
+    // Crear sesión
+    const session = await db.createSession({
+      userId: 'user-123',
+      status: 'active',
+      startTime: new Date()
+    });
+    
+    // Registrar archivos
+    const files = ['/file1.pdf', '/file2.pdf'];
+    
+    for (const filePath of files) {
+      const file = FileDetection.detectFile(filePath);
+      
+      const upload = await db.saveUpload({
+        sessionId: session.id,
+        filePath: file.path,
+        fileName: file.name,
+        fileSize: file.size,
+        mimeType: file.mimeType,
+        status: 'completed',
+        uploadedUrl: `https://bucket.storage/...`,
+        startTime: new Date(),
+        endTime: new Date()
+      });
+      
+      console.log(`✅ Registrado: ${file.name}`);
+    }
+    
+    await db.disconnect();
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+registerUploads();
+```
+
+#### Ejemplo 3: Obtener Estadísticas de Sesión
+
+```javascript
+const DatabaseService = require('./src/services/DatabaseService');
+
+async function getStatistics() {
+  const db = new DatabaseService();
+  
+  try {
+    await db.connect();
+    
+    // Obtener sesión
+    const session = await db.getSession('session-id');
+    console.log('📊 Sesión:', session.id);
+    console.log('   Estado:', session.status);
+    console.log('   Archivos:', session.fileCount);
+    console.log('   Exitosos:', session.successCount);
+    console.log('   Errores:', session.errorCount);
+    console.log('   Tamaño total:', session.totalSize / 1024 / 1024, 'MB');
+    
+    // Obtener uploads
+    const uploads = await db.getUploads('session-id');
+    console.log('\n📁 Uploads:');
+    uploads.forEach(upload => {
+      console.log(`  - ${upload.fileName} (${upload.status})`);
+    });
+    
+    // Obtener eventos
+    const events = await db.getEvents('session-id');
+    console.log('\n📝 Eventos:', events.length);
+    
+    await db.disconnect();
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+getStatistics();
+```
+
+---
+
+### Phase 4: File Operations & Logging
+
+**¿Qué hace?** Proporciona operaciones seguras de archivos y logging completo.
+
+#### Ejemplo 1: Operaciones de Archivo
+
+```javascript
+const FileOperations = require('./src/utils/FileOperations');
+
+async function fileOperations() {
+  try {
+    // Crear archivo
+    await FileOperations.createFile(
+      '/path/to/output.txt',
+      'Contenido del archivo'
+    );
+    console.log('✅ Archivo creado');
+    
+    // Leer archivo
+    const content = await FileOperations.readFile('/path/to/output.txt');
+    console.log('📖 Contenido:', content);
+    
+    // Copiar archivo
+    await FileOperations.copyFile(
+      '/path/to/output.txt',
+      '/path/to/backup.txt'
+    );
+    console.log('📋 Archivo copiado');
+    
+    // Obtener información
+    const stats = await FileOperations.getFileStats('/path/to/output.txt');
+    console.log('📊 Tamaño:', stats.size, 'bytes');
+    console.log('📅 Modificado:', stats.mtime);
+    
+    // Eliminar archivo
+    await FileOperations.deleteFile('/path/to/backup.txt');
+    console.log('🗑️  Archivo eliminado');
+    
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+fileOperations();
+```
+
+#### Ejemplo 2: Sistema de Logging
+
+```javascript
+const LoggingService = require('./src/services/LoggingService');
+
+function logging() {
+  const logger = LoggingService.getInstance();
+  
+  // Diferentes niveles
+  logger.trace('Información muy detallada');
+  logger.debug('Información de debug');
+  logger.info('Información general');
+  logger.warn('Advertencia importante');
+  logger.error('Error ocurrido');
+  
+  // Log con contexto
+  logger.info('Upload iniciado', {
+    fileName: 'document.pdf',
+    size: 2048000,
+    sessionId: 'session-123'
+  });
+  
+  // Log de error con stack
+  try {
+    throw new Error('Algo salió mal');
+  } catch (error) {
+    logger.error('Error en operación', error);
+  }
+  
+  console.log('✅ Logs registrados en:', logger.getLogFile());
+}
+
+logging();
+```
+
+---
+
+### Phase 5: Watch Mode & Sessions
+
+**¿Qué hace?** Monitorea directorios y procesa archivos automáticamente.
+
+#### Ejemplo 1: Modo Vigilancia Básico
+
+```bash
+# Iniciar vigilancia de directorio
+node -e "
+const WatchCommand = require('./src/commands/WatchCommand');
+
+(async () => {
+  const watch = new WatchCommand();
+  await watch.execute({
+    watchDir: '/Users/documents/uploads',
+    sessionName: 'main-session',
+    batchSize: 10,
+    debounceTime: 2000
+  });
+})();
+"
+
+# La sesión continúa hasta Ctrl+C
+# Cada archivo detectado se procesa automáticamente
+```
+
+#### Ejemplo 2: Vigilancia con Filtros
+
+```javascript
+const WatchCommand = require('./src/commands/WatchCommand');
+
+async function watchWithFilters() {
+  const watch = new WatchCommand();
+  
+  await watch.execute({
+    watchDir: '/uploads',
+    sessionName: 'pdf-session',
+    recursive: true,
+    batchSize: 5,
+    debounceTime: 1000,
+    fileFilter: ['.pdf', '.doc', '.docx'],
+    excludePatterns: ['*.tmp', '.DS_Store']
+  });
+}
+
+watchWithFilters();
+```
+
+#### Ejemplo 3: Gestión Manual de Sesiones
+
+```javascript
+const SessionManager = require('./src/services/SessionManager');
+
+async function manageSessions() {
+  try {
+    // Crear sesión
+    const session = await SessionManager.createSession({
+      name: 'Manual Upload Session',
+      userId: 'user-123',
+      description: 'Uploading documents'
+    });
+    console.log('✅ Sesión creada:', session.id);
+    
+    // Realizar operaciones...
+    
+    // Pausar sesión
+    await SessionManager.pauseSession(session.id);
+    console.log('⏸️  Sesión pausada');
+    
+    // Reanudar
+    await SessionManager.resumeSession(session.id);
+    console.log('▶️  Sesión reanudada');
+    
+    // Completar
+    await SessionManager.completeSession(session.id);
+    console.log('✅ Sesión completada');
+    
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+  }
+}
+
+manageSessions();
+```
+
+---
+
+### Phase 6: Signal Handling & Graceful Shutdown
+
+**¿Qué hace?** Maneja señales del sistema para apagado elegante.
+
+#### Ejemplo 1: Setup Básico de Señales
+
+```javascript
+const SignalHandler = require('./src/services/SignalHandler');
+const DatabaseService = require('./src/services/DatabaseService');
+
+async function setupSignalHandling() {
+  const signalHandler = SignalHandler.getInstance();
+  const db = new DatabaseService();
+  
+  // Conectar a BD
+  await db.connect();
+  
+  // Registrar cleanup de BD
+  signalHandler.registerCleanup('database', async () => {
+    console.log('🗄️  Cerrando conexión a BD...');
+    await db.disconnect();
+  });
+  
+  // Registrar handler de SIGINT (Ctrl+C)
+  signalHandler.on('SIGINT', async () => {
+    console.log('\n✋ Apagado iniciado');
+    await signalHandler.shutdown('SIGINT');
+  });
+  
+  // Setup
+  signalHandler.setup();
+  
+  console.log('✅ Signal handling configurado');
+}
+
+setupSignalHandling();
+```
+
+#### Ejemplo 2: Apagado Elegante Completo
+
+```javascript
+const SignalHandler = require('./src/services/SignalHandler');
+const CleanupManager = require('./src/services/CleanupManager');
+const DatabaseService = require('./src/services/DatabaseService');
+
+async function gracefulShutdown() {
+  const signalHandler = SignalHandler.getInstance();
+  const cleanupManager = new CleanupManager();
+  const db = new DatabaseService();
+  
+  await db.connect();
+  
+  // Registrar tareas de limpieza (orden LIFO)
+  cleanupManager.register('sessions', async () => {
+    console.log('💾 Guardando sesiones activas...');
+    // guardar sesiones
+  });
+  
+  cleanupManager.register('uploads', async () => {
+    console.log('⬆️  Finalizando uploads...');
+    // finalizar uploads
+  });
+  
+  cleanupManager.register('database', async () => {
+    console.log('🗄️  Cerrando BD...');
+    await db.disconnect();
+  });
+  
+  // Manejar señales
+  signalHandler.on('SIGINT', async () => {
+    console.log('\n⏹️ Apagado elegante iniciado...');
+    console.log('Ejecutando limpieza en orden...\n');
+    
+    await cleanupManager.cleanup();
+    
+    console.log('\n✅ Apagado completado');
+    process.exit(0);
+  });
+  
+  signalHandler.setup();
+}
+
+gracefulShutdown();
+```
+
+---
+
+### Phase 7: Advanced Features & Integration
+
+**¿Qué hace?** Proporciona análisis, reportes y monitoreo avanzado.
+
+#### Ejemplo 1: Filtrado Avanzado
+
+```javascript
+const AdvancedFilterService = require('./src/services/AdvancedFilterService');
+
+async function advancedFiltering() {
+  const filterService = new AdvancedFilterService();
+  
+  const files = [
+    '/file1.pdf',
+    '/file2.doc',
+    '/file3.pdf',
+    '/file4.xlsx'
+  ];
+  
+  // Filtrar por múltiples criterios
+  const filtered = filterService.filterFiles(files, {
+    extensions: ['.pdf'],
+    minSize: 1024,
+    maxSize: 50 * 1024 * 1024,
+    dateRange: {
+      from: new Date('2025-11-01'),
+      to: new Date('2025-11-14')
+    }
+  });
+  
+  console.log('📋 Resultados del filtrado:');
+  console.log('   Original:', files.length);
+  console.log('   Filtrado:', filtered.length);
+  
+  // Usar presets
+  const pdfsOnly = filterService.applyPreset(files, 'pdfOnly');
+  console.log('   PDFs solo:', pdfsOnly.length);
+}
+
+advancedFiltering();
+```
+
+#### Ejemplo 2: Generación de Reportes
+
+```javascript
+const ReportingService = require('./src/services/ReportingService');
+const DatabaseService = require('./src/services/DatabaseService');
+
+async function generateReports() {
+  const db = new DatabaseService();
+  const reportingService = new ReportingService();
+  
+  await db.connect();
+  
+  // Obtener sesión
+  const session = await db.getSession('session-id');
+  
+  // Generar reporte de sesión
+  const sessionReport = reportingService.generateSessionReport(session);
+  console.log('📊 Reporte de Sesión:');
+  console.log('   Archivos:', sessionReport.summary.totalUploads);
+  console.log('   Exitosos:', sessionReport.summary.successCount);
+  console.log('   Errores:', sessionReport.summary.errorCount);
+  
+  // Exportar a JSON
+  await reportingService.exportReportJson(
+    sessionReport,
+    './reports/session-report.json'
+  );
+  console.log('💾 Reporte guardado en JSON');
+  
+  // Exportar a CSV
+  await reportingService.exportReportCsv(
+    sessionReport,
+    './reports/session-report.csv'
+  );
+  console.log('💾 Reporte guardado en CSV');
+  
+  await db.disconnect();
+}
+
+generateReports();
+```
+
+#### Ejemplo 3: Benchmarking de Rendimiento
+
+```javascript
+const BenchmarkingService = require('./src/services/BenchmarkingService');
+const UploadServiceFactory = require('./src/services/upload/UploadServiceFactory');
+
+async function benchmarkPerformance() {
+  const benchmark = new BenchmarkingService();
+  const uploader = UploadServiceFactory.createUploadService('supabase');
+  
+  await uploader.authenticate();
+  
+  // Iniciar benchmark
+  const bench = benchmark.startBenchmark('upload-test');
+  
+  // Marcar puntos
+  benchmark.mark(bench, 'validation-complete');
+  
+  // Ejecutar upload
+  await uploader.uploadFile('/path/to/file.pdf');
+  benchmark.mark(bench, 'upload-complete');
+  
+  // Completar
+  const result = benchmark.completeBenchmark(bench);
+  
+  console.log('⏱️  Resultados del Benchmark:');
+  console.log('   Duración:', result.duration, 'ms');
+  console.log('   Memoria:', result.memory, 'bytes');
+  
+  // Generar reporte
+  const report = benchmark.generateBenchmarkReport();
+}
+
+benchmarkPerformance();
+```
+
+#### Ejemplo 4: Monitoreo en Tiempo Real
+
+```javascript
+const MonitoringService = require('./src/services/MonitoringService');
+
+async function setupMonitoring() {
+  const monitor = new MonitoringService();
+  
+  // Agregar reglas de alerta
+  monitor.addAlertRule({
+    name: 'high-memory',
+    type: 'memory',
+    operator: 'greaterThan',
+    threshold: 500,
+    severity: 'warning'
+  });
+  
+  // Suscribirse a alertas
+  monitor.subscribe('critical', (alert) => {
+    console.error('🔴 CRÍTICA:', alert.message);
+  });
+  
+  monitor.subscribe('warning', (alert) => {
+    console.warn('🟡 ADVERTENCIA:', alert.message);
+  });
+  
+  // Actualizar métricas
+  setInterval(() => {
+    monitor.updateMetrics({
+      cpu: Math.random() * 100,
+      memory: Math.random() * 600,
+      disk: Math.random() * 100,
+      connections: Math.floor(Math.random() * 50),
+      errorRate: Math.random() * 0.1
+    });
+  }, 5000);
+  
+  console.log('✅ Monitoreo iniciado');
+}
+
+setupMonitoring();
+```
+
+---
+
+## Casos de Uso Prácticos
+
+### Caso 1: Workflow Completo (Upload Simple)
+
+```javascript
+const FileDetection = require('./src/file-detection');
+const UploadServiceFactory = require('./src/services/upload/UploadServiceFactory');
+const DatabaseService = require('./src/services/DatabaseService');
+const LoggingService = require('./src/services/LoggingService');
+
+async function completeWorkflow(filePath) {
+  const logger = LoggingService.getInstance();
+  const db = new DatabaseService();
+  
+  try {
+    logger.info('=== INICIANDO WORKFLOW COMPLETO ===');
+    
+    // STEP 1: Validar archivo
+    logger.info('📋 STEP 1: Validando archivo...');
+    const validation = FileDetection.validateFile(filePath);
+    
+    if (!validation.isValid) {
+      throw new Error('Archivo inválido: ' + validation.errors.join(', '));
+    }
+    logger.info('✅ Archivo válido');
+    
+    // STEP 2: Conectar BD
+    logger.info('🔌 STEP 2: Conectando BD...');
+    await db.connect();
+    logger.info('✅ Conectado');
+    
+    // STEP 3: Crear sesión
+    logger.info('📝 STEP 3: Creando sesión...');
+    const session = await db.createSession({
+      userId: 'user-123',
+      status: 'active',
+      startTime: new Date()
+    });
+    logger.info('✅ Sesión creada: ' + session.id);
+    
+    // STEP 4: Autenticar con proveedor
+    logger.info('🔐 STEP 4: Autenticando con Supabase...');
+    const uploader = UploadServiceFactory.createUploadService('supabase');
+    await uploader.authenticate();
+    logger.info('✅ Autenticado');
+    
+    // STEP 5: Subir archivo
+    logger.info('⬆️  STEP 5: Subiendo archivo...');
+    const uploadResult = await uploader.uploadFile(filePath);
+    logger.info('✅ Subido a: ' + uploadResult.url);
+    
+    // STEP 6: Registrar en BD
+    logger.info('📝 STEP 6: Registrando en BD...');
+    const file = FileDetection.detectFile(filePath);
+    const upload = await db.saveUpload({
+      sessionId: session.id,
+      filePath: file.path,
+      fileName: file.name,
+      fileSize: file.size,
+      mimeType: file.mimeType,
+      status: 'completed',
+      uploadedUrl: uploadResult.url,
+      startTime: new Date(),
+      endTime: new Date()
+    });
+    logger.info('✅ Registrado en BD');
+    
+    // STEP 7: Actualizar sesión
+    logger.info('🔄 STEP 7: Actualizando sesión...');
+    await db.updateSession(session.id, {
+      status: 'completed',
+      successCount: 1,
+      fileCount: 1,
+      endTime: new Date()
+    });
+    logger.info('✅ Sesión actualizada');
+    
+    await db.disconnect();
+    
+    logger.info('=== WORKFLOW COMPLETADO CON ÉXITO ===\n');
+    
+    return {
+      session,
+      upload,
+      uploadResult
+    };
+    
+  } catch (error) {
+    logger.error('ERROR EN WORKFLOW', error);
+    await db.disconnect();
+    throw error;
+  }
+}
+
+// Uso
+completeWorkflow('/path/to/document.pdf')
+  .then(result => console.log('✅ Resultado:', result))
+  .catch(error => console.error('❌ Error:', error.message));
+```
+
+### Caso 2: Vigilancia Continua con Reportes
+
+```javascript
+const WatchCommand = require('./src/commands/WatchCommand');
+const DatabaseService = require('./src/services/DatabaseService');
+const ReportingService = require('./src/services/ReportingService');
+const LoggingService = require('./src/services/LoggingService');
+
+async function continuousWatchWithReports() {
+  const logger = LoggingService.getInstance();
+  const db = new DatabaseService();
+  const reportingService = new ReportingService();
+  
+  try {
+    await db.connect();
+    
+    // Crear sesión de vigilancia
+    const session = await db.createSession({
+      userId: 'system',
+      status: 'active',
+      startTime: new Date()
+    });
+    
+    logger.info('🚀 Iniciando vigilancia continua');
+    
+    // Iniciar vigilancia
+    const watch = new WatchCommand();
+    await watch.execute({
+      watchDir: '/uploads',
+      sessionName: 'continuous-watch-' + Date.now(),
+      batchSize: 10,
+      debounceTime: 2000
+    });
+    
+    // Generar reportes cada 1 hora
+    setInterval(async () => {
+      const updatedSession = await db.getSession(session.id);
+      const report = reportingService.generateSessionReport(updatedSession);
+      
+      logger.info('📊 REPORTE PERIÓDICO', {
+        totalUploads: report.summary.totalUploads,
+        successCount: report.summary.successCount,
+        errorCount: report.summary.errorCount
+      });
+      
+      await reportingService.exportReportJson(
+        report,
+        `./reports/periodic-${Date.now()}.json`
+      );
+    }, 60 * 60 * 1000);  // Cada hora
+    
+  } catch (error) {
+    logger.error('Error en vigilancia continua', error);
+  }
+}
+
+continuousWatchWithReports();
+```
+
+### Caso 3: Procesamiento por Lotes con Monitoreo
+
+```javascript
+const BatchProcessor = require('./src/services/BatchProcessor');
+const MonitoringService = require('./src/services/MonitoringService');
+const LoggingService = require('./src/services/LoggingService');
+
+async function processWithMonitoring(files) {
+  const logger = LoggingService.getInstance();
+  const processor = new BatchProcessor({ batchSize: 10 });
+  const monitor = new MonitoringService();
+  
+  // Configurar alertas
+  monitor.addAlertRule({
+    name: 'high-error-rate',
+    type: 'errorRate',
+    operator: 'greaterThan',
+    threshold: 0.2,
+    severity: 'critical'
+  });
+  
+  // Suscribirse a alertas
+  monitor.subscribe('critical', (alert) => {
+    logger.error('🔴 ALERTA:', alert.message);
+  });
+  
+  // Procesar archivos
+  for (const file of files) {
+    processor.addFile(file);
+  }
+  
+  const results = await processor.processBatch();
+  
+  // Actualizar métricas
+  const successful = results.filter(r => r.success).length;
+  const errorRate = (results.length - successful) / results.length;
+  
+  monitor.updateMetrics({
+    errorRate,
+    connections: 5,
+    memory: 256,
+    cpu: 45,
+    disk: 65
+  });
+  
+  // Generar reporte
+  const health = monitor.getHealthStatus();
+  logger.info('📊 Estado del Sistema:', health);
+  
+  return results;
+}
+```
+
+---
+
+## Ejemplos Avanzados
+
+### Integración Completa con Todas las Fases
+
+```javascript
+const FileDetection = require('./src/file-detection');
+const UploadServiceFactory = require('./src/services/upload/UploadServiceFactory');
+const DatabaseService = require('./src/services/DatabaseService');
+const LoggingService = require('./src/services/LoggingService');
+const SignalHandler = require('./src/services/SignalHandler');
+const AdvancedFilterService = require('./src/services/AdvancedFilterService');
+const ReportingService = require('./src/services/ReportingService');
+const BenchmarkingService = require('./src/services/BenchmarkingService');
+const MonitoringService = require('./src/services/MonitoringService');
+
+async function fullIntegration(dirPath, userId) {
+  const logger = LoggingService.getInstance();
+  const db = new DatabaseService();
+  const signalHandler = SignalHandler.getInstance();
+  
+  try {
+    logger.info('🚀 INICIANDO INTEGRACIÓN COMPLETA');
+    
+    // Setup signal handling
+    signalHandler.registerCleanup('database', async () => {
+      await db.disconnect();
+    });
+    signalHandler.setup();
+    
+    // Conectar BD
+    await db.connect();
+    
+    // Crear sesión
+    const session = await db.createSession({
+      userId,
+      status: 'active',
+      startTime: new Date()
+    });
+    
+    // Detectar archivos
+    const files = FileDetection.detectFilesInDirectory(dirPath);
+    
+    // Filtrado avanzado
+    const filterService = new AdvancedFilterService();
+    const filtered = filterService.filterFiles(files.map(f => f.path), {
+      extensions: ['.pdf', '.doc', '.docx'],
+      maxSize: 50 * 1024 * 1024
+    });
+    
+    // Benchmarking
+    const benchmark = new BenchmarkingService();
+    const bench = benchmark.startBenchmark('full-workflow');
+    
+    // Upload con monitoreo
+    const uploader = UploadServiceFactory.createUploadService('supabase');
+    await uploader.authenticate();
+    
+    const monitor = new MonitoringService();
+    monitor.addAlertRule({
+      name: 'upload-failures',
+      type: 'errorRate',
+      operator: 'greaterThan',
+      threshold: 0.1,
+      severity: 'critical'
+    });
+    
+    const uploadResults = [];
+    let successful = 0;
+    let failed = 0;
+    
+    for (const filePath of filtered) {
+      try {
+        const result = await uploader.uploadFile(filePath, {
+          bucket: 'documents',
+          public: false
+        });
+        
+        const file = FileDetection.detectFile(filePath);
+        const upload = await db.saveUpload({
+          sessionId: session.id,
+          filePath: file.path,
+          fileName: file.name,
+          fileSize: file.size,
+          mimeType: file.mimeType,
+          status: 'completed',
+          uploadedUrl: result.url,
+          startTime: new Date(),
+          endTime: new Date()
+        });
+        
+        uploadResults.push(upload);
+        successful++;
+      } catch (error) {
+        failed++;
+        logger.error('Error uploadando archivo', { error: error.message });
+        
+        await db.saveEvent({
+          sessionId: session.id,
+          eventType: 'error',
+          message: 'Error uploadando archivo',
+          details: { error: error.message }
+        });
+      }
+    }
+    
+    // Completar benchmark
+    benchmark.mark(bench, 'uploads-complete');
+    const benchResult = benchmark.completeBenchmark(bench);
+    
+    // Actualizar sesión
+    await db.updateSession(session.id, {
+      status: 'completed',
+      successCount: successful,
+      errorCount: failed,
+      fileCount: successful + failed,
+      endTime: new Date()
+    });
+    
+    // Generar reportes
+    const reportingService = new ReportingService();
+    const updatedSession = await db.getSession(session.id);
+    const report = reportingService.generateSessionReport(updatedSession);
+    
+    await reportingService.exportReportJson(
+      report,
+      `./reports/full-workflow-${Date.now()}.json`
+    );
+    
+    // Monitoreo final
+    monitor.updateMetrics({
+      errorRate: failed / (successful + failed),
+      memory: process.memoryUsage().heapUsed,
+      cpu: 0
+    });
+    
+    const health = monitor.getHealthStatus();
+    
+    logger.info('✅ INTEGRACIÓN COMPLETADA', {
+      filesDetected: files.length,
+      filesFiltered: filtered.length,
+      filesUploaded: successful,
+      filesFailed: failed,
+      duration: benchResult.duration,
+      health: health.status
+    });
+    
+    await db.disconnect();
+    
+    return {
+      session,
+      uploadResults,
+      report,
+      benchmark: benchResult,
+      health
+    };
+    
+  } catch (error) {
+    logger.error('ERROR EN INTEGRACIÓN COMPLETA', error);
+    await db.disconnect();
+    throw error;
+  }
+}
+
+// Uso
+fullIntegration('/uploads', 'user-123')
+  .then(result => console.log('✅ Éxito:', result))
+  .catch(error => console.error('❌ Error:', error.message));
+```
+
+---
+
+## Solución de Problemas
+
+### Problema: "ECONNREFUSED" en BD
+
+**Síntoma:** Error de conexión a base de datos
+
+**Solución:**
+```bash
+# Verificar que PostgreSQL está corriendo
+psql --version
+
+# Verificar variables de entorno
+echo $DB_HOST
+echo $DB_PORT
+echo $DB_NAME
+
+# Verificar credenciales
+psql -h localhost -U postgres
+```
+
+### Problema: "Authentication Failed" con Supabase
+
+**Síntoma:** Error de autenticación con API
+
+**Solución:**
+```bash
+# Verificar variables de entorno
+echo $SUPABASE_URL
+echo $SUPABASE_ANON_KEY
+
+# Verificar credenciales en Supabase console
+# Generar nuevas claves si es necesario
+
+# Probar conexión
+curl -H "Authorization: Bearer $SUPABASE_ANON_KEY" $SUPABASE_URL
+```
+
+### Problema: Archivos no se detectan en vigilancia
+
+**Síntoma:** WatchCommand no procesa archivos nuevos
+
+**Solución:**
+```javascript
+// Aumentar debounceTime
+await watch.execute({
+  watchDir: '/uploads',
+  sessionName: 'debug-session',
+  debounceTime: 5000  // Aumentar a 5 segundos
+});
+
+// Verificar permisos de lectura
+ls -la /uploads
+
+// Verificar logs
+tail -f logs/app-*.log
+```
+
+### Problema: Memoria alta durante uploads
+
+**Síntoma:** Aplicación usa mucha memoria
+
+**Solución:**
+```javascript
+// Reducir tamaño de lote
+const batch = new BatchProcessor({ batchSize: 5 });
+
+// Procesar de a uno
+for (const file of files) {
+  await uploader.uploadFile(file);
+  // Dar tiempo para garbage collection
+  await new Promise(resolve => setTimeout(resolve, 100));
+}
+```
+
+---
+
+## Resumen de Comandos Útiles
+
+```bash
+# Validar archivo específico
+node -e "
+const FileDetection = require('./src/file-detection');
+console.log(FileDetection.validateFile('/path/to/file.pdf'));
+"
+
+# Iniciar vigilancia
+npm run watch -- --dir /uploads
+
+# Generar reportes
+npm run report -- --session-id session-uuid
+
+# Ejecutar tests
+npm test
+
+# Ver logs en tiempo real
+tail -f logs/app-$(date +%Y-%m-%d).log
+
+# Cleanup de logs antiguos
+npm run cleanup-logs -- --days 30
+```
+
+---
+
+## Documentación Adicional
+
+- [Phase 1: File Detection](./PHASE_1_FILE_DETECTION.md)
+- [Phase 2: API Integration](./PHASE_2_API_INTEGRATION.md)
+- [Phase 3: Database](./PHASE_3_DATABASE_MANAGEMENT.md)
+- [Phase 4: File Operations](./PHASE_4_FILE_OPERATIONS.md)
+- [Phase 5: Watch Mode](./PHASE_5_WATCH_MODE.md)
+- [Phase 6: Signal Handling](./PHASE_6_SIGNAL_HANDLING.md)
+- [Phase 7: Advanced Features](./PHASE_7_ADVANCED_FEATURES.md)
+
+---
+
+**ARELA-UPLOADER v1.0** | Documentación Completa | Noviembre 2025
+