Initial commit: CloudRestoreAS v1.0.0 - Aplicación completa de restauración automática SQL Server

2026-01-25 16:53:00 -07:00
commit 854ffa116f
43 changed files with 6357 additions and 0 deletions
--- a/PROJECT_STRUCTURE.md
+++ b/PROJECT_STRUCTURE.md
@@ -0,0 +1,271 @@
+# Estructura del Proyecto CloudRestoreAS
+
+```
+CloudRestoreAs/
+│
+├── app/                                # Código fuente de la aplicación
+│   ├── __init__.py                     # Inicialización del paquete
+│   ├── constants.py                    # Constantes globales y configuración por defecto
+│   │
+│   ├── db/                             # Capa de acceso a datos (SQLite)
+│   │   ├── __init__.py
+│   │   ├── database.py                 # Gestor de conexiones y esquema SQLite
+│   │   ├── job_repository.py           # Repositorio de jobs
+│   │   ├── job_step_repository.py      # Repositorio de pasos de jobs
+│   │   ├── node_repository.py          # Repositorio de nodos (mapeos)
+│   │   ├── event_repository.py         # Repositorio de eventos/logs
+│   │   └── config_repository.py        # Repositorio de configuración
+│   │
+│   ├── engine/                         # Motor de procesamiento
+│   │   ├── __init__.py
+│   │   ├── engine.py                   # Motor principal y coordinador
+│   │   ├── file_watcher.py             # Vigilancia de carpetas y detección de archivos
+│   │   └── restore_worker.py           # Worker para procesamiento de jobs
+│   │
+│   ├── extract/                        # Módulo de extracción
+│   │   ├── __init__.py
+│   │   └── seven_zip.py                # Integración con 7-Zip
+│   │
+│   ├── sql/                            # Módulo SQL Server
+│   │   ├── __init__.py
+│   │   └── sql_manager.py              # Gestor de conexiones y operaciones SQL Server
+│   │
+│   ├── ui/                             # Interfaz gráfica (PySide6)
+│   │   ├── __init__.py
+│   │   ├── main_window.py              # Ventana principal y system tray
+│   │   ├── dashboard_tab.py            # Tab de dashboard (estadísticas)
+│   │   ├── jobs_tab.py                 # Tab de gestión de jobs
+│   │   ├── nodes_tab.py                # Tab de gestión de nodos
+│   │   ├── config_tab.py               # Tab de configuración
+│   │   └── logs_tab.py                 # Tab de logs y eventos
+│   │
+│   └── utils/                          # Utilidades
+│       ├── __init__.py
+│       ├── logger.py                   # Configuración de logging rotativo
+│       └── crypto.py                   # Cifrado/descifrado de contraseñas (DPAPI)
+│
+├── data/                               # Datos de la aplicación
+│   └── app.db                          # Base de datos SQLite (generada en ejecución)
+│
+├── logs/                               # Archivos de log
+│   └── app.log                         # Log principal (con rotación automática)
+│
+├── runner.py                           # Punto de entrada principal
+├── requirements.txt                    # Dependencias Python
+│
+├── install.ps1                         # Script de instalación automática
+├── start.ps1                           # Script de inicio rápido (PowerShell)
+├── start.bat                           # Script de inicio rápido (Batch)
+├── build.ps1                           # Script para generar ejecutable con PyInstaller
+├── test_installation.py                # Script de verificación de instalación
+│
+├── README.md                           # Documentación completa
+├── QUICKSTART.md                       # Guía rápida de inicio
+├── ADVANCED.md                         # Configuración avanzada
+├── SCRIPTS.md                          # Ejemplos de scripts de automatización
+├── CHANGELOG.md                        # Historial de cambios
+├── LICENSE                             # Licencia MIT
+│
+├── .gitignore                          # Archivos ignorados por Git
+│
+└── (después del build)
+    ├── build/                          # Directorio temporal de PyInstaller
+    ├── dist/                           # Ejecutable generado
+    │   └── CloudRestoreAS.exe          # Aplicación ejecutable
+    └── CloudRestoreAS.spec             # Archivo de configuración de PyInstaller
+```
+
+## Descripción de Componentes
+
+### Módulo `db` (Base de Datos)
+Capa de abstracción para SQLite con repositorios para cada entidad:
+- **database.py**: Gestor de conexiones y definición de esquema
+- **job_repository.py**: CRUD para jobs (create, get, update, stats)
+- **job_step_repository.py**: Gestión de pasos de ejecución de jobs
+- **node_repository.py**: Mapeos nodo → base de datos
+- **event_repository.py**: Log de eventos del sistema
+- **config_repository.py**: Almacenamiento de configuración
+
+### Módulo `engine` (Motor)
+Lógica de procesamiento y coordinación:
+- **engine.py**: Motor principal, maneja workers y file watcher
+- **file_watcher.py**: Monitorea carpetas, detecta estabilidad de archivos
+- **restore_worker.py**: Ejecuta el pipeline completo de restauración por job
+
+### Módulo `extract` (Extracción)
+Integración con 7-Zip:
+- **seven_zip.py**: Wrapper para ejecutar 7z.exe, soporte multipart
+
+### Módulo `sql` (SQL Server)
+Operaciones con SQL Server:
+- **sql_manager.py**: Conexiones, RESTORE FILELISTONLY, RESTORE DATABASE
+
+### Módulo `ui` (Interfaz Gráfica)
+Interfaz de usuario con PySide6/Qt:
+- **main_window.py**: Ventana principal, menús, system tray
+- **dashboard_tab.py**: Vista de estadísticas en tiempo real
+- **jobs_tab.py**: Lista y detalles de jobs
+- **nodes_tab.py**: CRUD de mapeos de nodos
+- **config_tab.py**: Configuración completa de la aplicación
+- **logs_tab.py**: Visualización de eventos y logs
+
+### Módulo `utils` (Utilidades)
+Funciones auxiliares:
+- **logger.py**: Configuración de logging rotativo
+- **crypto.py**: Cifrado de contraseñas con DPAPI de Windows
+
+## Flujo de Datos
+
+```
+┌─────────────────┐
+│ Carpeta Entrada │ ← Usuario copia archivos ZIP aquí
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  File Watcher   │ ← Monitorea carpeta cada N segundos
+└────────┬────────┘
+         │ Detecta archivo estable
+         ▼
+┌─────────────────┐
+│  RestoreEngine  │ ← Crea job en DB, encola worker
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ RestoreWorker   │ ← Procesa job en thread separado
+└────────┬────────┘
+         │
+         ├─► 1. Node Mapping (DB lookup)
+         ├─► 2. Extract (7-Zip)
+         ├─► 3. Locate .bak
+         ├─► 4. SQL Connect
+         ├─► 5. FILELISTONLY
+         ├─► 6. RESTORE DATABASE
+         └─► 7. Cleanup (mover a Procesados)
+              │
+              ▼
+         ┌─────────────────────┐
+         │ Carpeta Procesados  │ ← ZIP movido aquí si éxito
+         └─────────────────────┘
+```
+
+## Base de Datos SQLite
+
+### Esquema de Tablas
+
+**jobs**
+- job_id (PK)
+- created_at, updated_at
+- source_path, source_name, source_hash
+- node_name, db_name
+- status, attempts, last_error
+- started_at, finished_at
+- total_ms, extract_ms, restore_ms, filelist_ms
+
+**job_steps**
+- id (PK)
+- job_id (FK)
+- step, started_at, finished_at
+- duration_ms, exit_code
+- stdout, stderr, error
+
+**nodes**
+- node_name (PK)
+- db_name, active
+- notes, updated_at
+
+**events**
+- id (PK)
+- created_at, level
+- job_id (FK, opcional)
+- message
+
+**config**
+- key (PK)
+- value (JSON)
+- updated_at
+
+## Dependencias Externas
+
+### Software Requerido
+1. **Python 3.11+**: Lenguaje de programación base
+2. **7-Zip**: Para extracción de archivos ZIP
+3. **ODBC Driver 17+**: Para conexión con SQL Server
+4. **SQL Server**: Servidor de bases de datos destino
+
+### Bibliotecas Python
+- **PySide6**: Framework Qt para interfaz gráfica
+- **pyodbc**: Driver ODBC para SQL Server
+- **pywin32**: APIs de Windows (DPAPI para cifrado)
+
+## Configuración en Tiempo de Ejecución
+
+La configuración se almacena en:
+1. **SQLite** (`data/app.db`, tabla `config`): Configuración principal
+2. **Memoria** (`RestoreEngine._config`): Cache en ejecución
+
+Formato de configuración:
+```python
+{
+    "paths": {...},
+    "sql": {...},
+    "concurrency": {...},
+    "stability": {...},
+    "timeouts": {...},
+    "retries": {...},
+    "features": {...}
+}
+```
+
+## Logging
+
+Sistema de logging en múltiples niveles:
+1. **Archivo** (`logs/app.log`): RotatingFileHandler (10MB × 10 archivos)
+2. **Consola**: StreamHandler (stdout)
+3. **Base de Datos** (`events`): Eventos importantes
+
+Niveles: DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+## Threading
+
+- **Thread Principal**: UI de Qt (debe mantenerse libre)
+- **QThreadPool**: Workers para extracción y restauración
+- **Thread Daemon**: File watcher
+- **Timer Qt**: Actualización de stats cada 5s
+
+## Empaquetado
+
+**PyInstaller** genera ejecutable único:
+```
+CloudRestoreAS.exe
+├─► Python runtime embebido
+├─► Todas las dependencias
+├─► Código de la aplicación
+└─► Assets (si los hay)
+```
+
+Tamaño aproximado: 80-120 MB (con PySide6 embebido)
+
+## Extensibilidad
+
+### Agregar Nuevo Tipo de Backup
+1. Extender `extract/` con nuevo extractor
+2. Modificar `restore_worker.py` para detectar tipo
+3. Agregar lógica de procesamiento específica
+
+### Agregar Nuevo Motor de Base de Datos
+1. Crear nuevo gestor en `sql/` (ej: `postgres_manager.py`)
+2. Modificar `restore_worker.py` para seleccionar gestor
+3. Actualizar UI de configuración
+
+### Agregar Notificaciones
+1. Crear módulo `notifications/` con proveedores (email, slack, etc.)
+2. Conectar a señales del motor (`job_completed`, `error_occurred`)
+3. Agregar configuración en UI
+
+---
+
+**Versión**: 1.0.0  
+**Última Actualización**: 2026-01-25  
+**Mantenido por**: Aduanasoft