CloudRecoveryAS/PROJECT_STRUCTURE.md

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                         # Instalador de DESPLIEGUE Windows (binario autocontenido)
├── 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:

{
    "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