[ADN / Bitácora] Evolución Progresiva: Sistema de Iconografía Dual (Estado + Semántica)

2026-02-20 22:52:05 -03:00
parent ca715aee69
commit 2f4dcb62ea
18 changed files with 1666 additions and 15 deletions
@@ -0,0 +1,350 @@
+# Documentación del Proyecto dtic-BKPs
+
+## Resumen del Proyecto
+
+**Nombre del Proyecto:** dtic-BKPs
+**Versión:** v5.5.1
+**Autor:** Lic. Ricardo MONLA (rmonla@)
+**Organización:** Dirección de TIC, Facultad Regional La Rioja, Universidad Tecnológica Nacional  
+**Licencia:** MIT License  
+
+### Propósito y Descripción
+
+dtic-BKPs es un procesador automatizado de respaldos escrito en Ruby, diseñado para manejar el procesamiento, compresión y sincronización de respaldos de máquinas virtuales desde diversas plataformas de virtualización. El sistema proporciona un menú interactivo basado en terminal para gestionar operaciones de respaldo en entornos XenServer/XCP-ng y Proxmox VE.
+
+La aplicación automatiza el flujo de trabajo de descarga de respaldos desde servidores remotos, procesándolos (compresión, organización) y subiéndolos a almacenamiento en la nube u otros destinos utilizando rclone para sincronización universal de archivos.
+
+### Características Principales
+
+- **Interfaz de Terminal Interactiva:** Sistema basado en menús para ejecutar tareas de respaldo
+- **Soporte Multiplataforma:** Procesamiento nativo para XenServer/XCP-ng (archivos .xva) y respaldos de Proxmox VE
+- **Sincronización Universal:** Integración con rclone para sincronizar a cualquier destino local o remoto
+- **Arquitectura Modular:** Estructura de código organizada con procesadores separados para diferentes tipos de respaldo
+- **Tareas Configurables:** Definiciones de tareas editables a través de la interfaz de la aplicación
+- **Logging Integral:** Logging detallado con retroalimentación visual e indicadores de progreso
+- **Secuencias de Comandos:** Soporte para flujos de trabajo de respaldo de múltiples pasos
+
+## Estructura del Proyecto
+
+### Diseño de Directorios
+
+```
+dtic-BKPs/
+├── _vStable/                    # Directorio de versión estable
+│   ├── dtic-BKPs_app.rb         # Script principal de la aplicación
+│   ├── dtic-BKPs_tasks.rb       # Archivo de configuración de tareas
+│   ├── runDticBKPs.sh          # Script de ejecución
+│   ├── README.md               # Documentación del proyecto
+│   ├── LICENSE                 # Licencia MIT
+│   ├── logs/                   # Directorio de archivos de log
+│   │   └── dtic-BKPs.log        # Log principal de la aplicación
+│   ├── fxs/                    # Módulos de funciones
+│   │   ├── config_handler.rb   # Gestión de configuración
+│   │   ├── ui_handlers.rb      # Manejadores de interfaz de usuario
+│   │   ├── proc_syncPmox.rb    # Procesador de respaldos Proxmox
+│   │   ├── proc_syncXEN.rb     # Procesador de respaldos Xen
+│   │   └── sync_rclone.rb      # Sincronización rclone
+│   └── src/                    # Código fuente y documentación
+│       ├── install.sh          # Script de instalación
+│       ├── project__v5.5.0_*.md  # Documentación del proyecto
+│       └── core/               # Módulos principales
+│           └── globals.rb      # Constantes globales y utilidades
+├── _vStable/                   # Versiones estables anteriores
+└── _basurero/                  # Directorio de archivos
+```
+
+### Componentes Principales
+
+#### Aplicación Principal (`dtic-BKPs_app.rb`)
+- Punto de entrada del procesador de respaldos
+- Sistema de menú interactivo
+- Motor de ejecución de tareas
+- Carga y gestión de configuración
+
+#### Configuración de Tareas (`dtic-BKPs_tasks.rb`)
+- Define tareas individuales de respaldo
+- Contiene secuencias de comandos (flujos de trabajo de múltiples pasos)
+- Parámetros configurables para cada tipo de tarea
+
+#### Módulos de Funciones (`fxs/`)
+- **config_handler.rb:** Carga y guarda configuraciones de tareas
+- **ui_handlers.rb:** Gestiona interfaz de usuario e interacciones de menú
+- **proc_syncPmox.rb:** Procesa conjuntos de respaldos de Proxmox VE
+- **proc_syncXEN.rb:** Procesa archivos .xva de XenServer/XCP-ng
+- **sync_rclone.rb:** Maneja operaciones de sincronización rclone
+
+## Stack Tecnológico
+
+### Tecnologías Principales
+
+| Componente | Tecnología | Versión | Propósito |
+|------------|------------|---------|-----------|
+| **Lenguaje de Programación** | Ruby | 2.7+ | Lógica principal de la aplicación |
+| **Sincronización** | rclone | Última | Transferencia universal de archivos |
+| **Compresión** | tar/gzip | Sistema | Compresión de respaldos |
+| **Monitoreo de Progreso** | pv | Opcional | Visualización de progreso |
+| **Logging** | Ruby Logger | Integrado | Logging de la aplicación |
+
+### Dependencias
+
+#### Dependencias Requeridas
+- **Ruby 2.7+:** Entorno de ejecución principal
+- **rclone:** Herramienta universal de sincronización de archivos
+- **tar y gzip:** Utilidades de compresión (generalmente preinstaladas en Linux)
+
+#### Dependencias Opcionales
+- **pv (Pipe Viewer):** Proporciona barras de progreso durante operaciones de compresión
+
+#### Requisitos del Sistema
+- **Sistema Operativo:** Linux (Debian/Ubuntu recomendado)
+- **Permisos:** Acceso a directorios de origen y destino de respaldos
+- **Red:** Conectividad a orígenes remotos de respaldos (si aplica)
+- **Almacenamiento:** Espacio suficiente para procesamiento de respaldos y archivos temporales
+
+## Funcionalidades
+
+### Tipos de Procesamiento de Respaldos
+
+#### 1. Procesamiento XenServer/XCP-ng (`:xva`)
+- **Entrada:** Archivos de respaldo de máquinas virtuales .xva
+- **Proceso:** Comprime archivos .xva individuales en archivos .tar.gz
+- **Organización:** Agrupa respaldos por nombre de máquina virtual
+- **Salida:** Archivos comprimidos en estructura de directorios de destino
+
+#### 2. Procesamiento Proxmox VE (`:proxmox_log_notes`)
+- **Entrada:** Conjuntos de respaldos de Proxmox (archivos .log, .notes y datos)
+- **Proceso:** Lee archivo .notes para nombre de MV, comprime conjunto completo de respaldo
+- **Organización:** Crea archivos con timestamp por máquina virtual
+- **Salida:** Archivos .tar.gz consolidados con nomenclatura apropiada
+
+#### 3. Sincronización Universal (`:rclone_sync`)
+- **Entrada:** Cualquier directorio local o remoto
+- **Proceso:** Utiliza rclone para sincronizar archivos entre ubicaciones
+- **Destinos:** Rutas locales, almacenamiento en nube, servidores remotos
+- **Características:** Sincronización incremental, reporte de progreso, manejo de errores
+
+### Gestión de Tareas
+
+#### Tareas Individuales
+Cada tarea define:
+- **ID Único:** Identificador simbólico para la tarea
+- **Texto de Visualización:** Descripción amigable para el usuario
+- **Tipo de Proceso:** `:xva`, `:proxmox_log_notes`, o `:rclone_sync`
+- **Ruta de Origen:** Directorio origen (local o remoto rclone)
+- **Ruta de Destino:** Directorio destino (local o remoto rclone)
+- **Opciones:** Eliminar origen después del procesamiento, sobrescribir destino
+
+#### Secuencias de Comandos
+Flujos de trabajo de múltiples pasos que ejecutan múltiples tareas en orden:
+- **Descargar y Procesar:** Sincronizar desde remoto, luego procesar respaldos
+- **Ciclo Completo de Respaldo:** Descargar → Procesar → Subir a nube
+- **Operaciones Masivas:** Procesar múltiples orígenes de respaldos
+
+### Interfaz de Usuario
+
+#### Menú Principal
+- **Tareas Individuales:** Ejecutar operaciones de respaldo únicas
+- **Secuencias de Comandos:** Ejecutar flujos de trabajo de respaldo de múltiples pasos
+- **Editor de Tareas:** Modificar tareas existentes o crear nuevas
+- **Salir:** Cierre limpio de la aplicación
+
+#### Modo Editor de Tareas
+- **Editar Tareas:** Modificar parámetros de tareas existentes
+- **Crear Tareas:** Agregar nuevas operaciones de respaldo
+- **Eliminar Tareas:** Remover tareas no utilizadas
+- **Guardar Cambios:** Persistir modificaciones en archivo de configuración
+
+### Sistema de Configuración
+
+#### Archivo de Configuración de Tareas
+- **Formato:** Array Ruby de hashes de tareas
+- **Ubicación:** `dtic-BKPs_tasks.rb`
+- **Editable:** A través de interfaz de aplicación o manualmente
+- **Auto-generado:** Comentarios y formato preservados
+
+#### Configuración de Runtime
+- **Avance Automático:** Opción para proceder automáticamente a través de tareas
+- **Nivel de Logging:** Verbose configurable
+- **Salida en Color:** Retroalimentación visual con colores ANSI
+
+## Instalación y Configuración
+
+### Proceso de Instalación
+
+1. **Descarga:** Obtener todos los archivos del proyecto
+2. **Permisos:** Hacer ejecutable el script de instalación
+   ```bash
+   chmod +x install.sh
+   ```
+3. **Ejecutar Instalador:** Ejecutar el script de instalación
+   ```bash
+   ./install.sh
+   ```
+4. **Verificación de Dependencias:** El script verifica instalación de Ruby y rclone
+5. **Configuración:** Genera configuración inicial de tareas
+
+### Configuración de Tareas
+
+#### Ejemplos de Configuración de Tareas
+
+**Procesamiento de Respaldo Xen:**
+```ruby
+{
+  id: :proc_syncXen1,
+  menu_texto: "Procesar respaldos de MV Xen01",
+  tipo_proceso: :xva,
+  origen: "/mnt/respaldos/xen01/",
+  destino: "/mnt/procesados/xen01/",
+  eliminar_origen: true,
+  sobrescribir_destino: false,
+}
+```
+
+**Procesamiento de Respaldo Proxmox:**
+```ruby
+{
+  id: :proc_syncPmox,
+  menu_texto: "Procesar respaldos Proxmox",
+  tipo_proceso: :proxmox_log_notes,
+  origen: "servidor_pve:/var/lib/vz/dump/",
+  destino: "/mnt/procesados/proxmox/",
+  eliminar_origen: false,
+  sobrescribir_destino: false,
+}
+```
+
+**Subida a Nube:**
+```ruby
+{
+  id: :subir_nube,
+  menu_texto: "Subir a almacenamiento en nube",
+  tipo_proceso: :rclone_sync,
+  origen: "/mnt/procesados/",
+  destino: "proveedor_nube:/respaldos/",
+  eliminar_origen: false,
+  sobrescribir_destino: false,
+}
+```
+
+## Guía de Uso
+
+### Operación Básica
+
+1. **Iniciar Aplicación:**
+   ```bash
+   ./dtic-BKPs_app.rb
+   ```
+
+2. **Seleccionar Operación:**
+   - Ingresar número de tarea para ejecución individual
+   - Ingresar número de comando para ejecución de secuencia
+   - Presionar 'E' para modo de edición de tareas
+
+3. **Monitorear Progreso:**
+   - Indicadores visuales de progreso
+   - Actualizaciones de estado en tiempo real
+   - Logging detallado a archivo
+
+### Características Avanzadas
+
+#### Secuencias de Comandos
+Ejecutar flujos de trabajo complejos de respaldo:
+- **C1:** Descargar y procesar respaldos Proxmox
+- **C2:** Ciclo completo (descargar → procesar → subir)
+- **C3:** Sincronización masiva a nube
+
+#### Personalización de Tareas
+Modificar tareas a través del editor:
+- Cambiar rutas de origen/destino
+- Ajustar opciones de procesamiento
+- Agregar nuevos orígenes de respaldo
+- Crear secuencias de comandos personalizadas
+
+## Logging y Monitoreo
+
+### Archivos de Log
+- **Log Principal:** `logs/dtic-BKPs.log`
+- **Formato:** Timestamp, severidad, mensaje
+- **Rotación:** Rotación diaria con limpieza automática
+
+### Niveles de Log
+- **INFO:** Operaciones normales y completación
+- **WARN:** Problemas no críticos (archivos faltantes, etc.)
+- **ERROR:** Fallos críticos que requieren atención
+
+### Características de Monitoreo
+- **Estadísticas de Ejecución:** Seguimiento de tareas completadas y rendimiento
+- **Indicadores de Progreso:** Retroalimentación visual durante operaciones largas
+- **Reportes de Error:** Mensajes de error detallados con contexto
+- **Rastro de Auditoría:** Registro completo de todas las operaciones
+
+## Consideraciones de Seguridad
+
+### Control de Acceso
+- **Permisos de Archivos:** Acceso apropiado a directorios de respaldo
+- **Acceso Remoto:** Configuraciones remotas rclone seguras
+- **Gestión de Credenciales:** Almacenamiento seguro de credenciales de acceso
+
+### Protección de Datos
+- **Encriptación:** Usar almacenamiento remoto encriptado cuando sea posible
+- **Integridad de Respaldos:** Verificación de completitud de respaldos
+- **Logging de Acceso:** Rastro de auditoría de operaciones de respaldo
+
+## Mantenimiento y Solución de Problemas
+
+### Mantenimiento Regular
+- **Rotación de Logs:** Monitorear tamaños de archivos de log
+- **Respaldo de Configuración:** Preservar configuraciones de tareas
+- **Actualizaciones de Dependencias:** Mantener rclone y Ruby actualizados
+
+### Problemas Comunes
+- **Dependencias Faltantes:** Ejecutar script de instalación para verificar
+- **Errores de Permisos:** Verificar permisos de acceso a directorios
+- **Problemas de Red:** Verificar conectividad a orígenes remotos
+- **Errores de Configuración:** Validar definiciones de tareas
+
+### Optimización de Rendimiento
+- **Procesamiento Paralelo:** Considerar múltiples instancias para diferentes orígenes
+- **Planificación de Almacenamiento:** Asegurar espacio adecuado para procesamiento
+- **Ancho de Banda de Red:** Monitorear velocidades de transferencia para operaciones remotas
+
+## Desarrollo y Extensión
+
+### Arquitectura
+- **Diseño Modular:** Procesadores separados para diferentes tipos de respaldo
+- **Configuración Dirigida:** Definiciones de tareas en archivos externos
+- **Extensible:** Fácil adición de nuevos tipos de procesador
+
+### Agregar Nuevos Procesadores
+1. Crear nuevo módulo procesador en `fxs/`
+2. Agregar mapeo de procesador en aplicación principal
+3. Definir parámetros de configuración de tareas
+4. Actualizar documentación y ejemplos
+
+### Estándares de Código
+- **Estilo Ruby:** Seguir convenciones y mejores prácticas de Ruby
+- **Documentación:** Comentarios y documentación comprehensivos
+- **Manejo de Errores:** Manejo robusto de errores y logging
+- **Testing:** Testing manual de nuevas características
+
+## Soporte y Recursos
+
+### Documentación
+- **README.md:** Instalación y uso básico
+- **Archivos del Proyecto:** Documentación técnica detallada
+- **Ejemplos de Configuración:** Definiciones de tareas de ejemplo
+
+### Comunidad y Soporte
+- **Autor:** Lic. Ricardo MONLA (rmonla@)
+- **Organización:** Dirección de TIC, Universidad Tecnológica Nacional
+- **Licencia:** MIT License (código abierto)
+
+### Historial de Versiones
+- **v4.4:** Versión modular inicial con soporte Xen y Proxmox
+- **v5.2:** Sistema de configuración mejorado y editor de tareas
+- **v5.5.0:** Automatic execution via command-line parameters
+- **v5.5.1 (2025-11-14):** Fixed naming inconsistencies across the application to ensure correct app name references.
+
+---
+
+*Esta documentación proporciona una visión comprehensiva del procesador automatizado de respaldos dtic-BKPs. Para detalles específicos de implementación, referirse al código fuente y archivos de configuración.*