272 lines
10 KiB
Markdown
272 lines
10 KiB
Markdown
# 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
|