feat: Initial commit for OnEver Drive centralized backup system with Windows PyQt6 agent and Proxmox LXC deployment

2026-08-13 19:33:44 -03:00
commit 1bfb808c79
77 changed files with 10675 additions and 0 deletions
@@ -0,0 +1,84 @@
+# OnEver Drive — Manual del Agente Windows (PyQt6 & System Tray)
+
+## 1. Visión General
+El **Agente de Windows de OnEver Drive** es una aplicación de escritorio nativa moderna desarrollada en **PyQt6**, empaquetada como ejecutable `.exe` y diseñada para ejecutarse silenciosamente en el **Área de Notificaciones (System Tray)** de Windows con interfaz gráfica completa para:
+
+1. **Apuntar y conectar con el servidor central de backup** (URL del servidor + Código de registro con test de latencia).
+2. **Elegir carpetas de backup locales visualmente** mediante el explorador de Windows (`QFileDialog`), estableciendo filtros (`*.bak`, `*.mdf`), frecuencia y estabilidad de archivos.
+3. **Monitorear transferencias por bloques (chunks de 4 MB)** en tiempo real con barras de progreso, cálculo de hash SHA-256 y notificaciones nativas de Windows.
+
+---
+
+## 2. Interfaz Gráfica PyQt6
+
+```text
+ ┌────────────────────────────────────────────────────────────────────────┐
+ │ OnEver Drive — Agente de Backup Windows               ● Conectado      │
+ ├────────────────────────────────────────────────────────────────────────┤
+ │ [Dashboard]  [Carpetas de Backup]  [Servidor & Config]  [Historial]    │
+ ├────────────────────────────────────────────────────────────────────────┤
+ │                                                                        │
+ │  Transferencia en Vivo (Motor de Chunks)                               │
+ │  Subiendo database_production.bak...                                   │
+ │  [████████████████████████████░░░░░░░░] 68.4% (17 / 25 Chunks)         │
+ │  Chunks: 17/25 | Velocidad: 42.1 MB/s | SHA-256: e3b0c44298fc...       │
+ │                                                                        │
+ │  Información del Dispositivo                                           │
+ │  • Cliente ID: CLIENT-0001 (Servidor SQL Producción)                   │
+ │  • Servidor Proxmox: https://backup.midominio.com                      │
+ │  • Carpetas en Monitoreo: 3 carpetas locales                           │
+ │                                                                        │
+ │  [ ▶ Iniciar Sincronización Manual Ahora ]                             │
+ └────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Pestañas y Funcionalidades
+
+### 📁 Pestaña 1: Carpetas de Backup (Selector Visual)
+Permite gestionar las carpetas de Windows que el agente respaldará automáticamente:
+- **Añadir Carpeta...**: Abre el selector visual de Windows para elegir la carpeta deseada (ej. `C:\SQLBackups`, `D:\DatosEmpresa`).
+- **Configuración de la Carpeta**:
+  - **Filtros de Archivo**: `*.bak,*.mdf` (o `*.*`).
+  - **Frecuencia de Sondeo**: Intervalo en minutos (ej. cada 60 min).
+  - **Estabilidad de Archivo (Locks)**: Ventana de seguridad en segundos (ej. 60s) para garantizar que SQL Server finalizó el volcado antes de iniciar la transferencia por bloques.
+- **Respaldar / Eliminar**: Botones dedicados para iniciar un respaldo inmediato de la carpeta o eliminarla del monitoreo.
+
+### 🌐 Pestaña 2: Servidor & Configuración
+- **URL Servidor**: Ingrese la dirección del servidor Proxmox VE (ej. `http://192.168.1.100:8000` o `https://backup.midominio.com`).
+- **Probar Conexión**: Comprueba la conectividad de red con el backend y muestra la latencia en milisegundos.
+- **Código de Registro**: Ingrese el código de un solo uso generado en el Dashboard Web (`OED-XXXX-XXXX`).
+- **Registrar Dispositivo**: Vincula criptográficamente la máquina Windows generando un `Device ID` y token secreto único.
+- **Preferencias de Notificaciones (No Invasivas)**:
+  - `[x] Habilitar notificaciones en el Área de Notificaciones (System Tray)`
+  - `[x] Notificar únicamente cuando INICIA un proceso de respaldo`
+  - `[x] Notificar únicamente cuando FINALIZA con éxito (Confirmación SHA-256)`
+  - `[x] Notificar en caso de error o pérdida de conexión`
+  *(Las actualizaciones de progreso intermedias se visualizan de manera silenciosa en la barra de la interfaz sin emitir globos emergentes).*
+
+### 📊 Pestaña 3: Dashboard & Telemetría
+- Medidor en tiempo real del progreso de subida por bloques.
+- Notificaciones de confirmación de integridad SHA-256 tras cada ensamblado.
+
+### 📜 Pestaña 4: Historial de Archivos
+- Registro histórico de todos los archivos respaldados localmente con su tamaño, fecha y checksum SHA-256.
+
+---
+
+## 4. Ejecutables Disponibles
+
+Los ejecutables listos para su distribución se ubican en:
+- **Standalone Portable (Un solo archivo):**
+  [`windows-agent/dist/OnEverDriveAgent-Standalone.exe`](file:///c:/Workspaces/onever_drive/windows-agent/dist/OnEverDriveAgent-Standalone.exe)
+- **Carpeta de Distribución:**
+  [`windows-agent/dist/OnEverDriveAgent/OnEverDriveAgent.exe`](file:///c:/Workspaces/onever_drive/windows-agent/dist/OnEverDriveAgent/OnEverDriveAgent.exe)
+- **Lanzador rápido con doble clic:**
+  [`windows-agent/start_tray_agent.bat`](file:///c:/Workspaces/onever_drive/windows-agent/start_tray_agent.bat)
+
+---
+
+## 5. Comportamiento en la Bandeja del Sistema (System Tray)
+
+- Al cerrar la ventana principal (botón `X`), la aplicación se **minimiza al área de notificaciones** junto al reloj sin interrumpir las transferencias programadas.
+- Al hacer **doble clic** o clic derecho en el icono de OnEver Drive en el System Tray, se abre instantáneamente el panel de control.