diff --git a/docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md b/docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md index 9919358b..9baa2faa 100644 --- a/docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md +++ b/docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md @@ -73,6 +73,167 @@ dron_orquestador \ --- +## πŸ“‘ Medio de ComunicaciΓ³n: BitΓ‘cora Web como Registro Central + +La **BitΓ‘cora Web** es el medio de comunicaciΓ³n donde los drones dejan registro de su actividad. El sistema sigue el principio **DB-First** con capas de visibilidad. + +### Arquitectura de Registros + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DRONES (Ejecutores, Vigilantes, Sanadores, etc.) β”‚ +β”‚ Cada dron deja registro al ejecutar β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ registra + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA 1: Tablas Internas (NO visibles directamente) β”‚ +β”‚ - bitacoras.dron_logs: Logs detallados de cada dron β”‚ +β”‚ - bitacoras.dron_avances: Progreso paso-a-paso β”‚ +β”‚ - bitacoras.dron_metricas: MΓ©tricas de rendimiento β”‚ +β”‚ - bitacoras.dron_errores: Errores y reintentos β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ dron_vigilante consolida + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CAPA 2: BitΓ‘cora Web (Resumen visible) β”‚ +β”‚ - events: Eventos consolidados por flujo/orquestaciΓ³n β”‚ +β”‚ - DescripciΓ³n: Resumen legible del progreso β”‚ +β”‚ - Estado: ⏳ En ejecuciΓ³n | βœ… Completado | ❌ Fallido β”‚ +β”‚ - URL: http://localhost:5174/bitacoras/ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Tablas Internas (Esquema `bitacoras`) + +```sql +-- Logs detallados de cada dron (NO visible en web directamente) +CREATE TABLE bitacoras.dron_logs ( + id SERIAL PRIMARY KEY, + dron_id VARCHAR(50) NOT NULL, -- ej: dron_083045_123 + flujo_id VARCHAR(50), -- ID de orquestaciΓ³n (si aplica) + tipo VARCHAR(20) NOT NULL, -- ejecutor|vigilante|sanador|planificador|mensajero + estado VARCHAR(20) NOT NULL, -- pending|running|completed|failed|zombie + cmd TEXT, -- Comando ejecutado + output TEXT, -- Salida del comando + exit_code INTEGER, -- CΓ³digo de retorno + started_at TIMESTAMP DEFAULT NOW(), + completed_at TIMESTAMP, + heartbeat TIMESTAMP DEFAULT NOW(), -- Último heartbeat + reintentos INTEGER DEFAULT 0, + metadata JSONB DEFAULT '{}'::jsonb -- Metadata adicional +); + +-- Avances paso-a-paso (para flujos multi-paso) +CREATE TABLE bitacoras.dron_avances ( + id SERIAL PRIMARY KEY, + dron_id VARCHAR(50) NOT NULL, + paso INTEGER NOT NULL, -- NΓΊmero de paso en flujo + descripcion TEXT NOT NULL, -- QuΓ© se estΓ‘ haciendo + estado VARCHAR(20) NOT NULL, -- pending|running|completed|failed + started_at TIMESTAMP DEFAULT NOW(), + completed_at TIMESTAMP, + metadata JSONB DEFAULT '{}'::jsonb +); + +-- MΓ©tricas de rendimiento (agregaciones) +CREATE TABLE bitacoras.dron_metricas ( + id SERIAL PRIMARY KEY, + fecha DATE NOT NULL, + dron_tipo VARCHAR(20) NOT NULL, + total_ejecuciones INTEGER DEFAULT 0, + completados INTEGER DEFAULT 0, + fallidos INTEGER DEFAULT 0, + zombies INTEGER DEFAULT 0, + tiempo_promedio INTERVAL, + reintentos_total INTEGER DEFAULT 0, + UNIQUE(fecha, dron_tipo) +); + +-- Índices para consultas eficientes +CREATE INDEX idx_dron_logs_estado ON bitacoras.dron_logs(estado); +CREATE INDEX idx_dron_logs_heartbeat ON bitacoras.dron_logs(heartbeat); +CREATE INDEX idx_dron_logs_flujo ON bitacoras.dron_logs(flujo_id); +CREATE INDEX idx_dron_avances_dron ON bitacoras.dron_avances(dron_id); +``` + +### Dron Vigilante: El Monitor de Flotas + +El **`dron_vigilante`** es responsable de: + +1. **Escanear flota**: Lee `bitacoras.dron_logs` para detectar drones activos +2. **Detectar zombies**: `heartbeat > 5min` β†’ marca como zombie +3. **Registrar avances**: Inserta en `bitacoras.dron_avances` el progreso +4. **Consolidar resumen**: Crea/actualiza evento en `bitacoras.events` (visible en web) +5. **Alertar anomalΓ­as**: Si detecta >5 fallos en 1h β†’ notifica + +```ruby +# Ejemplo: dron_vigilante escanea y registra avances +class DronVigilante + def escanear_flota + drones_activos = DronDB.where("estado = 'running' AND heartbeat < ?", 5.minutes.ago) + + drones_activos.each do |dron| + # Marcar como zombie + dron.update(estado: 'zombie') + + # Registrar en avances + DronAvance.create( + dron_id: dron.id, + paso: -1, + descripcion: "Dron detectado como zombie (heartbeat > 5min)", + estado: 'failed' + ) + + # Consolidar resumen en events (visible en BitΓ‘cora Web) + consolidar_resumen(dron.flujo_id) + end + end + + def consolidar_resumen(flujo_id) + # Obtener todos los logs del flujo + logs = DronLog.where(flujo_id: flujo_id) + + # Calcular estado consolidado + estado = if logs.all? { |l| l.estado == 'completed' } + 'completed' + elsif logs.any? { |l| l.estado == 'failed' } + 'failed' + else + 'running' + end + + # Actualizar/crear evento resumen (visible en BitΓ‘cora Web) + Evento.find_or_create_by(flujo_id: flujo_id).update( + descripcion: "Flujo #{flujo_id}: #{logs.count} drones - #{estado}", + estado: estado + ) + end +end +``` + +### BitΓ‘cora Web: Lo que el Usuario Ve + +La **BitΓ‘cora Web** (`http://localhost:5174/bitacoras/`) muestra: + +| Columna | Contenido | +|---------|-----------| +| **ID** | ID del evento resumen | +| **I** | Hora de inicio del flujo | +| **F** | Hora de fin (si completado) | +| **DescripciΓ³n** | Resumen consolidado (ej: "Backup nocturno: 4 drones completados") | +| **J** | Modo (P=Presencial, R=Remoto, A=AutomΓ‘tico) | +| **E** | Estado (⏳, βœ…, ❌) | +| **Acc.** | Acciones (ver detalle, reintentar) | + +**Al hacer clic en "ver detalle"**: +- Muestra tabla con drones individuales y su estado +- Muestra avances paso-a-paso del flujo +- Muestra mΓ©tricas de rendimiento (tiempo, reintentos) + +--- + ## πŸ“Š Estado Actual (LΓ­nea Base) ### Herramientas Existentes @@ -114,6 +275,22 @@ dron_orquestador \ ## πŸ—ΊοΈ Fases de ImplementaciΓ³n +### Fase 0: Infraestructura de Datos (Dron 0.5) β€” **PRIORITARIA** + +**Objetivo:** Crear tablas internas para registro detallado de drones. + +| ID | Tarea | DescripciΓ³n | Estado | +|:--:|-------|-------------|--------| +| F0.T1 | MigraciΓ³n `003_dron_logs.sql` | Tabla `bitacoras.dron_logs` | ⏳ | +| F0.T2 | MigraciΓ³n `004_dron_avances.sql` | Tabla `bitacoras.dron_avances` | ⏳ | +| F0.T3 | MigraciΓ³n `005_dron_metricas.sql` | Tabla `bitacoras.dron_metricas` | ⏳ | +| F0.T4 | `adn/tools/db/core/dron_db.rb` | Acceso a datos de drones | ⏳ | +| F0.T5 | Hooks DB-First | Auto-registro en dron_logs al lanzar | ⏳ | + +**Criterio de Γ©xito:** Drones pueden registrar actividad en tablas internas sin tocar events directamente. + +--- + ### Fase 1: Atomicidad β€” SeparaciΓ³n de Responsabilidades (Dron 1.0) **Objetivo:** Refactorizar el monolito `dron.rb` en mΓ³dulos atΓ³micos especializados. @@ -198,8 +375,8 @@ dron_orquestador \ | ID | Tarea | Tipo de Dron | Estado | |:--:|-------|--------------|--------| -| F5.T1 | `dron_db.rb` | Vigilante β€” almacena mΓ©tricas en PostgreSQL | ⏳ | -| F5.T2 | Tabla `dron_logs` | HistΓ³rico de ejecuciones | ⏳ | +| F5.T1 | API `/api/drones` | Endpoint para listar drones | ⏳ | +| F5.T2 | API `/api/drones/:id/avances` | Endpoint para avances de un dron | ⏳ | | F5.T3 | Dashboard web | `http://localhost:5174/drones` | ⏳ | | F5.T4 | GrΓ‘ficas | Tareas por dΓ­a, tasa de Γ©xito, tiempos | ⏳ | | F5.T5 | Alertas proactivas | `dron_vigilante` detecta anomalΓ­as | ⏳ | @@ -211,6 +388,7 @@ dron_orquestador \ ## πŸ“ˆ Progreso ``` +Fase 0: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% Infraestructura de Datos (tablas internas) Fase 1: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% Atomicidad β€” SeparaciΓ³n de Responsabilidades (Dron 1.0) Fase 2: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% ComposiciΓ³n β€” OrquestaciΓ³n de Flujos (Dron 1.5) Fase 3: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% PlanificaciΓ³n β€” Drones Programados (Dron 2.0) @@ -329,13 +507,16 @@ Fase 5: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% Observabilidad β€” Dashboard y MΓ© ### Persistencia -| Archivo | PropΓ³sito | -|---------|-----------| -| `/tmp/dron_flota/*.json` | Estado de drones activos (uno por archivo) | -| `/tmp/dron_queue/*.json` | Cola de eventos (por tipo) | -| `/tmp/dron_pheromones/` | SeΓ±ales quΓ­micas virtuales | -| `~/.claude/scheduled_tasks.json` | Schedules persistentes | -| `bitacoras.dron_logs` | HistΓ³rico en PostgreSQL | +| Archivo/Tabla | Tipo | PropΓ³sito | Visibilidad | +|---------|---------|-----------|-------------| +| `bitacoras.dron_logs` | Tabla DB | Logs detallados de cada dron | πŸ”’ Interna | +| `bitacoras.dron_avances` | Tabla DB | Progreso paso-a-paso de flujos | πŸ”’ Interna | +| `bitacoras.dron_metricas` | Tabla DB | Agregaciones y estadΓ­sticas | πŸ”’ Interna | +| `bitacoras.events` | Tabla DB | Eventos consolidados (resumen) | βœ… BitΓ‘cora Web | +| `/tmp/dron_flota/*.json` | Archivo | Estado de drones activos (runtime) | πŸ”’ CLI | +| `/tmp/dron_queue/*.json` | Archivo | Cola de eventos (por tipo) | πŸ”’ Drones | +| `/tmp/dron_pheromones/` | Directorio | SeΓ±ales quΓ­micas virtuales | πŸ”’ Drones | +| `~/.claude/scheduled_tasks.json` | Archivo | Schedules persistentes (cron) | πŸ”’ Planificador | ### Modificar