From 61f225496f3c695aa3016186ebb879ce4bd72dec Mon Sep 17 00:00:00 2001 From: Ricardo Monla Date: Tue, 7 Apr 2026 10:50:48 -0300 Subject: [PATCH] =?UTF-8?q?feat(A01.P009):=20Plan=20de=20evoluci=C3=B3n=20?= =?UTF-8?q?a=20AtomicDrones=20con=20inteligencia=20de=20colmena?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nuevo plan A01.P009 que define la arquitectura de drones como engranajes especializados que forman una maquinaria integral mediante composición. Filosofía de diseño: - AtomicDrones: Cada dron hace UNA cosa y la hace bien - Inteligencia de Colmena: Soluciones complejas emergen de drones simples - No FrankenDrones: Rechazar monolitos que intentan hacer todo mal Tipos de drones definidos: - 🛠️ Ejecutor: Ejecuta comando y reporta resultado - 👁️ Vigilante: Monitorea estado de otros drones - 🩹 Sanador: Repara drones zombies/fallidos - 📅 Planificador: Lanza drones según cron - 📨 Mensajero: Notifica resultados - 🎼 Orquestador: Compone múltiples drones en flujo Fases de implementación: - Fase 1: Atomicidad (separación de responsabilidades) - Fase 2: Composición (orquestación de flujos) - Fase 3: Planificación (drones programados) - Fase 4: Inteligencia de Colmena (comunicación por eventos) - Fase 5: Observabilidad (dashboard y métricas) Co-Authored-By: Claude Opus 4.6 --- .../dtic-ADN/A01.P009_Evolucion-Dron-ADN.md | 489 ++++++++++++++++++ docs/ambito/dtic-ADN/A01_dtic-ADN.md | 1 + 2 files changed, 490 insertions(+) create mode 100644 docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md diff --git a/docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md b/docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md new file mode 100644 index 00000000..9919358b --- /dev/null +++ b/docs/ambito/dtic-ADN/A01.P009_Evolucion-Dron-ADN.md @@ -0,0 +1,489 @@ +# A01.P009 - Evolución del Ecosistema ADN al Concepto de Dron + +> **Estado**: ⏳ En Planificación +> **Pertenece a**: [A01 - Ecosistema ADN](./A01_dtic-ADN.md) +> **Fecha**: 2026-04-07 +> **Responsable**: Lic. Ricardo MONLA +> **Versión**: 2.0 — Filosofía AtomicDrones + +--- + +## 📋 Resumen Ejecutivo + +Este plan define la evolución del ecosistema ADN hacia una arquitectura de **Inteligencia de Colmena** basada en **AtomicDrones** — drones atómicos especializados que, compuestos, forman una maquinaria autónoma integral. + +**Filosofía de Diseño:** + +| Principio | Descripción | +|-----------|-------------| +| **🧬 AtomicDrones** | Cada dron hace UNA cosa y la hace bien. Sin monolitos. | +| **🤖 Inteligencia de Colmena** | La solución emerge de la composición de drones simples. | +| **⚙️ Engranajes Especializados** | Drones ejecutores, vigilantes, sanadores, planificadores. | +| **🚫 No FrankenDrones** | Rechazar drones que intentan hacer todo mal. | + +**Concepto de Dron ADN:** +- **Atómico**: Una responsabilidad única (Single Responsibility) +- **Componible**: Se ensambla con otros drones para soluciones complejas +- **Auto-bitácora**: Registra inicio/fin automáticamente +- **Observable**: Estado visible vía `dron flota` y dashboard web +- **Efímero**: Nace, ejecuta, muere (sin estado persistente innecesario) + +--- + +## 🎯 Objetivo + +Evolucionar el ecosistema ADN hacia una **colonia de AtomicDrones** especializados que, compuestos, resuelven problemas complejos mediante inteligencia de colmena. + +**Meta:** Reducir la fricción operativa mediante drones atómicos que se especializan en una tarea única y se componen para flujos complejos. + +--- + +## 🐝 Tipos de AtomicDrones (Especialización) + +Cada tipo de dron tiene una única responsabilidad. La composición de múltiples drones resuelve problemas complejos. + +| Tipo | Símbolo | Responsabilidad | Ejemplo | +|------|---------|-----------------|---------| +| **Ejecutor** | `🛠️` | Ejecuta un comando y reporta resultado | `dron_ejecutor` | +| **Vigilante** | `👁️` | Monitorea estado de otros drones | `dron_vigilante` | +| **Sanador** | `🩹` | Repara drones zombies/fallidos | `dron_sanador` | +| **Planificador** | `📅` | Lanza drones según cron | `dron_planificador` | +| **Mensajero** | `📨` | Notifica resultados (Slack, email) | `dron_mensajero` | +| **Orquestador** | `🎼` | Compone múltiples drones en flujo | `dron_orquestador` | + +### Ejemplo de Composición (Inteligencia de Colmena) + +**Problema:** Backup nocturno de SQL + sync a nube + notificación + +**Solución FrankenDron (❌ rechazar):** +```ruby +# Un solo dron que hace todo (monolito frágil) +dron_backup_nocturno.rb # 500 líneas, 7 responsabilidades +``` + +**Solución AtomicDrones (✅ adoptar):** +```bash +# Orquestador compone 4 drones especializados +dron_orquestador \ + --step "dron_ejecutor --cmd 'vzdump 103'" \ + --step "dron_ejecutor --cmd 'rclone sync /bkps oneDrive:'" \ + --step "dron_vigilante --check exit_code" \ + --step "dron_mensajero --notify slack 'Backup OK'" +``` + +--- + +## 📊 Estado Actual (Línea Base) + +### Herramientas Existentes + +| Herramienta | Ubicación | Tipo | Estado | +|-------------|-----------|------|--------| +| `dron.rb` | `adn/tools/cli/dron.rb` | Orquestador básico | ✅ Operativo | +| `dron lanzar` | Subcomando CLI | Ejecutor | ✅ Funcional | +| `dron flota` | Dashboard | Vigilante | ✅ Implementado | +| `dron salud` | Health check | Sanador | ✅ Implementado | +| `dron limpiar` | Limpieza | Sanador | ✅ Implementado | + +### Capacidades Actuales + +```bash +# Ejecutor (lanzar tarea con auto-bitácora) +./adn/tools/run dron lanzar --evento AUTO --nota "Backup" -- + +# Vigilante (ver flota) +./adn/tools/run dron flota + +# Sanador (health check + limpiar) +./adn/tools/run dron salud +./adn/tools/run dron limpiar +``` + +### Limitaciones Detectadas (Deuda de Atomicidad) + +| # | Limitación | Tipo | Impacto | Prioridad | +|---|------------|------|---------|-----------| +| 1 | `dron.rb` es monolítico | FrankenDron | Difícil de extender | Alta | +| 2 | Sin persistencia entre sesiones | Ejecutor | Drones se pierden al reiniciar | Alta | +| 3 | Sin reintentos automáticos | Sanador | Tareas fallidas no se recuperan | Media | +| 4 | Sin planificación (cron) | Planificador | Requiere lanzamiento manual | Alta | +| 5 | Sin composición de drones | Orquestador | No hay flujos multi-paso | Media | +| 6 | Sin métricas históricas | Vigilante | No se puede analizar rendimiento | Baja | + +--- + +## 🗺️ Fases de Implementación + +### Fase 1: Atomicidad — Separación de Responsabilidades (Dron 1.0) + +**Objetivo:** Refactorizar el monolito `dron.rb` en módulos atómicos especializados. + +| ID | Tarea | Tipo de Dron | Estado | +|:--:|-------|--------------|--------| +| F1.T1 | `dron/ejecutor.rb` | Ejecutor — lanza y monitorea comando | ⏳ | +| F1.T2 | `dron/vigilante.rb` | Vigilante — escanea flota, detecta zombies | ⏳ | +| F1.T3 | `dron/sanador.rb` | Sanador — re-intenta, limpia, notifica fallos | ⏳ | +| F1.T4 | `dron/bitacora.rb` | Registrador — auto-bitácora (inicio/fin) | ⏳ | +| F1.T5 | `dron/dispatcher.rb` | Orquestador — dispatch de subcomandos | ⏳ | + +**Criterio de éxito:** Cada módulo tiene una única responsabilidad. Sin código duplicado. + +--- + +### Fase 2: Composición — Orquestación de Flujos (Dron 1.5) + +**Objetivo:** Permitir composición de drones para flujos multi-paso. + +| ID | Tarea | Descripción | Estado | +|:--:|-------|-------------|--------| +| F2.T1 | `dron/orquestador.rb` | Ejecuta pasos secuenciales (`--step`) | ⏳ | +| F2.T2 | Condicionales | `--on-error continue\|abort\|retry` | ⏳ | +| F2.T3 | Paralelismo | `--parallel` para pasos independientes | ⏳ | +| F2.T4 | Contexto compartido | Variables entre pasos (`$DRON_OUTPUT_N`) | ⏳ | + +**Ejemplo:** +```bash +./adn/tools/run dron orquestar \ + --step "dron_ejecutor --cmd 'vzdump 103'" \ + --step "dron_ejecutor --cmd 'rclone sync /bkps oneDrive:'" \ + --step "dron_mensajero --notify 'Backup OK'" \ + --on-error abort +``` + +**Criterio de éxito:** Flujos complejos se expresan como composición de drones simples. + +--- + +### Fase 3: Planificación — Drones Programados (Dron 2.0) + +**Objetivo:** Ejecución automática según cron. + +| ID | Tarea | Tipo de Dron | Estado | +|:--:|-------|--------------|--------| +| F3.T1 | `dron/planificador.rb` | Planificador — lee cron y lanza drones | ⏳ | +| F3.T2 | Persistencia de schedules | `~/.claude/scheduled_tasks.json` | ⏳ | +| F3.T3 | CLI schedules | `schedule add\|list\|remove` | ⏳ | +| F3.T4 | Integración CronCreate | SDK de Claude Code | ⏳ | + +**Criterio de éxito:** Tareas recurrentes se lanzan automáticamente. + +--- + +### Fase 4: Inteligencia de Colmena — Comunicación entre Drones (Dron 3.0) + +**Objetivo:** Drones se comunican y coordinan para resolver problemas. + +| ID | Tarea | Descripción | Estado | +|:--:|-------|-------------|--------| +| F4.T1 | Cola de eventos | Redis o archivo compartido para eventos | ⏳ | +| F4.T2 | Publicar/ Suscribirse | Drones publican eventos, otros reaccionan | ⏳ | +| F4.T3 | Patrones de reacción | `on failed → sanador`, `on completed → mensajero` | ⏳ | +| F4.T4 | Feromonas digitales | Señales químicas virtuales (`/tmp/dron_pheromones/`) | ⏳ | + +**Ejemplo de flujo emergente:** +``` +1. Ejecutor falla → publica "failed" en cola +2. Sanador escucha → re-intenta (máx 3 veces) +3. Si falla → publica "critical" +4. Mensajero escucha → notifica por Slack +``` + +**Criterio de éxito:** Soluciones complejas emergen sin orquestador central. + +--- + +### Fase 5: Observabilidad — Dashboard y Métricas (Dron 4.0) + +**Objetivo:** Visibilidad completa de la colonia. + +| 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.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 | ⏳ | + +**Criterio de éxito:** Visibilidad completa vía web dashboard y métricas históricas. + +--- + +## 📈 Progreso + +``` +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) +Fase 4: ░░░░░░░░░░ 0% Inteligencia de Colmena (Dron 3.0) +Fase 5: ░░░░░░░░░░ 0% Observabilidad — Dashboard y Métricas (Dron 4.0) +``` + +--- + +## 🏗️ Arquitectura de Colmena + +### Diagrama de Flujo (Inteligencia de Colmena) + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ PLANIFICADOR (dron_planificador) │ +│ - Lee ~/.claude/scheduled_tasks.json │ +│ - Publica evento "scheduled" en cola │ +└─────────────┬────────────────────────────────────────────────────┘ + │ publica + ▼ +┌──────────────────────────────────────────────────────────────────┐ +│ COLA DE EVENTOS (/tmp/dron_queue/) │ +│ - Archivos por evento: {tipo, payload, timestamp} │ +│ - Escuchado por suscriptores │ +└─────────────┬────────────────────────────────────────────────────┘ + │ + ┌─────────┼─────────┬─────────────────┐ + │ │ │ │ + ▼ ▼ ▼ ▼ +┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ +│EJECUTOR│ │VIGILANTE│ │SANADOR│ │MENSAJERO │ +│🛠️ │ │👁️ │ │🩹 │ │📨 │ +│Escucha │ │Escanea│ │Escucha │ │Escucha │ +│"run" │ │flota │ │"failed"│ │"notify" │ +└───┬────┘ └───┬────┘ └───┬────┘ └────┬─────┘ + │ │ │ │ + │ │ │ │ publica "alert" + │ │ │ ▼ + │ │ │ ┌─────────────┐ + │ │ │ │SLACK/EMAIL │ + │ │ │ └─────────────┘ + │ │ │ + │ │ └─→ Re-intenta (máx 3) + │ │ Backoff: 1m, 2m, 4m + │ │ + │ └─→ Detecta zombies (heartbeat > 5min) + │ Publica "zombie_detected" + │ + └─→ Ejecuta cmd + Registra en bitácora (AUTO) + Publica "completed" o "failed" +``` + +### Principios de Diseño + +| Principio | Aplicación | +|-----------|------------| +| **Single Responsibility** | Cada dron hace UNA cosa | +| **Composability** | Drones se ensamblan en flujos | +| **Event-Driven** | Comunicación vía cola de eventos | +| **Stateless** | Drones no guardan estado (efímeros) | +| **Observable** | Todo evento se registra en DB | + +--- + +## 🔧 Componentes por Tipo de Dron + +### Ejecutor (`adn/tools/cli/dron/ejecutor.rb`) + +| Componente | Propósito | +|------------|-----------| +| `Ejecutor#lanzar` | Ejecuta comando, captura output, exit_code | +| `Ejecutor#heartbeat` | Escribe heartbeat cada 30s | +| `Ejecutor#resultado` | Retorna `{cmd, output, exit_code, duration}` | + +### Vigilante (`adn/tools/cli/dron/vigilante.rb`) + +| Componente | Propósito | +|------------|-----------| +| `Vigilante#escanear` | Lee `/tmp/dron_flota/`, detecta zombies | +| `Vigilante#reportar` | Muestra dashboard (flota) | +| `Vigilante#alertar` | Detecta anomalías (ej: >5 fallos en 1h) | + +### Sanador (`adn/tools/cli/dron/sanador.rb`) + +| Componente | Propósito | +|------------|-----------| +| `Sanador#reintentar` | Re-lanza failed (máx 3, backoff) | +| `Sanador#limpiar` | Remueve completados >24h | +| `Sanador#notificar_fallo` | Alerta tras 3 fallos consecutivos | + +### Planificador (`adn/tools/cli/dron/planificador.rb`) + +| Componente | Propósito | +|------------|-----------| +| `Planificador#leer_cron` | Lee `~/.claude/scheduled_tasks.json` | +| `Planificador#encolar` | Publica evento en cola | +| `Planificador#listar` | Muestra schedules activos | + +### Orquestador (`adn/tools/cli/dron/orquestador.rb`) + +| Componente | Propósito | +|------------|-----------| +| `Orquestador#secuenciar` | Ejecuta pasos en orden | +| `Orquestador#paralelizar` | Ejecuta pasos en paralelo | +| `Orquestador#condicionar` | `on-error: continue\|abort\|retry` | + +### Registrador (`adn/tools/cli/dron/bitacora.rb`) + +| Componente | Propósito | +|------------|-----------| +| `Bitacora#iniciar` | Crea evento `⏳` con nota | +| `Bitacora#finalizar` | Actualiza evento con `--fin` | +| `Bitacora#fallar` | Marca evento como `❌` con error | + +### 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 | + +### Modificar + +| Archivo | Cambio | +|---------|--------| +| `adn/tools/cli/dron.rb` | Refactorizar → dispatcher que importa módulos | +| `adn/tools/run` | Registrar subcomandos: `dron lanzar`, `dron orquestar`, etc. | +| `adn/tools/db/core/bitacora_db.rb` | Hook para eventos AUTO (dron_bitacora) | + +--- + +## 📝 Comandos por Tipo de Dron + +### Ejecutor + +```bash +# Lanzar tarea simple (auto-bitácora) +./adn/tools/run dron lanzar --evento AUTO --nota "Backup SQL" -- vzdump 103 + +# Lanzar sin registro (efímero) +./adn/tools/run dron lanzar --no-bitacora --nota "Test rápido" -- echo hola + +# Lanzar con timeout +./adn/tools/run dron lanzar --timeout 300 --nota "Sync larga" -- rclone sync ... +``` + +### Orquestador (Composición) + +```bash +# Flujo secuencial (backup → sync → notificar) +./adn/tools/run dron orquestar \ + --step "dron lanzar --nota 'Backup' -- vzdump 103" \ + --step "dron lanzar --nota 'Sync' -- rclone sync /bkps oneDrive:" \ + --step "dron notificar --msg 'Backup completado'" \ + --on-error abort + +# Flujo paralelo (múltiples backups simultáneos) +./adn/tools/run dron orquestar \ + --parallel \ + --step "dron lanzar --nota 'Backup SQL' -- vzdump 103" \ + --step "dron lanzar --nota 'Backup DC' -- vzdump 100" \ + --step "dron lanzar --nota 'Backup PCV' -- vzdump 104" +``` + +### Planificador (Cron) + +```bash +# Agendar backup nocturno +./adn/tools/run dron schedule add \ + --cron "0 2 * * *" \ + --cmd "dron lanzar --evento AUTO --nota 'Backup nocturno' -- ./adn/tools/run bkps run C4 --batch" + +# Listar schedules +./adn/tools/run dron schedule list + +# Eliminar schedule +./adn/tools/run dron schedule remove +``` + +### Vigilante (Monitoreo) + +```bash +# Dashboard de flota +./adn/tools/run dron flota + +# Estado detallado de un dron +./adn/tools/run dron estado + +# Métricas históricas +./adn/tools/run dron metricas [--desde 2026-04-01] [--hasta 2026-04-07] +``` + +### Sanador (Reparación) + +```bash +# Health check (detecta zombies) +./adn/tools/run dron salud + +# Reintentar fallidos +./adn/tools/run dron sanear --reintentar + +# Limpiar completados +./adn/tools/run dron limpiar --mayor-a 24h +``` + +### Mensajero (Notificaciones) + +```bash +# Notificar por Slack +./adn/tools/run dron notificar --slack "#backups" "Backup completado ✅" + +# Notificar por email +./adn/tools/run dron notificar --email "admin@frlr.utn.edu.ar" "Alerta de fallo" +``` + +--- + +## 🎯 Criterios de Éxito + +### Atomicidad (Fase 1) +- ✅ Cada dron tiene una única responsabilidad (Single Responsibility) +- ✅ Sin código duplicado entre módulos +- ✅ Tests independientes por tipo de dron + +### Composición (Fase 2) +- ✅ Flujos multi-paso se expresan como composición de drones +- ✅ Orquestador permite secuencial/paralelo/condicional + +### Inteligencia de Colmena (Fase 4) +- ✅ Drones se comunican vía cola de eventos +- ✅ Patrones de reacción emergen (failed → sanador → notificar) +- ✅ Sin orquestador central para reacciones automáticas + +### Observabilidad (Fase 5) +- ✅ Dashboard web muestra estado en tiempo real +- ✅ Histórico consultable vía CLI y web +- ✅ Alertas proactivas ante anomalías + +--- + +## 📚 Referencias + +### Internas (ADN) +- **Herramienta actual**: [`adn/tools/cli/dron.rb`](../../../adn/tools/cli/dron.rb) +- **A01.P006**: [Sensor de Mejora Continua](./A01.P006_Sensor-de-Mejora-Continua.md) — Dron como evolución del sensor +- **A01 (dtic-ADN)**: [Manifiesto de Ámbito](./A01_dtic-ADN.md) — Marco de trabajo +- **adn/06_gobernanza.md**: [Principios Rectores](../../../adn/06_gobernanza.md) — Menos es Más + +### Externas (Inspiración) +- **Swarm Intelligence**: Comportamiento emergente en colonias de insectos +- **Unix Philosophy**: "Do one thing and do it well" +- **Microservices**: Servicios pequeños, composables, independientes +- **Event-Driven Architecture**: Comunicación asíncrona vía eventos +- **CronCreate**: SDK de Claude Code para schedules persistentes + +### DB-First +- Todas las métricas se almacenan en PostgreSQL (`bitacoras.dron_logs`) +- Dashboard web consume API → DB + +--- + +## 🔄 Armonía Integral + +**Última actualización**: 2026-04-07 (plan creado, filosofía AtomicDrones aplicada) + +| Documento | Estado | Notas | +|-----------|--------|-------| +| `A01_dtic-ADN.md` | 📍 Pendiente | Agregar A01.P009 a tabla de planes | +| `adn/07_proyectos.md` | 📍 Pendiente | Referenciar nuevo plan | +| `docs/contexto/IA.md` | 📍 Pendiente | Actualizar sección de drones | +| `adn/06_gobernanza.md` | ✅ Alineado | Principio "Menos es Más" — AtomicDrones | diff --git a/docs/ambito/dtic-ADN/A01_dtic-ADN.md b/docs/ambito/dtic-ADN/A01_dtic-ADN.md index e5c0a3f2..3d7fc4c4 100644 --- a/docs/ambito/dtic-ADN/A01_dtic-ADN.md +++ b/docs/ambito/dtic-ADN/A01_dtic-ADN.md @@ -121,6 +121,7 @@ Este ámbito cubre: | [A01.P006](A01.P006_Sensor-de-Mejora-Continua.md) | Sensor de Mejora Continua | ✅ Completado | | [A01.P007](A01.P007_Plantillas-Escritura-Eventos.md) | Plantillas de Escritura para Eventos | ✅ Completado | | [A01.P008](A01.P008_Modelo-Ambito-Nodo.md) | Modelo Ámbito/Nodo | ✅ Completado | +| [A01.P009](A01.P009_Evolucion-Dron-ADN.md) | Evolución a AtomicDrones (Colmena) | ⏳ En Planificación | ## 🛸 Sistema de Drones (Operación Autónoma)