# Orquestador de Herramientas - Dashboard P2601

## Filosofía: "Pequeñas herramientas coordinadas hacen al todo"

> **NOTA**: Esta versión ha sido optimizada con una estructura modular. 
> Ver [README_OPTIMIZADO.md](README_OPTIMIZADO.md) para la nueva arquitectura.

Este directorio contiene herramientas pequeñas, específicas y reutilizables para gestionar el dashboard del proyecto P2601. Cada herramienta tiene un propósito único y claro, siguiendo el principio de que herramientas pequeñas combinadas son más efectivas que una herramienta monolítica.

## 🚀 Nueva Estructura Modular (Optimizada)

Se ha implementado una nueva arquitectura modular que centraliza funcionalidades comunes y promueve la reutilización de código:

```
tools/orquestador/
├── dashboard/                    # Herramientas específicas (legado)
├── lib/                         # 📦 Módulos centrales reutilizables
│   ├── dashboard_core.rb        # Módulo central con funcionalidades comunes
│   ├── hitos/manager.rb         # Gestión centralizada de hitos
│   ├── estados/manager.rb       # Gestión centralizada de estados
│   ├── verificacion/manager.rb  # Verificación centralizada
│   ├── vista_previa/manager.rb  # Vista previa multi-modo
│   └── sincronizacion/manager.rb # Sincronización multi-ambiente
├── config.rb                    # Configuración centralizada
├── migrar_ids_hitos.rb          # Migración a nuevo sistema de IDs
├── ejemplo_modulos_optimizados.rb # Ejemplos de uso
└── README_OPTIMIZADO.md         # Documentación completa
```

### 🎯 Nuevo Sistema de IDs de Hitos
- **Formato**: `f{numero_fase}{secuencia de 3 dígitos}`
- **Ejemplos**: `f05001` (Fase 5, secuencia 1), `f05002` (Fase 5, secuencia 2)

### 🔄 Migración Recomendada
1. Verificar estado actual: `./migrar_ids_hitos.rb verificar`
2. Simular migración: `./migrar_ids_hitos.rb simular`
3. Realizar migración: `./migrar_ids_hitos.rb migrar`

### 📚 Documentación Completa
- [README_OPTIMIZADO.md](README_OPTIMIZADO.md) - Nueva arquitectura modular
- [config.rb](config.rb) - Configuración centralizada
- [ejemplo_modulos_optimizados.rb](ejemplo_modulos_optimizados.rb) - Ejemplos de uso

## Estructura (Versión Original)

```
tools/orquestador/
├── dashboard/                    # Herramientas específicas para el dashboard
│   ├── limpiar.rb               # Limpiar hitos duplicados
│   ├── agregar_hitos.rb         # Agregar hitos de forma controlada
│   ├── verificar.rb             # Verificar estructura y estado
│   ├── actualizar_estados.rb    # Actualizar estados de hitos
│   ├── vista_previa.rb          # Vista previa rápida del dashboard
│   ├── sincronizar.rb           # Sincronizar dashboard local con producción
│   ├── agregar_hitos_db.rb      # Agregar hitos a base de datos PostgreSQL
│   └── orquestador.rb           # Script maestro para orquestar todas las herramientas
└── README.md                    # Este archivo
```

## Herramientas Disponibles (Versión Original)

> **NOTA**: Estas herramientas están siendo migradas a la nueva estructura modular.
> Para funcionalidades optimizadas, usar los módulos en `lib/`.

### 1. `limpiar.rb` - Limpiador de Dashboard
**Propósito**: Eliminar hitos duplicados y corregir estructura del dashboard.
**Equivalente modular**: `DashboardCore::HitosManager#limpiar_duplicados`

**Uso**:
```bash
cd tools/orquestador/dashboard
./limpiar.rb
```

**Características**:
- Crea backup automático del dashboard
- Detecta y elimina hitos duplicados
- Reconstruye estructura correcta de timeline
- Muestra estadísticas de limpieza

### 2. `agregar_hitos.rb` - Gestor de Hitos
**Propósito**: Agregar hitos al dashboard de forma controlada y estructurada.
**Equivalente modular**: `DashboardCore::HitosManager#agregar_hitos_fase`

**Uso**:
```bash
# Agregar hitos de fase 5 (modo predeterminado)
./agregar_hitos.rb agregar fase5 append

# Listar hitos disponibles
./agregar_hitos.rb listar fase5

# Mostrar ayuda
./agregar_hitos.rb help
```

**Modos de operación**:
- `append`: Agregar hitos al final de la timeline
- `replace`: Reemplazar hitos existentes de una fase
- `insert`: Insertar después de un marcador específico

**Hitos predefinidos (fase5)**:
- `BKP02`: Backup Automático de VMs en Proxmox
- `DB02`: Backup Automático de Base de Datos sysdasuten
- `MON01`: Monitoreo de Recursos del Hipervisor
- `DOC01`: Documentación Operativa del Sistema
- `PERF01`: Pruebas de Rendimiento del Sistema

### 3. `verificar.rb` - Verificador de Dashboard
**Propósito**: Verificar estructura y analizar estado del dashboard.
**Equivalente modular**: `DashboardCore::VerificacionManager#verificar_completo`

