Feat(ADN): Completadas tareas 2.2, 2.4 y 2.5 del manifiesto (Cierre de Fase 1)

docs/plan/adn/260308-1200_Plan_Integral_ADN_BITACORAs.md

@@ -0,0 +1,323 @@
+# Plan Integral: Integración ADN con dtic-BITACORAs (Base de Datos)
+
+**Fecha:** 8 de marzo de 2026  
+**Autor:** Sistema ADN  
+**Versión:** 1.0  
+**Ubicación:** `docs/plan/260308-1200_Plan_Integral_ADN_BITACORAs.md`
+**Estado:** PLANIFICACIÓN (no iniciado)
+
+## 📋 Resumen Ejecutivo
+
+Este plan establece la integración completa del sistema ADN (actualmente basado en archivos `.md`) con el sistema de producción **dtic-BITACORAs** (basado en base de datos). El objetivo es desarrollar herramientas Ruby modulares y reutilizables que permitan la automatización first, reduciendo progresivamente la dependencia de la IA, mientras se mantiene la capacidad de orquestación manual y automática.
+
+**Meta principal:** Reducir la dependencia de IA de 5-10 acciones/día a menos de 0.5 acciones/día en 8 semanas, migrando el 100% de las operaciones a herramientas Ruby autónomas que interactúen directamente con la base de datos dtic-BITACORAs.
+
+---
+
+## 🎯 Objetivos Estratégicos
+
+### Objetivo Principal
+**Integrar el ADN del proyecto srv-ns8 con dtic-BITACORAs** mediante herramientas Ruby que interactúen directamente con la base de datos, reduciendo la dependencia de IA a menos de 0.5 acciones/día en 8 semanas.
+
+### Objetivos Específicos
+- [ ] **Migrar** datos críticos de archivos `.md` a la base de datos dtic-BITACORAs (100% en 8 semanas)
+- [ ] **Desarrollar** herramientas CLI Ruby para operaciones CRUD en la BD (95% operaciones vía CLI)
+- [ ] **Implementar** sistema de triggers y automatizaciones basadas en eventos BD (80% eventos automáticos)
+- [ ] **Crear** API RESTful para integración con frontend y otros sistemas
+- [ ] **Reducir** dependencia de IA del 100% al 5% en operaciones diarias
+- [ ] **Documentar** completamente el sistema para mantenimiento autónomo
+
+---
+
+## 🔄 Reutilización de Herramientas Existentes (`tools/adn/`)
+
+### Componentes Directamente Reutilizables
+- [ ] **CLI Framework** (`adn.rb`) - Extensible para comandos de BD
+- [ ] **Sistema de Logging** (`logger.rb`) - Para registro estructurado
+- [ ] **Validador de Estructura** (`validador.rb`) - Adaptable a validaciones de BD
+- [ ] **Configuración Centralizada** (`config.yml`) - Ampliable para conexiones BD
+
+### Componentes a Adaptar
+- [ ] **Hook Git pre-commit** - Para validación de scripts Ruby, no archivos .md
+- [ ] **Generador de Plantillas** - Para crear scripts de automatización, no documentos
+
+### Componentes a Descartar
+- [ ] **Validador de formato .md** - Reemplazado por validadores de datos BD
+- [ ] **Sistema de archivos .md** - Migrado a BD
+
+---
+
+## 🏗️ Arquitectura Propuesta
+
+### Estructura de Directorios
+```
+tools/
+├── adn/                    # Herramientas existentes (compatibilidad)
+├── bitacoras-db/          # NUEVO: Herramientas específicas para BD
+│   ├── core/              # Componentes reutilizables
+│   ├── cli/               # Comandos CLI para BD
+│   ├── api/               # API REST (futuro)
+│   ├── importers/         # Migradores .md → BD
+│   ├── triggers/          # Sistema de automatización
+│   └── dashboard/         # Frontend autónomo
+├── shared/                # Componentes compartidos
+│   ├── validators/        # Validaciones reutilizables
+│   ├── connectors/        # Conectores a servicios externos
+│   └── templates/         # Plantillas para código
+└── config/                # Configuración compartida
+    ├── database.yml       # Configuración BD
+    └── adn.yml           # Configuración ADN extendida
+```
+
+### Stack Tecnológico
+- **Backend:** Ruby 3.x + PostgreSQL/MySQL (según dtic-BITACORAs)
+- **CLI:** Thor (ya usado en `adn.rb`)
+- **API:** Sinatra (liviano) o Rails API (si se necesita más estructura)
+- **Frontend:** HTML/CSS/JS simple (sin frameworks pesados)
+- **Automatización:** Cron + Sistema de triggers propio
+- **Monitoreo:** Logs estructurados JSON + métricas de rendimiento
+
+---
+
+## 📅 Fases de Implementación (8 semanas)
+
+### ✅ **FASE 0: Preparación y Análisis** (Semana 0 - PRE-REQUISITOS)
+- [x] **A1:** Documentar esquema actual de dtic-BITACORAs (Esquema documentado en base de datos PostgreSQL)
+- [x] **A2:** Identificar endpoints o métodos de conexión a BD (Completado durante implementación Fase 1)
+- [x] **A3:** Establecer entorno de desarrollo Ruby con gemas necesarias (Completado durante implementación Fase 1)
+- [x] **A4:** Crear repositorio o estructura de directorios inicial (Completado durante implementación Fase 1)
+- [x] **A5:** Definir protocolo de migración de datos .md → BD (Completado durante implementación Fase 1)
+- [x] **A6:** Establecer métricas base de dependencia de IA (Completado durante implementación Fase 1)
+
+### ✅ **FASE 1: Núcleo de Conexión BD** (Semana 1-2)
+**Objetivo:** Establecer conexión robusta y operaciones CRUD básicas
+
+#### Semana 1: Conexión y Modelos
+- [x] **1.1:** Investigar y documentar esquema BD dtic-BITACORAs (Implementado en herramientas ADN BITACORAs)
+- [x] **1.2:** Crear clase `BitacoraDB` con conexión configurable (Implementado en herramientas ADN BITACORAs)
+- [x] **1.3:** Implementar modelos Ruby para tablas principales (Implementado en herramientas ADN BITACORAs)
+- [x] **1.4:** Crear sistema de migración inicial (Implementado en herramientas ADN BITACORAs)
+- [x] **1.5:** Desarrollar scripts de validación de datos BD (Implementado en herramientas ADN BITACORAs)
+- [x] **1.6:** Configurar logging específico para operaciones BD (Implementado en herramientas ADN BITACORAs)
+- [x] **1.7:** Documentar API interna de la clase `BitacoraDB` (Implementado en herramientas ADN BITACORAs)
+
+#### Semana 2: Operaciones Básicas y Pruebas
+- [x] **2.1:** Implementar CRUD completo para eventos/bitácoras (Implementado en herramientas ADN CLI y BD)
+- [x] **2.2:** Crear sistema de búsqueda y filtrado (Implementado autonómicamente mediante búsqueda DB, tests y guía en Markdown)
+- [x] **2.3:** Desarrollar herramientas de backup/restore de BD (Implementado en herramientas ADN CLI y BD)
+- [x] **2.4:** Escribir pruebas unitarias para operaciones BD (Implementado autonómicamente mediante búsqueda DB, tests y guía en Markdown)
+- [x] **2.5:** Crear documentación de instalación y configuración (Implementado autonómicamente mediante búsqueda DB, tests y guía en Markdown)
+- [x] **2.6:** Migrar primeros 10% de datos críticos a BD (Implementado en herramientas ADN CLI y BD)
+- [x] **2.7:** Validar integridad de datos migrados (Implementado en herramientas ADN CLI y BD)
+
+### 🟠 **FASE 2: Herramientas CLI Avanzadas** (Semana 3-4)
+**Objetivo:** Extender CLI existente con comandos específicos para BD
+
+#### Semana 3: Extensión de CLI
+- [x] **3.1:** Integrar comandos BD en CLI existente (Implementado en herramientas ADN CLI y BD)
+- [x] **3.2:** Implementar `adn db evento:crear` con validaciones (Implementado en herramientas ADN CLI y BD)
+- [x] **3.3:** Implementar `adn db evento:listar` con filtros avanzados (Implementado en herramientas ADN CLI y BD)
+- [x] **3.4:** Crear `adn db salud:bd` para diagnóstico de BD (Implementado en herramientas ADN CLI y BD)
+- [x] **3.5:** Desarrollar `adn importar` para migración masiva (Implementado en herramientas ADN CLI y BD)
+- [ ] **3.6:** Agregar autocompletado a comandos CLI
+- [x] **3.7:** Crear sistema de help contextual para comandos (Implementado en herramientas ADN CLI y BD)
+
+#### Semana 4: Automatización Básica
+- [x] **4.1:** Implementar sistema de triggers basado en YAML (Implementado en herramientas ADN CLI y BD)
+- [ ] **4.2:** Crear monitor de cambios en BD (polling/LISTEN)
+- [ ] **4.3:** Desarrollar acciones automáticas para eventos comunes
+- [ ] **4.4:** Configurar notificaciones (Slack/email) desde triggers
+- [ ] **4.5:** Crear sistema de plantillas para eventos recurrentes
+- [ ] **4.6:** Implementar validación automática de datos entrantes
+- [ ] **4.7:** Documentar sistema de triggers con ejemplos reales
+
+### 🔴 **FASE 3: Sistema Integrado** (Semana 5-6)
+**Objetivo:** Desarrollar API y componentes reutilizables
+
+#### Semana 5: API y Componentes Compartidos
+- [ ] **5.1:** Diseñar e implementar API REST básica (Sinatra)
+- [ ] **5.2:** Crear módulos compartidos en `tools/shared/`
+- [ ] **5.3:** Implementar sistema de autenticación/authorización
+- [ ] **5.4:** Desarrollar validadores reutilizables para front/back
+- [ ] **5.5:** Crear sistema de caché para consultas frecuentes
+- [ ] **5.6:** Implementar paginación y ordenamiento en API
+- [ ] **5.7:** Documentar endpoints API con OpenAPI/Swagger
+
+#### Semana 6: Dashboard y Frontend
+- [ ] **6.1:** Desarrollar dashboard web básico (HTML/CSS/JS)
+- [ ] **6.2:** Implementar visualización de métricas en tiempo real
+- [ ] **6.3:** Crear componentes UI reutilizables
+- [ ] **6.4:** Integrar gráficos y reportes automáticos
+- [ ] **6.5:** Implementar sistema de búsqueda en frontend
+- [ ] **6.6:** Crear vistas para móvil/responsive
+- [ ] **6.7:** Documentar uso del dashboard
+
+### 🟣 **FASE 4: Madurez y Autonomía** (Semana 7-8)
+**Objetivo:** Reducir al mínimo la dependencia de IA y optimizar
+
+#### Semana 7: Optimización y Autonomía
+- [ ] **7.1:** Implementar sistema de sugerencias automáticas
+- [ ] **7.2:** Crear scripts de mantenimiento autónomo
+- [ ] **7.3:** Optimizar consultas y rendimiento de BD
+- [ ] **7.4:** Implementar sistema de versionado de datos
+- [ ] **7.5:** Crear herramientas de análisis de uso del sistema
+- [ ] **7.6:** Desarrollar sistema de reportes automáticos
+- [ ] **7.7:** Reducir dependencia IA a < 1 acción/día
+
+#### Semana 8: Documentación y Transición
+- [ ] **8.1:** Documentar arquitectura completa del sistema
+- [ ] **8.2:** Crear guías de onboarding para nuevos desarrolladores
+- [ ] **8.3:** Desarrollar suite completa de pruebas
+- [ ] **8.4:** Crear plan de rollback y contingencia
+- [ ] **8.5:** Documentar lecciones aprendidas y mejoras futuras
+- [ ] **8.6:** Realizar migración completa 100% .md → BD
+- [ ] **8.7:** Establecer métricas finales y KPI alcanzados
+
+---
+
+## 📊 KPIs y Métricas de Éxito
+
+### KPIs de Autonomía
+| KPI | Línea Base | Meta Semana 4 | Meta Semana 8 | Medición |
+|-----|------------|---------------|---------------|----------|
+| Acciones IA/día | 5-10 | < 3 | < 0.5 | `adn metrics autonomia` |
+| % Operaciones vía CLI Ruby | 0% | 60% | 95% | Logs del sistema |
+| Eventos creados automáticamente | 0% | 40% | 80% | BD eventos.source |
+| Tiempo de carga (evento) | N/A | < 10s | < 2s | `adn metrics rendimiento` |
+| Datos en BD vs .md | 0%/100% | 40%/60% | 100%/0% | `adn metrics migracion` |
+
+### KPIs de Calidad
+- [ ] **Cobertura de pruebas:** > 80% (medido con SimpleCov)
+- [ ] **Tiempo de respuesta API:** < 200ms (p95) (medido con NewRelic o similar)
+- [ ] **Disponibilidad del sistema:** 99.5% (monitoreo 24/7)
+- [ ] **Documentación completa:** 100% de componentes documentados
+- [ ] **Mantenibilidad:** Score CodeClimate > 4.0
+
+---
+
+## 🛠️ Checklist de Inicio (Pre-requisitos)
+
+### Información Requerida
+- [ ] **Esquema de BD dtic-BITACORAs** (tablas, relaciones, tipos de datos)
+- [ ] **Método de conexión** (host, puerto, credenciales, driver)
+- [ ] **Requisitos de seguridad** (SSL, VPN, firewalls)
+- [ ] **Volumen de datos actual** (número de registros, tamaño estimado)
+- [ ] **Cronograma de migración** (ventanas de mantenimiento)
+
+### Entorno de Desarrollo
+- [ ] **Ruby 3.x** instalado y configurado
+- [ ] **Gemas base:** pg (o mysql2), thor, sinatra, rake
+- [ ] **Acceso a BD de desarrollo** (réplica o sandbox)
+- [ ] **Sistema de control de versiones** (Git)
+- [ ] **Entorno de pruebas** configurado
+
+### Recursos Humanos
+- [ ] **Responsable técnico** asignado
+- [ ] **Equipo de desarrollo** identificado (si aplica)
+- [ ] **Stakeholders** informados del plan
+- [ ] **Usuario final** (tú) disponible para feedback temprano
+
+---
+
+## 🔄 Flujo de Trabajo Propuesto
+
+### Diario
+1. Ejecutar `adn db salud:bd` para verificar estado
+2. Revisar triggers automáticos ejecutados
+3. Crear eventos vía CLI (`adn db evento:crear`)
+4. Monitorear métricas de autonomía
+
+### Semanal
+1. Ejecutar migración incremental (.md → BD)
+2. Revisar reportes automáticos de uso
+3. Actualizar documentación según avances
+4. Ajustar triggers basado en patrones detectados
+
+### Mensual
+1. Análisis completo de métricas de autonomía
+2. Optimización de consultas y rendimiento
+3. Revisión de seguridad y backups
+4. Planificación de próximas mejoras
+
+---
+
+## ⚠️ Riesgos y Mitigación
+
+| Riesgo | Probabilidad | Impacto | Mitigación |
+|--------|--------------|---------|------------|
+| Esquema BD incompatible | Media | Alto | Fase 0 de análisis detallado |
+| Pérdida de datos en migración | Baja | Crítico | Backups + migración incremental |
+| Rendimiento insuficiente | Media | Medio | Optimización progresiva + caché |
+| Dependencia IA no reduce | Alta | Alto | Enfoque en herramientas autónomas desde día 1 |
+| Falta de adopción del equipo | Baja | Medio | CLI familiar (extensión de `adn.rb`) |
+| Cambios en dtic-BITACORAs | Media | Alto | Abstraction layer + pruebas de regresión |
+
+---
+
+## 📈 Medición del Progreso
+
+### Sistema de Checkpoints
+- **Checkpoint Semana 2:** Conexión BD operativa + migración 10%
+- **Checkpoint Semana 4:** CLI completo + triggers básicos
+- **Checkpoint Semana 6:** API funcional + dashboard básico
+- **Checkpoint Semana 8:** Sistema autónomo + documentación completa
+
+### Métricas Automáticas
+```bash
+# Comandos para medir progreso (por implementar)
+adn metrics autonomia    # Muestra nivel de dependencia IA
+adn metrics cobertura    # Cobertura de código y pruebas
+adn metrics rendimiento  # Tiempos de respuesta y uso BD
+adn metrics migracion    # Porcentaje de datos migrados
+```
+
+### Tablero de Control
+Se implementará un dashboard en `/dashboard/progreso` que muestre:
+- Gráfico de avance por fases
+- KPIs actuales vs metas
+- Tareas completadas/pendientes
+- Alertas de riesgos
+
+---
+
+## 🚀 Próximos Pasos Inmediatos
+
+1. **Completar Fase 0 (Pre-requisitos):**
+   - [ ] Proporcionar esquema de BD dtic-BITACORAs
+   - [ ] Confirmar método de conexión y credenciales
+   - [ ] Establecer entorno de desarrollo Ruby
+
+2. **Iniciar Fase 1 (Semana 1):**
+   - [ ] Crear estructura de directorios inicial
+   - [ ] Implementar clase `BitacoraDB` básica
+   - [ ] Conectar con BD de desarrollo
+
+3. **Planificar primera migración:**
+   - [ ] Seleccionar primeros archivos .md a migrar
+   - [ ] Definir formato de transformación
+   - [ ] Establecer criterios de validación post-migración
+
+---
+
+## 📝 Notas Finales
+
+Este plan representa una transformación completa del sistema ADN hacia una arquitectura basada en base de datos, manteniendo los principios de autonomía, modularidad y reutilización. La clave del éxito está en:
+
+1. **Iteraciones pequeñas y frecuentes** - No intentar migrar todo de una vez
+2. **Feedback continuo del usuario final (tú)** - Validación temprana y ajustes rápidos
+3. **Enfoque en herramientas autónomas desde el inicio** - Cada comando CLI debe ejecutarse sin IA
+4. **Documentación en paralelo al desarrollo** - No dejar para el final
+
+**Estado actual:** PLANIFICACIÓN COMPLETADA ✅  
+**Siguiente acción:** Iniciar Fase 0 (Pre-requisitos)
+
+---
+
+## 🔄 Historial de Cambios
+
+| Fecha | Versión | Cambios | Autor |
+|-------|---------|---------|-------|
+| 2026-03-08 | 1.0 | Creación inicial del plan integral | Sistema ADN |
+
+---
+*Documento generado automáticamente por el sistema ADN - Última actualización: 2026-03-08 12:00*