rmonla/dtic-DIIAA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(A01.P009): Bitácora Web como medio de comunicación para drones

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Ricardo Monla
2026-04-07 10:52:56 -03:00
co-authored by Claude Opus 4.6
parent 61f225496f
commit b5e89144e3
1 changed files with 190 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md
+190 -9
View File
@@ -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) ## 📊 Estado Actual (Línea Base)
### Herramientas Existentes ### Herramientas Existentes
@@ -114,6 +275,22 @@ dron_orquestador \
## 🗺️ Fases de Implementación ## 🗺️ 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) ### Fase 1: Atomicidad — Separación de Responsabilidades (Dron 1.0)
**Objetivo:** Refactorizar el monolito `dron.rb` en módulos atómicos especializados. **Objetivo:** Refactorizar el monolito `dron.rb` en módulos atómicos especializados.
@@ -198,8 +375,8 @@ dron_orquestador \
| ID | Tarea | Tipo de Dron | Estado | | ID | Tarea | Tipo de Dron | Estado |
|:--:|-------|--------------|--------| |:--:|-------|--------------|--------|
| F5.T1 | `dron_db.rb` | Vigilante — almacena métricas en PostgreSQL | ⏳ | | F5.T1 | API `/api/drones` | Endpoint para listar drones | ⏳ |
| F5.T2 | Tabla `dron_logs` | Histórico de ejecuciones | ⏳ | | F5.T2 | API `/api/drones/:id/avances` | Endpoint para avances de un dron | ⏳ |
| F5.T3 | Dashboard web | `http://localhost:5174/drones` | ⏳ | | F5.T3 | Dashboard web | `http://localhost:5174/drones` | ⏳ |
| F5.T4 | Gráficas | Tareas por día, tasa de éxito, tiempos | ⏳ | | F5.T4 | Gráficas | Tareas por día, tasa de éxito, tiempos | ⏳ |
| F5.T5 | Alertas proactivas | `dron_vigilante` detecta anomalías | ⏳ | | F5.T5 | Alertas proactivas | `dron_vigilante` detecta anomalías | ⏳ |
@@ -211,6 +388,7 @@ dron_orquestador \
## 📈 Progreso ## 📈 Progreso
``` ```
Fase 0: ░░░░░░░░░░ 0% Infraestructura de Datos (tablas internas)
Fase 1: ░░░░░░░░░░ 0% Atomicidad — Separación de Responsabilidades (Dron 1.0) Fase 1: ░░░░░░░░░░ 0% Atomicidad — Separación de Responsabilidades (Dron 1.0)
Fase 2: ░░░░░░░░░░ 0% Composición — Orquestación de Flujos (Dron 1.5) Fase 2: ░░░░░░░░░░ 0% Composición — Orquestación de Flujos (Dron 1.5)
Fase 3: ░░░░░░░░░░ 0% Planificación — Drones Programados (Dron 2.0) Fase 3: ░░░░░░░░░░ 0% Planificación — Drones Programados (Dron 2.0)
@@ -329,13 +507,16 @@ Fase 5: ░░░░░░░░░░ 0% Observabilidad — Dashboard y Mé
### Persistencia ### Persistencia
| Archivo | Propósito | | Archivo/Tabla | Tipo | Propósito | Visibilidad |
|---------|-----------| |---------|---------|-----------|-------------|
| `/tmp/dron_flota/*.json` | Estado de drones activos (uno por archivo) | | `bitacoras.dron_logs` | Tabla DB | Logs detallados de cada dron | 🔒 Interna |
| `/tmp/dron_queue/*.json` | Cola de eventos (por tipo) | | `bitacoras.dron_avances` | Tabla DB | Progreso paso-a-paso de flujos | 🔒 Interna |
| `/tmp/dron_pheromones/` | Señales químicas virtuales | | `bitacoras.dron_metricas` | Tabla DB | Agregaciones y estadísticas | 🔒 Interna |
| `~/.claude/scheduled_tasks.json` | Schedules persistentes | | `bitacoras.events` | Tabla DB | Eventos consolidados (resumen) | ✅ Bitácora Web |
| `bitacoras.dron_logs` | Histórico en PostgreSQL | | `/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 ### Modificar