**Uso**:
```bash
# Verificar estructura básica
./verificar.rb verificar

# Analizar hitos en detalle
./verificar.rb analizar

# Mostrar ayuda
./verificar.rb help
```

**Verificaciones realizadas**:
- Estructura HTML básica
- Presencia de elementos requeridos
- Integridad de hitos (sin duplicados)
- Estado de la timeline
- Métricas y estadísticas

### 4. `actualizar_estados.rb` - Gestor de Estados de Hitos
**Propósito**: Actualizar el estado de hitos en el dashboard.
**Equivalente modular**: `DashboardCore::EstadosManager#actualizar_estado_hito`

**Uso**:
```bash
# Listar hitos con sus estados
./actualizar_estados.rb listar

# Actualizar estado de un hito
./actualizar_estados.rb actualizar BKP02 in-progress

# Actualizar múltiples hitos
./actualizar_estados.rb multiples BKP02 in-progress DB02 completed

# Mostrar estados disponibles
./actualizar_estados.rb estados
```

**Estados disponibles**:
- `pending`: Pendiente (amarillo)
- `in-progress`: En Progreso (azul)
- `completed`: Completado (verde)
- `blocked`: Bloqueado (rojo)
- `on-hold`: En Espera (púrpura)

### 5. `vista_previa.rb` - Vista Previa Rápida
**Propósito**: Obtener vista previa rápida del dashboard.
**Equivalente modular**: `DashboardCore::VistaPreviaManager#mostrar_vista_previa`

**Uso**:
```bash
# Resumen completo
./vista_previa.rb resumen

# Hitos detallados
./vista_previa.rb hitos

# Estructura del dashboard
./vista_previa.rb estructura

# Estadísticas detalladas
./vista_previa.rb estadisticas

# Resumen rápido
./vista_previa.rb rapido
```

**Características**:
- Múltiples modos de visualización
- Análisis de estructura HTML
- Estadísticas de hitos y estados
- Métricas clave del proyecto

### 6. `orquestador.rb` - Script Maestro de Orquestación
**Propósito**: Orquestar todas las herramientas en flujos de trabajo predefinidos.

### 7. `sincronizar.rb` - Sincronizador de Dashboard
**Propósito**: Sincronizar dashboard local con producción.
**Equivalente modular**: `DashboardCore::SincronizacionManager#sincronizar_a_produccion`

### 8. `agregar_hitos_db.rb` - Gestor de Hitos en Base de Datos
**Propósito**: Agregar hitos a la base de datos PostgreSQL.

**Uso**:
```bash
# Ejecutar una herramienta específica
./orquestador.rb herramienta limpiar

# Ejecutar flujo de trabajo predefinido
./orquestador.rb flujo seguimiento-diario

# Listar herramientas disponibles
./orquestador.rb listar-herramientas

# Listar flujos de trabajo
./orquestador.rb listar-flujos

# Mostrar estado del sistema
./orquestador.rb estado
```

**Flujos de trabajo predefinidos**:
- `inicializar`: Inicializar dashboard limpio con hitos de fase 5
- `seguimiento-diario`: Flujo para seguimiento diario del proyecto
- `revision-semanal`: Flujo para revisión semanal completa
- `agregar-fase5`: Agregar hitos de fase 5 y verificar

## Flujo de Trabajo Recomendado

### Para nuevo proyecto o limpieza completa:
1. **Verificar estado actual**:
   ```bash
   ./orquestador.rb flujo revision-semanal
   ```

2. **Inicializar dashboard limpio**:
   ```bash
   ./orquestador.rb flujo inicializar
   ```

### Para seguimiento diario:
```bash
./orquestador.rb flujo seguimiento-diario
```

### Para agregar hitos de fase 5:
```bash
./orquestador.rb flujo agregar-fase5
```

## Principios de Diseño

1. **Una herramienta, un propósito**: Cada herramienta hace una cosa y la hace bien.
2. **Composición sobre monolitos**: Las herramientas se pueden combinar para flujos complejos.
3. **Backup automático**: Todas las herramientas crean backups antes de modificar.
4. **Feedback claro**: Proporcionan información detallada sobre lo que hacen.
5. **Interfaz simple**: Uso intuitivo desde línea de comandos.
6. **Reutilización**: Código modular que se puede integrar en otros sistemas.

## Integración con Herramientas ADN

Estas herramientas están diseñadas para complementar (no reemplazar) las herramientas existentes en `tools/adn`. Se pueden usar conjuntamente:

1. **Herramientas ADN**: Para automatización compleja y gestión de eventos
2. **Herramientas Orquestador**: Para tareas específicas de dashboard y estructura

## 🚀 Migración a la Nueva Estructura

### Ventajas de la Nueva Arquitectura:
1. **Reutilización de código**: Funcionalidades comunes centralizadas
2. **Consistencia**: Sistema de IDs uniforme (`fNNNNN`)
3. **Mantenibilidad**: Módulos independientes con responsabilidades únicas
4. **Escalabilidad**: Fácil adición de nuevas funcionalidades

