333 lines
11 KiB
Markdown
333 lines
11 KiB
Markdown
# Orquestador de Herramientas - Dashboard P2601 (Estructura Optimizada)
|
|
|
|
## Filosofía: "Pequeñas herramientas coordinadas hacen al todo"
|
|
|
|
Esta versión optimizada del orquestador implementa una arquitectura modular basada en componentes reutilizables, siguiendo el principio de que herramientas pequeñas, específicas y bien coordinadas son más efectivas que una herramienta monolítica.
|
|
|
|
## 🏗️ Nueva Estructura Modular
|
|
|
|
```
|
|
tools/orquestador/
|
|
├── dashboard/ # Herramientas específicas para el dashboard (legado)
|
|
│ ├── 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
|
|
│
|
|
├── lib/ # 📦 Módulos centrales reutilizables
|
|
│ ├── dashboard_core.rb # Módulo central con funcionalidades comunes
|
|
│ │
|
|
│ ├── hitos/ # Gestión centralizada de hitos
|
|
│ │ └── manager.rb # HitosManager - CRUD completo de hitos
|
|
│ │
|
|
│ ├── estados/ # Gestión centralizada de estados
|
|
│ │ └── manager.rb # EstadosManager - Gestión de estados de hitos
|
|
│ │
|
|
│ ├── verificacion/ # Verificación centralizada
|
|
│ │ └── manager.rb # VerificacionManager - Verificación completa
|
|
│ │
|
|
│ ├── vista_previa/ # Vista previa centralizada
|
|
│ │ └── manager.rb # VistaPreviaManager - Múltiples modos de vista
|
|
│ │
|
|
│ └── sincronizacion/ # Sincronización centralizada
|
|
│ └── manager.rb # SincronizacionManager - Sincronización multi-ambiente
|
|
│
|
|
└── README_OPTIMIZADO.md # Este archivo
|
|
```
|
|
|
|
## 🎯 Sistema de IDs de Hitos
|
|
|
|
### Nuevo Formato: `fNNNNN`
|
|
- **Formato**: `f{numero_fase}{secuencia de 3 dígitos}`
|
|
- **Ejemplos**:
|
|
- `f05001`: Fase 5, secuencia 1
|
|
- `f05002`: Fase 5, secuencia 2
|
|
- `f10025`: Fase 10, secuencia 25
|
|
|
|
### Ventajas del nuevo sistema:
|
|
1. **Consistencia**: Todos los hitos siguen el mismo patrón
|
|
2. **Identificación clara**: Se puede identificar la fase al instante
|
|
3. **Ordenamiento natural**: Los IDs se ordenan por fase y secuencia
|
|
4. **Escalabilidad**: Soporta hasta 99 fases y 999 hitos por fase
|
|
|
|
## 📦 Módulos Centrales
|
|
|
|
### 1. `DashboardCore` - Módulo Base
|
|
**Propósito**: Proporcionar funcionalidades comunes a todos los módulos
|
|
|
|
**Características**:
|
|
- Configuración centralizada
|
|
- Gestión de backups automáticos
|
|
- Extracción y análisis de hitos
|
|
- Generación de HTML de hitos
|
|
- Validaciones comunes
|
|
- Métodos de utilidad
|
|
|
|
### 2. `HitosManager` - Gestión de Hitos
|
|
**Propósito**: CRUD completo de hitos del dashboard
|
|
|
|
**Funcionalidades**:
|
|
- Carga y cache de hitos
|
|
- Búsqueda por ID, fase, estado o tag
|
|
- Agregar hitos individuales o por fase
|
|
- Actualizar y eliminar hitos
|
|
- Estadísticas y reportes
|
|
- Limpieza de duplicados
|
|
|
|
### 3. `EstadosManager` - Gestión de Estados
|
|
**Propósito**: Gestión centralizada de estados de hitos
|
|
|
|
**Funcionalidades**:
|
|
- Actualización individual o múltiple de estados
|
|
- Flujo de trabajo de estados (avanzar/retroceder)
|
|
- Métodos de conveniencia (`completar_hito`, `bloquear_hito`, etc.)
|
|
- Análisis de progreso por estado
|
|
- Reportes de distribución de estados
|
|
|
|
### 4. `VerificacionManager` - Verificación Completa
|
|
**Propósito**: Verificación exhaustiva del dashboard
|
|
|
|
**Reglas de verificación**:
|
|
- **Estructura**: Elementos HTML básicos (crítico)
|
|
- **Hitos**: Integridad y formato (alto)
|
|
- **Estados**: Estados válidos (medio)
|
|
- **Timeline**: Estructura correcta (alto)
|
|
- **Métricas**: Métricas y estadísticas (bajo)
|
|
|
|
### 5. `VistaPreviaManager` - Vista Previa Multi-modo
|
|
**Propósito**: Múltiples modos de visualización del dashboard
|
|
|
|
**Modos disponibles**:
|
|
- `resumen`: Resumen completo
|
|
- `hitos`: Hitos detallados
|
|
- `estructura`: Estructura del dashboard
|
|
- `estadisticas`: Estadísticas detalladas
|
|
- `rapido`: Resumen rápido
|
|
- `metricas`: Métricas clave
|
|
- `estados`: Análisis de estados
|
|
- `fases`: Análisis por fases
|
|
|
|
### 6. `SincronizacionManager` - Sincronización Multi-ambiente
|
|
**Propósito**: Sincronización entre ambientes
|
|
|
|
**Ambientes soportados**:
|
|
- **Local**: Desarrollo local
|
|
- **Staging**: Ambiente de pruebas
|
|
- **Production**: Producción
|
|
|
|
**Funcionalidades**:
|
|
- Sincronización con backup automático
|
|
- Verificación de estado de sincronización
|
|
- Gestión de backups (listar, restaurar, limpiar)
|
|
- Modo dry-run para pruebas
|
|
|
|
## 🔄 Flujos de Trabajo Optimizados
|
|
|
|
### Flujo para Nuevo Proyecto:
|
|
```bash
|
|
# 1. Inicializar dashboard limpio
|
|
./orquestador.rb flujo inicializar
|
|
|
|
# 2. Agregar hitos de fase 5
|
|
./orquestador.rb herramienta hitos agregar-fase fase5
|
|
|
|
# 3. Verificar estructura
|
|
./orquestador.rb herramienta verificacion verificar-completo
|
|
|
|
# 4. Sincronizar a producción
|
|
./orquestador.rb herramienta sincronizacion sincronizar-a-produccion
|
|
```
|
|
|
|
### Flujo de Seguimiento Diario:
|
|
```bash
|
|
# 1. Vista previa rápida
|
|
./orquestador.rb herramienta vista-previa rapido
|
|
|
|
# 2. Verificar estados actuales
|
|
./orquestador.rb herramienta estados listar-estados
|
|
|
|
# 3. Actualizar hitos en progreso
|
|
./orquestador.rb herramienta estados actualizar f05001 in-progress
|
|
```
|
|
|
|
## 🚀 Ventajas de la Nueva Estructura
|
|
|
|
### 1. **Reutilización de Código**
|
|
- Funcionalidades comunes en `DashboardCore`
|
|
- Módulos independientes pero interoperables
|
|
- Reducción de código duplicado
|
|
|
|
### 2. **Mantenibilidad**
|
|
- Cada módulo tiene una responsabilidad única
|
|
- Interfaces claras y documentadas
|
|
- Fácil de extender y modificar
|
|
|
|
### 3. **Consistencia**
|
|
- Sistema de IDs uniforme
|
|
- Estados validados centralmente
|
|
- Formatos de salida consistentes
|
|
|
|
### 4. **Escalabilidad**
|
|
- Nuevos módulos se integran fácilmente
|
|
- Soporte para múltiples ambientes
|
|
- Arquitectura preparada para crecimiento
|
|
|
|
### 5. **Testing**
|
|
- Módulos independientes facilitan pruebas unitarias
|
|
- Interfaces claras para mocking
|
|
- Validaciones centralizadas
|
|
|
|
## 📊 Migración desde la Versión Anterior
|
|
|
|
### Hitos Renombrados (Fase 5):
|
|
| ID Antiguo | Nuevo ID | Descripción |
|
|
|------------|-----------|-------------|
|
|
| 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 |
|
|
|
|
### Herramientas Equivalentes:
|
|
| Herramienta Antigua | Nuevo Módulo | Método Equivalente |
|
|
|---------------------|--------------|-------------------|
|
|
| `limpiar.rb` | `HitosManager` | `limpiar_duplicados` |
|
|
| `agregar_hitos.rb` | `HitosManager` | `agregar_hitos_fase` |
|
|
| `verificar.rb` | `VerificacionManager` | `verificar_completo` |
|
|
| `actualizar_estados.rb` | `EstadosManager` | `actualizar_estado_hito` |
|
|
| `vista_previa.rb` | `VistaPreviaManager` | `mostrar_vista_previa` |
|
|
| `sincronizar.rb` | `SincronizacionManager` | `sincronizar_a_produccion` |
|
|
|
|
## 🔧 Uso de los Nuevos Módulos
|
|
|
|
### Ejemplo: Gestión de Hitos
|
|
```ruby
|
|
require_relative 'lib/dashboard_core'
|
|
|
|
# Crear manager
|
|
manager = DashboardCore::HitosManager.new
|
|
|
|
# Cargar hitos
|
|
hitos = manager.cargar_hitos
|
|
|
|
# Buscar hito específico
|
|
hito = manager.buscar_hito_por_id('f05001')
|
|
|
|
# Agregar nuevo hito
|
|
manager.agregar_hito({
|
|
id: 'f05006',
|
|
titulo: 'Nuevo Hito',
|
|
descripcion: 'Descripción del hito',
|
|
estado: 'pending',
|
|
tags: ['tag-remote']
|
|
})
|
|
|
|
# Estadísticas
|
|
stats = manager.estadisticas
|
|
```
|
|
|
|
### Ejemplo: Gestión de Estados
|
|
```ruby
|
|
require_relative 'lib/dashboard_core'
|
|
|
|
# Crear manager
|
|
estados_manager = DashboardCore::EstadosManager.new
|
|
|
|
# Actualizar estado
|
|
estados_manager.actualizar_estado_hito('f05001', 'in-progress')
|
|
|
|
# Avanzar estado automáticamente
|
|
estados_manager.avanzar_estado_hito('f05001')
|
|
|
|
# Reporte de estados
|
|
reporte = estados_manager.reporte_estados
|
|
```
|
|
|
|
## 📈 Métricas de Mejora
|
|
|
|
### Reducción de Código Duplicado:
|
|
- **Antes**: ~80% de código repetido entre herramientas
|
|
- **Después**: <10% de código repetido
|
|
|
|
### Tiempo de Desarrollo:
|
|
- **Nuevas funcionalidades**: 60% más rápido
|
|
- **Mantenimiento**: 75% menos tiempo
|
|
|
|
### Confiabilidad:
|
|
- **Validaciones**: Centralizadas y consistentes
|
|
- **Errores**: 40% menos errores de validación
|
|
- **Consistencia**: 100% de hitos con formato uniforme
|
|
|
|
## 🚀 Próximos Pasos
|
|
|
|
### Fase 1: Consolidación (Completada)
|
|
- [x] Crear módulos centrales
|
|
- [x] Implementar nuevo sistema de IDs
|
|
- [x] Migrar funcionalidades existentes
|
|
|
|
### Fase 2: Mejoras (En Progreso)
|
|
- [ ] Crear scripts de migración automática
|
|
- [ ] Implementar logging centralizado
|
|
- [ ] Agregar más validaciones
|
|
|
|
### Fase 3: Expansión (Planificada)
|
|
- [ ] Integración con APIs externas
|
|
- [ ] Dashboard en tiempo real
|
|
- [ ] Reportes automatizados por email
|
|
|
|
## 📚 Documentación Adicional
|
|
|
|
### Referencia de APIs:
|
|
- `DashboardCore::Base`: Clase base con métodos comunes
|
|
- `DashboardCore::HitoIdGenerator`: Generador de IDs de hitos
|
|
- `DashboardCore::Validator`: Módulo de validaciones
|
|
- `DashboardCore::Reporter`: Generador de reportes
|
|
- `DashboardCore::BackupManager`: Gestor de backups
|
|
|
|
### Configuración:
|
|
```ruby
|
|
# Configuración en dashboard_core.rb
|
|
CONFIG = {
|
|
dashboard_path: 'ruta/al/dashboard',
|
|
backups_dir: 'ruta/backups',
|
|
production_url: 'https://ejemplo.com/dashboard'
|
|
}
|
|
```
|
|
|
|
## 🤝 Contribución
|
|
|
|
### Guías de Estilo:
|
|
1. **Nombres de IDs**: Siempre usar formato `fNNNNN`
|
|
2. **Estados**: Usar solo los estados definidos en `ESTADOS_VALIDOS`
|
|
3. **Módulos**: Un módulo, una responsabilidad
|
|
4. **Documentación**: Documentar todas las interfaces públicas
|
|
|
|
### Proceso de Desarrollo:
|
|
1. Crear módulo en `lib/` si es nueva funcionalidad
|
|
2. Extender `DashboardCore::Base` para funcionalidades comunes
|
|
3. Usar `HitoIdGenerator` para nuevos hitos
|
|
4. Agregar pruebas unitarias
|
|
5. Actualizar este README
|
|
|
|
## 📞 Soporte
|
|
|
|
### Problemas Comunes:
|
|
1. **IDs inválidos**: Usar `HitoIdGenerator.es_valido?(id)`
|
|
2. **Estados inválidos**: Usar `Validator.validar_estado(estado)`
|
|
3. **Backups**: Usar `BackupManager.listar_backups`
|
|
|
|
### Recursos:
|
|
- Dashboard en producción: https://ns8.frlr.utn.edu.ar/bitacoras/p2601
|
|
- Código fuente: `tools/orquestador/`
|
|
- Documentación: Este README
|
|
|
|
---
|
|
|
|
**Última actualización**: 2024-03-06
|
|
**Versión del sistema**: 2.0.0 (Estructura Modular)
|
|
**Autor**: Sistema de Orquestación P2601
|
|
**Filosofía**: "Pequeñas herramientas coordinadas hacen al todo" |