@arela/uploader 1.0.24 → 1.1.0

package/docs/DATABASESERVICE_IMPROVEMENTS.md

@@ -0,0 +1,546 @@
+# DatabaseService - Mejoras Fase 5
+
+**Archivo**: `src/services/DatabaseService.js`  
+**Tamaño Original**: 1692 líneas  
+**Tamaño Nuevo**: 2078 líneas  
+**Líneas Agregadas**: +386  
+**Métodos Originales**: 16  
+**Métodos Nuevos**: 6  
+**Total Métodos**: 22  
+**Validación**: ✅ Sintaxis correcta
+
+---
+
+## 📋 Resumen de Cambios
+
+Se agregaron 6 nuevos métodos al DatabaseService para soportar el tracking de eventos de upload, reintentos y generación de estadísticas. Estos métodos se integran directamente con el LoggingService y habilitan la persistencia de datos en las tablas `watch_uploads` y `watch_events`.
+
+---
+
+## 🆕 Nuevos Métodos Implementados
+
+### 1. insertUploadEvent(uploadEvent, sessionId)
+**Propósito**: Guardar evento de upload en la tabla `watch_uploads`
+
+**Parámetros**:
+- `uploadEvent` (Object): Evento de upload del LoggingService
+  - timestamp (ISO8601)
+  - strategy ('individual' | 'batch' | 'full-structure')
+  - fileCount (number)
+  - successCount (number)
+  - failureCount (number)
+  - retryCount (number)
+  - duration (milliseconds)
+  - status (string)
+  - metadata (object)
+- `sessionId` (string): ID único de sesión
+
+**Retorna**: Promise<Object> - Registro insertado
+
+**Ejemplo**:
+```javascript
+const uploadEvent = await databaseService.insertUploadEvent({
+  timestamp: '2025-11-14T10:30:00Z',
+  strategy: 'batch',
+  fileCount: 20,
+  successCount: 18,
+  failureCount: 2,
+  retryCount: 3,
+  duration: 5000,
+  status: 'completed',
+  metadata: { notes: 'Batch upload completed' }
+}, 'session-123');
+```
+
+**Tabla watch_uploads**:
+```sql
+{
+  id: UUID (auto-generated),
+  session_id: VARCHAR,
+  timestamp: TIMESTAMP,
+  strategy: VARCHAR ('individual' | 'batch' | 'full-structure'),
+  file_count: INTEGER,
+  success_count: INTEGER,
+  failure_count: INTEGER,
+  retry_count: INTEGER,
+  duration_ms: INTEGER,
+  status: VARCHAR,
+  metadata: JSONB,
+  created_at: TIMESTAMP (auto)
+}
+```
+
+---
+
+### 2. insertRetryEvent(uploadEventId, sessionId, retryEvent)
+**Propósito**: Guardar evento de reintento en la tabla `watch_events`
+
+**Parámetros**:
+- `uploadEventId` (string): ID del evento de upload padre
+- `sessionId` (string): ID de sesión
+- `retryEvent` (Object): Evento de reintento del LoggingService
+  - timestamp (ISO8601)
+  - attemptNumber (number)
+  - error (string)
+  - backoffMs (number)
+
+**Retorna**: Promise<Object> - Registro insertado
+
+**Ejemplo**:
+```javascript
+const retryEvent = await databaseService.insertRetryEvent(
+  'upload-event-id-456',
+  'session-123',
+  {
+    timestamp: '2025-11-14T10:31:00Z',
+    attemptNumber: 1,
+    error: 'Connection timeout',
+    backoffMs: 1000
+  }
+);
+```
+
+**Tabla watch_events**:
+```sql
+{
+  id: UUID (auto-generated),
+  upload_event_id: UUID,
+  session_id: VARCHAR,
+  timestamp: TIMESTAMP,
+  attempt_number: INTEGER,
+  error_message: VARCHAR,
+  backoff_ms: INTEGER,
+  type: VARCHAR ('retry', 'error', 'warning'),
+  created_at: TIMESTAMP (auto)
+}
+```
+
+---
+
+### 3. getSessionUploadHistory(sessionId, options)
+**Propósito**: Recuperar historial de uploads para una sesión
+
+**Parámetros**:
+- `sessionId` (string): ID de sesión a consultar
+- `options` (Object - opcional):
+  - limit (number, default: 100)
+  - offset (number, default: 0)
+  - strategy (string, optional - filter)
+
+**Retorna**: Promise<Array> - Array de eventos de upload
+
+**Ejemplo**:
+```javascript
+// Obtener últimos 20 uploads de la sesión
+const uploads = await databaseService.getSessionUploadHistory('session-123', {
+  limit: 20,
+  offset: 0,
+  strategy: 'batch' // opcional
+});
+
+// Resultado:
+// [
+//   {
+//     id: '...',
+//     session_id: 'session-123',
+//     timestamp: '2025-11-14T10:30:00Z',
+//     strategy: 'batch',
+//     file_count: 20,
+//     success_count: 18,
+//     failure_count: 2,
+//     retry_count: 3,
+//     duration_ms: 5000,
+//     status: 'completed'
+//   },
+//   ...
+// ]
+```
+
+---
+
+### 4. getUploadRetryHistory(uploadEventId, options)
+**Propósito**: Recuperar historial de reintentos para un upload específico
+
+**Parámetros**:
+- `uploadEventId` (string): ID del evento de upload
+- `options` (Object - opcional):
+  - limit (number, default: 100)
+  - offset (number, default: 0)
+
+**Retorna**: Promise<Array> - Array de eventos de reintento
+
+**Ejemplo**:
+```javascript
+const retries = await databaseService.getUploadRetryHistory('upload-event-id-456', {
+  limit: 10,
+  offset: 0
+});
+
+// Resultado:
+// [
+//   {
+//     id: '...',
+//     upload_event_id: 'upload-event-id-456',
+//     timestamp: '2025-11-14T10:31:00Z',
+//     attempt_number: 1,
+//     error_message: 'Connection timeout',
+//     backoff_ms: 1000,
+//     type: 'retry'
+//   },
+//   {
+//     id: '...',
+//     upload_event_id: 'upload-event-id-456',
+//     timestamp: '2025-11-14T10:31:02Z',
+//     attempt_number: 2,
+//     error_message: null,
+//     backoff_ms: 0,
+//     type: 'retry'
+//   },
+//   ...
+// ]
+```
+
+---
+
+### 5. getSessionStatistics(sessionId)
+**Propósito**: Calcular estadísticas completas de una sesión
+
+**Parámetros**:
+- `sessionId` (string): ID de sesión a analizar
+
+**Retorna**: Promise<Object> - Objeto con estadísticas completas
+
+**Estructura Retornada**:
+```javascript
+{
+  sessionId: 'session-123',
+  totalUploadEvents: 15,
+  totalRetryEvents: 8,
+  totalFileCount: 250,
+  totalSuccessCount: 245,
+  totalFailureCount: 5,
+  totalRetryCount: 8,
+  totalDuration: 45000,
+  byStrategy: {
+    individual: {
+      uploadCount: 5,
+      totalFiles: 50,
+      totalSuccess: 48,
+      totalFailure: 2,
+      successRate: 96.00,
+      totalDuration: 15000
+    },
+    batch: {
+      uploadCount: 8,
+      totalFiles: 150,
+      totalSuccess: 145,
+      totalFailure: 5,
+      successRate: 96.67,
+      totalDuration: 20000
+    },
+    'full-structure': {
+      uploadCount: 2,
+      totalFiles: 50,
+      totalSuccess: 52,
+      totalFailure: 0,
+      successRate: 100.00,
+      totalDuration: 10000
+    }
+  },
+  retryStats: {
+    totalRetries: 8,
+    uniqueUploadsWithRetries: 4,
+    totalRetryDuration: 7000
+  }
+}
+```
+
+**Ejemplo de Uso**:
+```javascript
+const stats = await databaseService.getSessionStatistics('session-123');
+console.log(`Tasa de éxito: ${(stats.totalSuccessCount / (stats.totalSuccessCount + stats.totalFailureCount) * 100).toFixed(2)}%`);
+console.log(`Estrategia más usada: batch (${stats.byStrategy.batch.uploadCount} uploads)`);
+console.log(`Uploads con reintentos: ${stats.retryStats.uniqueUploadsWithRetries}`);
+```
+
+---
+
+### 6. cleanupOldSessions(daysOld)
+**Propósito**: Eliminar datos de sesiones antiguas (limpieza)
+
+**Parámetros**:
+- `daysOld` (number, default: 30): Eliminar sesiones más antiguas que esto
+
+**Retorna**: Promise<Object>
+```javascript
+{
+  deletedUploads: number,
+  deletedEvents: number,
+  sessionsDeleted: number
+}
+```
+
+**Ejemplo**:
+```javascript
+// Eliminar sesiones más antiguas de 30 días
+const result = await databaseService.cleanupOldSessions(30);
+console.log(`Eliminadas ${result.sessionsDeleted} sesiones antiguas`);
+console.log(`- ${result.deletedUploads} registros de upload`);
+console.log(`- ${result.deletedEvents} eventos`);
+```
+
+---
+
+## 🔌 Integración con LoggingService
+
+### Flujo de Datos
+
+```
+WatchCommand
+    ↓
+uploadIndividual/uploadBatch/uploadFullStructure
+    ↓
+logger.recordUploadEvent(uploadEvent)  ← LoggingService
+    ↓
+databaseService.insertUploadEvent(...)  ← DatabaseService
+    ↓
+watch_uploads table
+```
+
+### Ejemplo de Integración Completa
+
+```javascript
+import databaseService from './DatabaseService.js';
+import logger from './LoggingService.js';
+
+// En WatchCommand.js
+const sessionId = randomUUID();
+logger.initializeSession(sessionId);
+
+// Durante upload
+const uploadEventId = logger.recordUploadEvent({
+  strategy: 'batch',
+  fileCount: 20,
+  successCount: 18,
+  failureCount: 2,
+  duration: 5000
+});
+
+// Guardar en BD
+const dbRecord = await databaseService.insertUploadEvent(
+  {
+    strategy: 'batch',
+    fileCount: 20,
+    successCount: 18,
+    failureCount: 2,
+    duration: 5000
+  },
+  sessionId
+);
+
+// En reintento
+logger.recordRetryEvent(
+  uploadEventId,
+  1,
+  'Connection timeout',
+  1000
+);
+
+// Guardar retry en BD
+await databaseService.insertRetryEvent(
+  dbRecord.id,
+  sessionId,
+  {
+    timestamp: new Date().toISOString(),
+    attemptNumber: 1,
+    error: 'Connection timeout',
+    backoffMs: 1000
+  }
+);
+
+// Al finalizar
+const stats = await databaseService.getSessionStatistics(sessionId);
+const report = logger.formatSessionReport();
+```
+
+---
+
+## 🛡️ Características de Robustez
+
+### Retry Logic
+Todos los métodos de DatabaseService utilizan `#queryWithRetry()` con:
+- Exponential backoff (1s, 2s, 4s, ... max 30s)
+- Detección automática de errores retriables
+- Logging detallado de reintentos
+
+### Error Handling
+- Try-catch blocks en todos los métodos
+- Logging de errores con contexto
+- Devolución de valores por defecto en caso de falla
+- No lanzamiento de excepciones no capturadas
+
+### Performance
+- Batch queries para operaciones grandes
+- Pagination support (limit/offset)
+- Índices recomendados en session_id y timestamp
+- Cleanup automática de datos antiguos
+
+---
+
+## 📊 Rendimiento Estimado
+
+### Inserciones
+- insertUploadEvent(): ~100-200ms (con retry)
+- insertRetryEvent(): ~50-100ms (con retry)
+
+### Consultas
+- getSessionUploadHistory(): ~200-500ms (depende del rango)
+- getUploadRetryHistory(): ~100-300ms
+- getSessionStatistics(): ~500ms-1s (con aggregations)
+
+### Cleanup
+- cleanupOldSessions(30): ~1-2s (depende del volumen)
+
+---
+
+## 🗄️ Esquema SQL Recomendado
+
+### Tabla watch_uploads
+```sql
+CREATE TABLE watch_uploads (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id VARCHAR(36) NOT NULL,
+  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  strategy VARCHAR(20) NOT NULL, -- 'individual', 'batch', 'full-structure'
+  file_count INTEGER NOT NULL DEFAULT 0,
+  success_count INTEGER NOT NULL DEFAULT 0,
+  failure_count INTEGER NOT NULL DEFAULT 0,
+  retry_count INTEGER NOT NULL DEFAULT 0,
+  duration_ms INTEGER NOT NULL DEFAULT 0,
+  status VARCHAR(20) DEFAULT 'completed',
+  metadata JSONB,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  
+  CONSTRAINT fk_session FOREIGN KEY (session_id) 
+    REFERENCES watch_sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_watch_uploads_session_id ON watch_uploads(session_id);
+CREATE INDEX idx_watch_uploads_timestamp ON watch_uploads(timestamp);
+CREATE INDEX idx_watch_uploads_strategy ON watch_uploads(strategy);
+```
+
+### Tabla watch_events
+```sql
+CREATE TABLE watch_events (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  upload_event_id UUID,
+  session_id VARCHAR(36) NOT NULL,
+  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  attempt_number INTEGER,
+  error_message VARCHAR(500),
+  backoff_ms INTEGER DEFAULT 0,
+  type VARCHAR(20) NOT NULL, -- 'retry', 'error', 'warning', 'info'
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  
+  CONSTRAINT fk_upload_event FOREIGN KEY (upload_event_id) 
+    REFERENCES watch_uploads(id) ON DELETE CASCADE,
+  CONSTRAINT fk_session FOREIGN KEY (session_id) 
+    REFERENCES watch_sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_watch_events_upload_event_id ON watch_events(upload_event_id);
+CREATE INDEX idx_watch_events_session_id ON watch_events(session_id);
+CREATE INDEX idx_watch_events_timestamp ON watch_events(timestamp);
+CREATE INDEX idx_watch_events_type ON watch_events(type);
+```
+
+### Tabla watch_sessions
+```sql
+CREATE TABLE watch_sessions (
+  id VARCHAR(36) PRIMARY KEY,
+  start_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  end_time TIMESTAMP,
+  user_id VARCHAR(255),
+  status VARCHAR(20) DEFAULT 'active', -- 'active', 'completed', 'error'
+  total_uploads INTEGER DEFAULT 0,
+  total_retries INTEGER DEFAULT 0,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_watch_sessions_start_time ON watch_sessions(start_time);
+CREATE INDEX idx_watch_sessions_status ON watch_sessions(status);
+```
+
+---
+
+## 🔄 Uso en WatchCommand
+
+El siguiente paso será integrar estos métodos en `WatchCommand.js`:
+
+```javascript
+// En execute() method
+const sessionId = randomUUID();
+logger.initializeSession(sessionId);
+
+// En cada upload
+const uploadEventId = logger.recordUploadEvent({
+  strategy: uploadStrategy,
+  fileCount: files.length,
+  successCount: successCount,
+  failureCount: failureCount,
+  duration: endTime - startTime
+});
+
+// Guardar en BD
+await databaseService.insertUploadEvent(
+  { /* event data */ },
+  sessionId
+);
+
+// En reintentos
+logger.recordRetryEvent(uploadEventId, attemptNumber, error.message, backoffMs);
+await databaseService.insertRetryEvent(uploadEventId, sessionId, { /* retry data */ });
+
+// Al finalizar
+const stats = await databaseService.getSessionStatistics(sessionId);
+```
+
+---
+
+## ✅ Validación Completada
+
+✅ **Sintaxis**: Verificada con `node -c`  
+✅ **Métodos**: 6 nuevos métodos implementados  
+✅ **Error Handling**: Try-catch en todos los métodos  
+✅ **Retry Logic**: Usa `#queryWithRetry()` existente  
+✅ **Logging**: Logging en todos los puntos críticos  
+✅ **Integración**: Compatible con LoggingService  
+
+---
+
+## 📈 Impacto de Cambios
+
+```
+Líneas nuevas:           386
+Métodos nuevos:          6
+Propiedades nuevas:      0
+Funcionalidades:         Persistencia, Consultas, Estadísticas, Limpieza
+Compatibilidad:          ✅ Hacia atrás
+Breaking Changes:        ❌ Ninguno
+```
+
+---
+
+## 🚀 Próximos Pasos
+
+1. ✅ **DatabaseService mejorado** - COMPLETADO
+2. ⏳ **Integración en WatchCommand** - Siguiente
+3. ⏳ **Progress Bars** - Después
+4. ⏳ **Session Summary Report** - Final Fase 5
+
+---
+
+**Status**: DatabaseService completamente mejorado  
+**Última actualización**: 14 de Noviembre, 2025  
+**Validación**: ✅ Sintaxis correcta, 2078 líneas totales