### Pasos de Migración:
```bash
# 1. Verificar estado actual de IDs
./migrar_ids_hitos.rb verificar

# 2. Simular migración (modo dry-run)
./migrar_ids_hitos.rb simular

# 3. Realizar migración completa
./migrar_ids_hitos.rb migrar

# 4. Probar nuevos módulos
./ejemplo_modulos_optimizados.rb
```

### Mapeo de IDs (Fase 5):
- `BKP02` → `f05001` (Backup Automático de VMs)
- `DB02` → `f05002` (Backup Automático de Base de Datos)
- `MON01` → `f05003` (Monitoreo de Recursos)
- `DOC01` → `f05004` (Documentación Operativa)
- `PERF01` → `f05005` (Pruebas de Rendimiento)

## Características Técnicas

### Backups Automáticos
- Todas las herramientas crean backups antes de modificar
- Backups organizados por fecha/hora en `dashboard/backups/`
- Formato: `dashboard_[tipo]_YYYYMMDD_HHMMSS.html`

### Manejo de Errores
- Validación de parámetros de entrada
- Mensajes de error descriptivos
- Códigos de salida significativos
- Opción `DEBUG=true` para detalles técnicos

### Compatibilidad
- Ruby estándar (sin dependencias externas)
- Compatible con cualquier sistema Unix/Linux
- Encoding UTF-8

## Ejemplos de Uso Avanzado

### Actualizar estados basados en progreso real:
```bash
# Marcar hitos en progreso
./actualizar_estados.rb actualizar BKP02 in-progress

# Marcar hitos completados con fecha específica
./actualizar_estados.rb actualizar DB02 completed 2024-03-05

# Actualizar múltiples hitos
./actualizar_estados.rb multiples \
  MON01 in-progress \
  DOC01 pending \
  PERF01 on-hold
```

### Análisis detallado del dashboard:
```bash
# Ver estructura completa
./vista_previa.rb estructura

# Analizar estadísticas
./vista_previa.rb estadisticas

# Verificar integridad
./verificar.rb verificar
```

## Mantenimiento

### Backups
- Se guardan automáticamente en `dashboard/backups/`
- Se recomienda limpiar backups antiguos periódicamente
- Formato: `dashboard_[tipo]_YYYYMMDD_HHMMSS.html`

### Logs y Depuración
```bash
# Activar modo debug
DEBUG=true ./verificar.rb verificar

# Verificar sintaxis de herramientas
ruby -c limpiar.rb
```

### Actualizaciones
- Mantener la filosofía de herramientas pequeñas y específicas
- Documentar cambios en este README
- Probar flujos de trabajo después de modificaciones

## Próximos Pasos

### ✅ Completado (Nueva Estructura):
1. **Crear módulos centrales** reutilizables en `lib/`
2. **Implementar nuevo sistema de IDs** (`fNNNNN`)
3. **Documentar arquitectura modular** en `README_OPTIMIZADO.md`
4. **Crear scripts de migración** y ejemplos de uso

### 🔄 En Progreso:
1. **Migrar herramientas existentes** a la nueva arquitectura
2. **Crear tests automatizados** para cada módulo
3. **Implementar logging centralizado**

### 📋 Planificado:
1. **Integración con APIs externas**
2. **Dashboard en tiempo real**
3. **Reportes automatizados por email**

## 📚 Documentación Adicional

### Nueva Arquitectura:
- [README_OPTIMIZADO.md](README_OPTIMIZADO.md) - Documentación completa de la nueva estructura
- [config.rb](config.rb) - Configuración centralizada
- [ejemplo_modulos_optimizados.rb](ejemplo_modulos_optimizados.rb) - Ejemplos de uso práctico

### Herramientas de Migración:
- [migrar_ids_hitos.rb](migrar_ids_hitos.rb) - Migración de IDs al nuevo formato
- Script interactivo con modos: `verificar`, `simular`, `migrar`

### Módulos Principales:
- `DashboardCore::HitosManager` - Gestión completa de hitos
- `DashboardCore::EstadosManager` - Gestión de estados
- `DashboardCore::VerificacionManager` - Verificación exhaustiva
- `DashboardCore::VistaPreviaManager` - Vista previa multi-modo
- `DashboardCore::SincronizacionManager` - Sincronización multi-ambiente

## Contacto

Para problemas o sugerencias:
- Revisar la bitácora del proyecto P2601
- Verificar backups en `dashboard/backups/`
- Usar modo debug para detalles técnicos: `DEBUG=true`

## Dashboard en Producción

🔗 **URL**: https://ns8.frlr.utn.edu.ar/bitacoras/p2601

**Recomendaciones**:
- Verificar cambios en producción después de cada modificación
- Usar flujo `seguimiento-diario` para monitoreo regular
- Mantener backups organizados por fecha

---

*Última actualización: 2024-03-06*  
*Versión del sistema: 2.0.0 (Estructura Modular)*  
*Documentación optimizada: [README_OPTIMIZADO.md](README_OPTIMIZADO.md)*  
*Autor: Sistema de Orquestación P2601*  
*Filosofía: "Pequeñas herramientas coordinadas hacen al todo"*