# 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.*