@arela/uploader 1.0.23 → 1.1.0

package/docs/SCHEMA_ALIGNMENT_SUMMARY.md

@@ -0,0 +1,301 @@
+# Schema Alignment: arela-uploader ↔ arela-api
+
+## 📋 Resumen Ejecutivo
+
+Se han realizado cambios para alinear el schema de BD entre ambas aplicaciones, adoptando un **patrón dual-status** que respeta las responsabilidades de cada sistema:
+
+- **arela-uploader**: Gestiona `status` (ciclo de detección)
+- **arela-api**: Gestiona `processing_status` (ciclo de procesamiento/upload)
+
+---
+
+## 🔄 Cambios Realizados
+
+### 1. **Nueva Migración: `002_align_with_arela_api_schema.sql`**
+
+**Ubicación:** `/supabase/migrations/002_align_with_arela_api_schema.sql`
+
+**Cambios:**
+- ✅ Convierte `created_at` a `TIMESTAMP WITH TIME ZONE`
+- ✅ Agrega `updated_at` (reemplaza `modified_at` gradualmente)
+- ✅ Agrega `deleted_at` (soft delete, de BaseEntity)
+- ✅ Agrega columnas de audit: `created_by`, `updated_by`, `deleted_by`
+- ✅ Agrega `seq` (auto-increment de TypeORM)
+- ✅ Agrega columnas de queue:
+  - `processing_status` (default: 'PENDING')
+  - `upload_attempts` (default: 0)
+  - `depends_on_path`
+  - `pedimento_detected_at`
+  - `last_error`
+  - `file_order`
+- ✅ Crea 15 índices para optimizar queries
+- ✅ Elimina tablas no usadas:
+  - `error_tracking`
+  - `upload_logs`
+  - `performance_metrics`
+  - `watch_sessions`
+
+**Ejecución:**
+```bash
+# En arela-uploader:
+npm run migration:run
+```
+
+---
+
+### 2. **DatabaseService.js - Actualización de Inserts**
+
+**Cambios realizados:**
+
+#### En `insertStatsToUploaderTable()`:
+```javascript
+// ANTES:
+const record = {
+  status: 'stats',
+  created_at: new Date().toISOString(),
+  modified_at: stats.mtime.toISOString(),
+};
+
+// DESPUÉS:
+const record = {
+  status: 'stats',                        // ← Interno (arela-uploader)
+  processing_status: 'PENDING',           // ← NUEVO (para arela-api)
+  upload_attempts: 0,                     // ← NUEVO
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),   // ← NUEVO (junto con modified_at)
+  modified_at: stats.mtime.toISOString(),
+};
+```
+
+#### En `insertStatsOnlyToUploaderTable()`:
+```javascript
+// ANTES:
+const record = {
+  status: 'fs-stats',
+  created_at: new Date().toISOString(),
+  modified_at: stats.mtime.toISOString(),
+};
+
+// DESPUÉS:
+const record = {
+  status: 'fs-stats',                     // ← Interno (arela-uploader)
+  processing_status: 'PENDING',           // ← NUEVO (para arela-api)
+  upload_attempts: 0,                     // ← NUEVO
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),   // ← NUEVO
+  modified_at: stats.mtime.toISOString(),
+};
+```
+
+---
+
+### 3. **SmartWatchDatabaseService.js - Agregar updated_at**
+
+**En `markPedimentoDetected()`:**
+```javascript
+// ANTES:
+await supabase.from('uploader').update({
+  pedimento_detected_at: new Date().toISOString(),
+  processing_status: 'READY_TO_UPLOAD',
+})
+
+// DESPUÉS:
+await supabase.from('uploader').update({
+  pedimento_detected_at: new Date().toISOString(),
+  processing_status: 'READY_TO_UPLOAD',
+  updated_at: new Date().toISOString(),  // ← NUEVO
+})
+```
+
+---
+
+## 📊 Matriz de Responsabilidades - AHORA SINCRONIZADO
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    TABLA UPLOADER (Shared)                      │
+├─────────────────────────────────────────────────────────────────┤
+│ Columna            │ Controlado por    │ Valores/Default       │
+├────────────────────┼───────────────────┼──────────────────────┤
+│ id                 │ System (UUID)     │ uuid_generate_v4()   │
+│ seq                │ System (TypeORM)  │ SERIAL (auto-inc)    │
+│                    │                   │                      │
+│ filename           │ arela-uploader    │ basename of file     │
+│ original_path (PK) │ arela-uploader    │ full path (unique)   │
+│ file_extension     │ arela-uploader    │ .pdf, .xml, etc      │
+│ size               │ arela-uploader    │ bytes                │
+│                    │                   │                      │
+│ document_type      │ arela-uploader    │ pedimento, etc       │
+│ num_pedimento      │ arela-uploader    │ RFC number           │
+│ is_like_simplif    │ arela-uploader    │ boolean              │
+│ year               │ arela-uploader    │ 2025, 2024, etc      │
+│ arela_path         │ arela-uploader    │ /2025/RFC/file.pdf   │
+│ rfc                │ arela-uploader    │ RFC number           │
+│                    │                   │                      │
+│ status ⭐          │ arela-uploader    │ stats, detected,     │
+│                    │                   │ detection-error,     │
+│                    │                   │ unsupported, etc     │
+│                    │                   │                      │
+│ processing_status  │ arela-api         │ PENDING,             │
+│ ⭐ (NEW)           │                   │ READY_TO_UPLOAD,     │
+│                    │                   │ PROCESSING,          │
+│                    │                   │ UPLOADED, FAILED     │
+│                    │                   │ [DEFAULT: PENDING]   │
+│                    │                   │                      │
+│ upload_attempts    │ arela-api         │ 0, 1, 2, 3...        │
+│ (NEW)              │                   │ [DEFAULT: 0]         │
+│                    │                   │                      │
+│ last_error         │ arela-api         │ error message string │
+│ (NEW)              │                   │ [NULLABLE]           │
+│                    │                   │                      │
+│ depends_on_path    │ arela-uploader    │ /path/to/pedimento   │
+│ (NEW)              │                   │ [NULLABLE]           │
+│                    │                   │                      │
+│ pedimento_detecte  │ arela-uploader    │ timestamp when       │
+│ d_at (NEW)         │                   │ pedimento found      │
+│                    │                   │ [NULLABLE]           │
+│                    │                   │                      │
+│ file_order         │ arela-api         │ display/processing   │
+│ (NEW)              │                   │ order [NULLABLE]     │
+│                    │                   │                      │
+│ created_at         │ System (audit)    │ TIMESTAMP WITH TZ    │
+│ updated_at         │ System (audit)    │ TIMESTAMP WITH TZ    │
+│ (NEW)              │                   │                      │
+│ deleted_at         │ System (soft-del) │ TIMESTAMP WITH TZ    │
+│ (NEW)              │                   │ [NULLABLE]           │
+│                    │                   │                      │
+│ created_by         │ System (audit)    │ user_id string       │
+│ (NEW)              │                   │ [NULLABLE]           │
+│                    │                   │                      │
+│ updated_by         │ System (audit)    │ user_id string       │
+│ (NEW)              │                   │ [NULLABLE]           │
+│                    │                   │                      │
+│ deleted_by         │ System (audit)    │ user_id string       │
+│ (NEW)              │                   │ [NULLABLE]           │
+│                    │                   │                      │
+│ message            │ arela-uploader    │ error/status message │
+│ modified_at        │ arela-uploader    │ file mtime (legacy)  │
+│ metadata           │ Both (flexible)   │ JSON (flexible)      │
+└────────────────────┴───────────────────┴──────────────────────┘
+```
+
+---
+
+## 🔄 Flujo de Datos - Dual Status
+
+### Ejemplo 1: Archivo Normal
+```
+Archivo detectado por arela-uploader
+├─ status: 'detected'                (arela-uploader)
+└─ processing_status: 'PENDING'       (arela-api, default)
+
+Archivo procesado por arela-api
+├─ status: 'detected'                (sin cambios)
+└─ processing_status: 'READY_TO_UPLOAD'
+
+Archivo en carga
+├─ status: 'detected'
+├─ processing_status: 'PROCESSING'
+└─ upload_attempts: 1
+
+Carga exitosa
+├─ status: 'detected'
+├─ processing_status: 'UPLOADED'
+└─ uploaded_at: [timestamp]
+
+Carga fallida
+├─ status: 'detected'
+├─ processing_status: 'FAILED'
+├─ upload_attempts: 3
+└─ last_error: 'Network timeout'
+```
+
+### Ejemplo 2: Archivo sin Detección
+```
+Archivo pero sin pedimento válido
+├─ status: 'not-detected'            (arela-uploader)
+└─ processing_status: 'PENDING'       (arela-api)
+
+(Permanece en PENDING indefinidamente o se archiva)
+```
+
+---
+
+## 📈 Ventajas del Dual-Status Pattern
+
+1. **Separación de responsabilidades clara:**
+   - `status` = interno de detección (arela-uploader)
+   - `processing_status` = para queue/api (arela-api)
+
+2. **Sin conflictos:**
+   - Cada sistema actualiza su propia columna
+   - No hay race conditions
+   - Ambos leen sin problemas
+
+3. **Compatible con SmartWatchDatabaseService:**
+   - Ya estaba usando `processing_status`
+   - Ahora funciona con la BD correctamente
+
+4. **Completo para arela-api:**
+   - Puede calcular `/stats` desde `processing_status`
+   - Puede calcular `/health` desde `processing_status + upload_attempts`
+   - Puede calcular `/progress` desde conteos
+
+5. **Auditía y Debugging:**
+   - `updated_at` para saber cuándo cambió estado
+   - `created_by`, `updated_by` para quién lo cambió
+   - `last_error` para debugging de fallos
+   - `upload_attempts` para reintentos
+
+---
+
+## ✅ Checklist de Verificación
+
+### En arela-uploader:
+- [ ] Ejecutar: `npm run migration:run`
+- [ ] Verificar que `insertStatsToUploaderTable()` ahora incluye `processing_status`
+- [ ] Verificar que `insertStatsOnlyToUploaderTable()` ahora incluye `processing_status`
+- [ ] Verificar que `SmartWatchDatabaseService` usa `updated_at`
+- [ ] Tests pasan: `npm test`
+- [ ] Ejecutar un watch mode y verificar que inserta `processing_status: 'PENDING'`
+
+### En arela-api:
+- [ ] Con `synchronize: true`, TypeORM sincronizará automáticamente
+- [ ] Verificar que `Uploader.entity.ts` tenga todas columnas
+- [ ] Endpoints funcionan:
+  - [ ] `GET /stats` → cuenta `processing_status`
+  - [ ] `GET /health` → calcula desde `processing_status`
+  - [ ] `GET /progress` → calcula % desde UPLOADED/TOTAL
+  - [ ] `GET /failed` → filtra `processing_status='FAILED'`
+  - [ ] `POST /retry` → actualiza a `processing_status='PENDING'`
+
+### Integración:
+- [ ] Ambas BD leen/escriben correctamente
+- [ ] Sin conflictos en updates
+- [ ] Frontend recibe datos consistentes
+
+---
+
+## 🚀 Próximos Pasos
+
+### Fase 1 (Ahora - v1.0 Estable)
+- ✅ Dual-status implementado
+- ✅ Migración creada
+- ✅ DatabaseService actualizado
+- ✅ SmartWatchDatabaseService listo
+
+### Fase 2 (Futuro - Mejoras)
+- Gradualmente migrar `modified_at` → `updated_at` en arela-uploader
+- Implementar triggers en BD para audit automático
+- Agregar `file_order` para control de procesamiento
+- Soft deletes con `deleted_at` si se necesita
+
+---
+
+## 📝 Notas
+
+- `modified_at` se mantiene por compatibilidad hacia atrás con arela-uploader
+- `updated_at` coexiste y es el estándar de BaseEntity
+- TypeORM con `synchronize: true` en arela-api mantendrá sincronizadas las nuevas columnas
+- Todos los valores por defecto están sincronizados entre migración SQL y Entity de TypeORM
+

package/docs/SMARTWATCH_DATABASE_REFACTORING.md

@@ -0,0 +1,181 @@
+# SmartWatchDatabaseService - Refactoring Guide
+
+## 📋 Overview
+
+Se ha extraído la funcionalidad de Smart Watch Queue del `DatabaseService` (que tenía >2600 líneas) a un nuevo servicio especializado `SmartWatchDatabaseService` (~500 líneas).
+
+### Cambios realizados:
+
+**DatabaseService.js**
+- ✅ Reducido de 2664 a 2183 líneas (-481 líneas)
+- ✅ Agregados métodos públicos: `getSupabaseClient()` y `queryWithRetry()` para inyección de dependencias
+- ✅ Mantiene toda la funcionalidad existente intacta (sin breaking changes)
+
+**SmartWatchDatabaseService.js** (NUEVO)
+- ✅ 13 métodos especializados para manejo de cola inteligente
+- ✅ Usa DatabaseService como dependencia inyectada
+- ✅ Modular y reutilizable
+
+## 🔌 Cómo integrar en WatchService
+
+### Opción 1: Inyección en constructor (Recomendado)
+
+```javascript
+import { databaseService } from './DatabaseService.js';
+import SmartWatchDatabaseService from './SmartWatchDatabaseService.js';
+
+export class WatchService {
+  constructor() {
+    // ... otros inicializadores
+    this.smartWatchDb = new SmartWatchDatabaseService(databaseService);
+  }
+
+  async handleNewFile(filePath) {
+    const isPedimento = await this.#isPedimentoSimplificado(filePath);
+    const parentDir = path.dirname(filePath);
+
+    if (isPedimento) {
+      // Insertamos pedimento y actualizamos pendientes automáticamente
+      await this.smartWatchDb.markPedimentoDetected(parentDir, filePath);
+    } else {
+      // Insertamos archivo como PENDING
+      await this.smartWatchDb.insertFileToUploader(filePath, {
+        processingStatus: 'PENDING',
+        dependsOnPath: parentDir,
+        size: fs.statSync(filePath).size,
+        fileExtension: path.extname(filePath).slice(1)
+      });
+    }
+  }
+}
+```
+
+### Opción 2: Inyección estática en singleton
+
+```javascript
+// smartWatchDatabaseService.js
+import { databaseService } from './DatabaseService.js';
+import SmartWatchDatabaseService from './SmartWatchDatabaseService.js';
+
+export const smartWatchDatabaseService = new SmartWatchDatabaseService(databaseService);
+export default smartWatchDatabaseService;
+```
+
+Luego en WatchService:
+
+```javascript
+import smartWatchDatabaseService from './smartWatchDatabaseService.js';
+
+export class WatchService {
+  async handleNewFile(filePath) {
+    // ... usar smartWatchDatabaseService.insertFileToUploader()
+  }
+}
+```
+
+## 📚 Métodos Disponibles
+
+| Método | Descripción | Parámetros |
+|--------|-------------|-----------|
+| `insertFileToUploader()` | Inserta archivo con estado inicial | `filePath, options` |
+| `getPendingFilesInDirectory()` | Obtiene PENDING en directorio | `dirPath` |
+| `getFilesWithStatus()` | Obtiene archivos por status | `statuses[], limit` |
+| `updateFileStatus()` | Actualiza estado del archivo | `filePath, updates` |
+| `markPedimentoDetected()` | Marca pedimento (auto-update) | `dirPath, pedimentoPath` |
+| `getExpiredWaitingFiles()` | Obtiene archivos huérfanos | `maxWaitTimeSeconds` |
+| `getProcessingStats()` | Estadísticas por status | - |
+| `getFailedFilesForRetry()` | Archivos fallidos para reintentar | `maxAttempts` |
+| `retryFile()` | Reinicia un archivo fallido | `filePath` |
+| `retryFailedFiles()` | Reinicia múltiples archivos | `limit, maxAttempts` |
+| `getOverallProgress()` | Progreso con ETA | - |
+| `getFileDetails()` | Detalles de un archivo | `filePath` |
+| `searchFiles()` | Búsqueda avanzada | `filters` |
+
+## 🔄 Arquitectura
+
+```
+WatchService (monitorea archivos)
+    ↓
+SmartWatchDatabaseService (gestiona cola)
+    ↓
+DatabaseService (acceso a DB)
+    ↓
+Supabase
+```
+
+## 🧪 Ejemplo Completo
+
+```javascript
+import SmartWatchDatabaseService from './SmartWatchDatabaseService.js';
+import { databaseService } from './DatabaseService.js';
+
+class MyService {
+  constructor() {
+    this.smartWatchDb = new SmartWatchDatabaseService(databaseService);
+  }
+
+  async processNewFile(filePath) {
+    // 1. Insertar archivo
+    const file = await this.smartWatchDb.insertFileToUploader(filePath, {
+      processingStatus: 'PENDING',
+      dependsOnPath: path.dirname(filePath)
+    });
+    console.log(`📝 Archivo registrado: ${file.filename}`);
+
+    // 2. Monitorear progreso
+    const stats = await this.smartWatchDb.getProcessingStats();
+    console.log(`📊 Stats: ${stats.pending} pending, ${stats.readyToUpload} ready`);
+
+    // 3. Cuando se detecta pedimento
+    await this.smartWatchDb.markPedimentoDetected(
+      path.dirname(filePath),
+      pedimentoPath
+    );
+    // ↑ Automáticamente actualiza PENDING → READY_TO_UPLOAD
+
+    // 4. Procesar archivos listos
+    const ready = await this.smartWatchDb.getFilesWithStatus(['READY_TO_UPLOAD'], 10);
+    for (const file of ready) {
+      // Procesar...
+      await this.smartWatchDb.updateFileStatus(file.original_path, {
+        processing_status: 'UPLOADED'
+      });
+    }
+
+    // 5. Manejar reintentos
+    const result = await this.smartWatchDb.retryFailedFiles(5, 3);
+    console.log(`🔄 Retried: ${result.retried}, Skipped: ${result.skipped}`);
+
+    // 6. Obtener progreso global
+    const progress = await this.smartWatchDb.getOverallProgress();
+    console.log(`Progress: ${progress.percentComplete}% - ETA: ${progress.estimatedTimeRemaining}`);
+  }
+}
+```
+
+## ⚙️ Configuración de Retry
+
+Todos los métodos incluyen retry automático con exponential backoff:
+- **Máximo de reintentos**: 3 (configurable)
+- **Backoff inicial**: 1 segundo
+- **Backoff máximo**: 30 segundos
+- **Incremento**: Exponencial (2^n)
+
+Los errores retriables incluyen:
+- Timeouts
+- Errores de conexión
+- Errores de declaración cancelada
+
+## 🚀 Próximos Pasos
+
+1. Integrar `SmartWatchDatabaseService` en `WatchService`
+2. Usar métodos de cola en el flujo de detección de archivos
+3. Implementar UI de monitoreo usando `getProcessingStats()` y `getOverallProgress()`
+4. Crear endpoints REST en arela-api para acceso a estadísticas
+
+## 📝 Notas
+
+- Los métodos usan la instancia privada de Supabase del DatabaseService
+- No hay breaking changes en DatabaseService
+- Los métodos privados de DatabaseService (#queryWithRetry, #getSupabaseClient) ahora tienen wrappers públicos
+- Compatible con todas las versiones de Supabase JS client (v1.x y v2.x)