From b5e89144e364c2522a7c2f49eb18be62f24f1769 Mon Sep 17 00:00:00 2001 From: Ricardo Monla Date: Tue, 7 Apr 2026 10:52:56 -0300 Subject: [PATCH] =?UTF-8?q?feat(A01.P009):=20Bit=C3=A1cora=20Web=20como=20?= =?UTF-8?q?medio=20de=20comunicaci=C3=B3n=20para=20drones?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Actualización del plan A01.P009 para definir la arquitectura de registros y comunicación de drones mediante la Bitácora Web. Arquitectura de registros: - CAPA 1 (Interna): Tablas dron_logs, dron_avances, dron_metricas - NO visibles directamente en la web - Almacenan detalle paso-a-paso de cada dron - Usadas por dron_vigilante para monitoreo - CAPA 2 (Visible): Bitácora Web (events consolidados) - Resumen legible de flujos/orquestaciones - Estado: ⏳ En ejecución | ✅ Completado | ❌ Fallido - URL: http://localhost:5174/bitacoras/ Dron Vigilante: - Escanea flota y detecta zombies (heartbeat > 5min) - Registra avances en bitacoras.dron_avances - Consolida resumen en bitacoras.events (visible en web) - Alerta anomalías (>5 fallos en 1h) Nueva Fase 0 (Prioritaria): - F0.T1-T3: Migraciones de tablas internas - F0.T4: dron_db.rb para acceso a datos - F0.T5: Hooks DB-First para auto-registro Co-Authored-By: Claude Opus 4.6 --- .../dtic-ADN/A01.P009_Evolucion-Dron-ADN.md | 199 +++++++++++++++++- 1 file changed, 190 insertions(+), 9 deletions(-) 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