From 4b000aeb89ecd99a56882490b78d50c3a656952f Mon Sep 17 00:00:00 2001 From: Ricardo Monla Date: Thu, 12 Mar 2026 05:57:34 -0300 Subject: [PATCH] =?UTF-8?q?[ADN]=20Actualizaci=C3=B3n=20completa=20a=20fil?= =?UTF-8?q?osof=C3=ADa=20DB-First=20-=20Clarificaci=C3=B3n=20Ruby=20como?= =?UTF-8?q?=20lenguaje=20y=20registro=20en=20bit=C3=A1cora=20web?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- adn/README.md | 246 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 167 insertions(+), 79 deletions(-) diff --git a/adn/README.md b/adn/README.md index ab8e2036..f943f455 100644 --- a/adn/README.md +++ b/adn/README.md @@ -10,11 +10,74 @@ | **Nombre** | dtic-DIIAA (Departamento de Investigación de IA y Automatización) | | **Repositorio** | `/home/rmonla/Documentos/GitHub/dtic-DIIAA` | | **Idioma** | Español (TODO: docs, commits, comentarios, interacciones) | -| **Lenguaje** | Ruby (scripts y herramientas operativas) | +| **Lenguaje** | Ruby (lenguaje de desarrollo para componentes y herramientas) | +| **Filosofía** | DB-First (Base de Datos PostgreSQL → Web) | | **Zona Horaria** | `America/Argentina/Buenos_Aires` (UTC-3) | --- +## Desarrollo y Registro de Actividades + +### Lenguaje de Desarrollo: Ruby +- **Ruby es el lenguaje estándar** para todos los componentes, scripts y herramientas del proyecto. +- **Justificación**: Manejo robusto de excepciones, escalabilidad estructural y consistencia frente a la fragilidad de Bash para secuencias complejas. +- **Alcance**: Scripts de automatización (`tools/`), procesadores de respaldos, utilidades de gestión y cualquier lógica operativa recurrente. +- **Excepción**: Bash se permite únicamente para one-liners, wrappers de lanzamiento y tareas triviales de sistema donde Ruby introduzca complejidad innecesaria. + +### Filosofía DB-First (Base de Datos PostgreSQL → Web) +**El sistema sigue una arquitectura DB-First donde PostgreSQL es la fuente de verdad única:** + +1. **Base de Datos como Fuente Primaria**: Todas las bitácoras, eventos, nodos y proyectos se almacenan primero en PostgreSQL. +2. **Web como Interfaz**: La capa web (API Node.js + Frontend Vite) consume datos directamente de la base de datos. +3. **Sin Duplicación MD**: Los archivos `.md` son exportaciones secundarias, no fuentes primarias (evitar el anti-patrón MD-First). +4. **Validador Obsoleto**: La herramienta `validador` está en desuso por estar orientada a validación de archivos `.md` en lugar de validación de coherencia en la base de datos. + +### Registro en Bitácora (DB-First) +**Toda actividad de desarrollo DEBE registrarse directamente en la base de datos PostgreSQL:** + +1. **Auto-Registro Obligatorio**: Cualquier trabajo en componentes, scripts o herramientas Ruby debe registrarse como entrada en la bitácora del día usando `db evento:crear`. +2. **Formato DB-First**: Usar exclusivamente los subcomandos `db` de `./adn/tools/run` para operaciones CRUD. +3. **Trazabilidad en DB**: Cada modificación queda documentada en PostgreSQL con: + - Contexto del cambio (qué componente y por qué) + - Estado (✅ completado, ⏳ en proceso, ❌ fallido) + - Métricas híbridas (tiempo invertido) + - Relaciones con nodos y proyectos +4. **Exportación Opcional**: La exportación a Markdown es opcional y solo para archivo histórico, no para operación. + +### Flujo de Trabajo DB-First +1. **Iniciar jornada**: `./adn/tools/run jornada iniciar [modo] [HH:MM]` (registra en DB) +2. **Registrar actividad**: `./adn/tools/run db evento:crear [opciones]` (crea entrada en DB) +3. **Desarrollar componente Ruby**: Seguir principios "Menos es Más" (atómico, reutilizable) +4. **Operaciones DB**: Usar `./adn/tools/run db` para todas las operaciones (listar, actualizar, eliminar) +5. **Registrar finalización**: `./adn/tools/run db evento:actualizar --fin HH:MM --estado completado` +6. **Verificar en Web**: Acceder a `http://localhost:5174` para visualizar bitácora actualizada +7. **Resguardar cambios**: Commit y push con formato `[Categoría] Descripción` + +### Subcomandos DB Disponibles +```bash +# Salud de la base de datos +./adn/tools/run db salud:bd + +# Gestión de eventos (entradas cronológicas) +./adn/tools/run db evento:crear --nodo --titulo "Título" --inicio HH:MM +./adn/tools/run db evento:listar [--desde FECHA] [--hasta FECHA] [--nodo NODO] +./adn/tools/run db evento:actualizar [--fin HH:MM] [--estado ESTADO] +./adn/tools/run db evento:eliminar + +# Gestión de bitácoras +./adn/tools/run db bitacora:crear [FECHA] +./adn/tools/run db bitacora:listar [--limit N] + +# Gestión de nodos +./adn/tools/run db nodo:crear --nombre --tipo +./adn/tools/run db nodo:listar [--tipo TIPO] + +# Estadísticas +./adn/tools/run db estadisticas +``` + +--- + ## Principios Rectores del ADN ### Tríptico Rector @@ -61,90 +124,114 @@ referencia canónica y exclusiva de las directivas que un agente IA debe seguir. ## Herramienta CLI: `adn/tools/run` -> **REGLA**: Antes de crear scripts temporales o ejecutar SQL directo, -> busca si ya existe un subcomando que haga lo que necesitas. +> **REGLA DB-FIRST**: Antes de crear scripts temporales o ejecutar SQL directo, +> busca si ya existe un subcomando `db` que haga lo que necesitas. **Punto de entrada**: `./adn/tools/run [opciones]` -### Subcomandos Disponibles +### Subcomandos Disponibles (DB-First) -| Subcomando | Descripción | -| :------------------------------------ | :----------------------------------------------- | -| `validador [--watch] [--fix]` | Validar cumplimiento del ADN en bitácoras | -| `contexto [--cmd]` | Obtener contexto topológico y SSH de un nodo | -| `nodos agrupar [--servidor SRV]` | Agrupar VMs por servidor anfitrión | -| `nodos listar [--tipo TIPO]` | Listar fichas de nodos (.md) | -| `nodos buscar ` | Buscar nodos por nombre o contenido | -| `jornada iniciar [modo] [HH:MM]` | Registrar inicio de jornada laboral | -| `jornada cerrar [modo] [HH:MM]` | Registrar cierre de jornada laboral | -| `jornada estado` | Ver estado de la jornada actual | -| `salud [--dashboard] [--json]` | Ver salud general del sistema ADN | -| `generar bitacora [fecha]` | Generar nueva bitácora (YYYY-MM-DD, default: hoy) | -| `generar nodo ` | Generar ficha de nodo | -| `generar proyecto ` | Generar manifiesto de proyecto | -| `conocimiento asimilar ` | Asimilar documentación al ADN | -| `backup [--mode MODO]` | Ejecutar backup seguro de un nodo | -| `triggers [--listar/--registrar]` | Gestión del motor de triggers | -| `plan [subcomando]` | Gestión de planes y progreso de proyectos | -| `ayuda [subcomando]` | Mostrar ayuda detallada | +| Subcomando | Descripción | Filosofía | +| :------------------------------------ | :----------------------------------------------- | :------------------ | +| `db ` | **Operaciones DB-First** (fuente de verdad) | PostgreSQL Primario | +| `jornada iniciar [modo] [HH:MM]` | Registrar inicio de jornada laboral en DB | DB-First | +| `jornada cerrar [modo] [HH:MM]` | Registrar cierre de jornada laboral en DB | DB-First | +| `jornada estado` | Ver estado de la jornada actual desde DB | DB-First | +| `contexto [--cmd]` | Obtener contexto topológico y SSH de un nodo | Consulta DB | +| `nodos agrupar [--servidor SRV]` | Agrupar VMs por servidor anfitrión | Consulta DB | +| `nodos listar [--tipo TIPO]` | Listar nodos desde base de datos | DB-First | +| `nodos buscar ` | Buscar nodos en base de datos | DB-First | +| `salud [--dashboard] [--json]` | Ver salud general del sistema ADN | Incluye DB | +| `backup [--mode MODO]` | Ejecutar backup seguro de un nodo | Registra en DB | +| `triggers [--listar/--registrar]` | Gestión del motor de triggers | Sincroniza DB | +| `plan [subcomando]` | Gestión de planes y progreso de proyectos | DB-First | +| `estados` | Listar tareas en proceso (⏳) desde DB | DB-First | +| `proceso ` | Ejecutar procesos técnicos automatizados | Registra en DB | +| `generar bitacora [fecha]` | Generar nueva bitácora en DB (YYYY-MM-DD) | DB-First | +| `generar nodo ` | Generar ficha de nodo en DB | DB-First | +| `generar proyecto ` | Generar manifiesto de proyecto en DB | DB-First | +| `conocimiento asimilar ` | Asimilar documentación al ADN | Almacena en DB | +| `ayuda [subcomando]` | Mostrar ayuda detallada | - | +| `validador [--watch] [--fix]` | ⚠️ **OBSOLETO** - Validación MD-First antigua | MD-First (evitar) | -### Subcomandos de Base de Datos (`db`) +### Subcomandos de Base de Datos (`db`) - Fuente de Verdad -| Subcomando | Descripción | -| :------------------------ | :--------------------------------------------- | -| `db salud:bd` | Verificar conexión y estado de PostgreSQL | -| `db bitacora:crear` | Crear nueva bitácora diaria en DB | -| `db bitacora:listar` | Listar bitácoras existentes | -| `db evento:crear` | Crear nueva entrada cronológica (I-F-D-E) | -| `db evento:listar` | Listar entradas con filtros (nodo, estado, fecha)| -| `db evento:actualizar` | Actualizar una entrada existente | -| `db evento:eliminar` | Eliminar una entrada existente por ID | -| `db nodo:crear` | Crear nuevo nodo (servidor/VM/PC/servicio) | -| `db nodo:listar` | Listar nodos del sistema | -| `db estadisticas` | Mostrar estadísticas del sistema | -| `db archivar:md` | Mover archivos .md migrados al archivo histórico| +| Subcomando | Descripción | Filosofía | +| :------------------------ | :--------------------------------------------- | :------------------ | +| `db salud:bd` | Verificar conexión y estado de PostgreSQL | DB-First | +| `db bitacora:crear` | Crear nueva bitácora diaria en DB | DB-First | +| `db bitacora:listar` | Listar bitácoras existentes desde DB | DB-First | +| `db evento:crear` | Crear nueva entrada cronológica (I-F-D-E) | DB-First | +| `db evento:listar` | Listar entradas con filtros desde DB | DB-First | +| `db evento:actualizar` | Actualizar una entrada existente en DB | DB-First | +| `db evento:eliminar` | Eliminar una entrada existente por ID de DB | DB-First | +| `db nodo:crear` | Crear nuevo nodo en DB | DB-First | +| `db nodo:listar` | Listar nodos desde DB | DB-First | +| `db estadisticas` | Mostrar estadísticas del sistema desde DB | DB-First | +| `db hito:crear` | Crear nuevo hito de proyecto en DB | DB-First | +| `db hito:listar` | Listar hitos desde DB | DB-First | +| `db migrar:md [fecha]` | Migrar bitácora .md legacy a DB (una vez) | Migración | +| `db archivar:md` | Mover archivos .md migrados al histórico | Limpieza | -### Ejemplos Frecuentes +### Ejemplos Frecuentes (DB-First) ```bash -# Inicio de jornada presencial a las 08:00 +# 1. INICIO DE JORNADA (registra en DB) ./adn/tools/run jornada iniciar presencial 08:00 -# Cierre de jornada remota a las 23:00 -./adn/tools/run jornada cerrar remoto 23:00 +# 2. REGISTRAR ACTIVIDAD DE DESARROLLO RUBY (DB-First) +./adn/tools/run db evento:crear --nodo srv-ns8 --titulo "Desarrollo componente Ruby: hook pre-commit mejorado" --inicio 09:00 --descripcion "Mejora del hook pre-commit para mayor robustez y aplicación de principios ADN" -# Ver estado de la jornada actual -./adn/tools/run jornada estado - -# Cerrar una entrada abierta -./adn/tools/run db evento:actualizar --fin 17:00 - -# Listar actividades de hoy +# 3. LISTAR ACTIVIDADES DEL DÍA (consulta DB) ./adn/tools/run db evento:listar --desde $(date +%Y-%m-%d) -# Exportar bitácora a Markdown -ruby -I adn/tools/db -e 'require "core/bitacora_db"; require "exporters/md_exporter"; - db = BitacorasDB::BitacoraDB.new(config_path: "adn/tools/config/database.yml"); - db.connect; BitacorasDB::Exporters::MDExporter.new(db).exportar_bitacora("FECHA", "docs/bitacoras/FECHA.md")' +# 4. ACTUALIZAR ENTRADA AL FINALIZAR (DB-First) +./adn/tools/run db evento:actualizar --fin 12:30 --estado completado -# Ver nodos agrupados por servidor -./adn/tools/run nodos agrupar +# 5. CERRAR JORNADA (registra en DB) +./adn/tools/run jornada cerrar remoto 18:00 -# Filtrar VMs de un servidor específico -./adn/tools/run nodos agrupar --servidor srv-pmox1 +# 6. VER ESTADO ACTUAL (desde DB) +./adn/tools/run jornada estado -# Listar solo VMs de servicio -./adn/tools/run nodos listar --tipo srvv +# 7. LISTAR NODOS DESDE BASE DE DATOS +./adn/tools/run db nodo:listar --tipo srvv -# Buscar nodos relacionados con dasuten +# 8. BUSCAR NODOS EN DB ./adn/tools/run nodos buscar dasuten -# Backup de un nodo +# 9. VER SALUD DEL SISTEMA (incluye DB) +./adn/tools/run salud --dashboard + +# 10. BACKUP CON REGISTRO EN DB ./adn/tools/run backup sql-dasuten + +# 11. VER ESTADÍSTICAS DEL SISTEMA +./adn/tools/run db estadisticas + +# 12. ACCEDER A INTERFAZ WEB (DB → Web) +# http://localhost:5174 (Frontend Vite) +# http://localhost:3002 (API Node.js) ``` --- + +## Directivas Críticas para IA (Actualizado DB-First) + +1. **DB-First es obligatorio**: PostgreSQL es la fuente de verdad única. NUNCA operar sobre archivos `.md` como fuente primaria. +2. **Usar subcomandos `db`**: Para cualquier operación CRUD, usar `./adn/tools/run db `. +3. **Auto-Registro en DB**: Toda acción autónoma de la IA DEBE registrarse como entrada en la bitácora del día usando `db evento:crear`. +4. **Ruby como lenguaje de desarrollo**: Todos los componentes nuevos deben escribirse en Ruby, siguiendo principios "Menos es Más" (atómicos, reutilizables). +5. **Validador obsoleto**: NO usar `validador` (orientado a MD-First). En su lugar, validar coherencia mediante consultas a la base de datos. +6. **Secretos en bóveda**: NUNCA exponer contraseñas en texto plano. Usar `ns8-candados`. +7. **Topología primero**: Antes de conectarte a un nodo, consultar `./adn/tools/run contexto ` para entender su ubicación en la red. +8. **Exportación opcional**: Los archivos `.md` son solo para archivo histórico. La operación real ocurre en PostgreSQL → Web. +9. **Verificar en Web**: Tras modificar la DB, acceder a `http://localhost:5174` para verificar que los cambios se reflejan correctamente. +10. **Zona horaria**: Siempre `America/Argentina/Buenos_Aires`. Ya configurada en herramientas y contenedores Docker. + +--- + ## Estructura de tools/ ``` @@ -234,26 +321,27 @@ Servicios: `postgres` (BD), `api` (Node.js, puerto 3002), `frontend` (Vite, puer --- -## Directivas Críticas para IA +## Notas de Migración (MD-First → DB-First) -1. **Usa las herramientas existentes**: `./adn/tools/run` tiene subcomandos para casi todo. - NO crees scripts temporales en `/tmp/` ni ejecutes SQL directo si existe un subcomando. +### Componentes Obsoletos (MD-First) +- **`validador`**: Herramienta para validar archivos `.md` - en desuso +- **`md_exporter.rb`**: Exportador DB → MD - uso solo para archivo histórico +- **Hooks pre-commit MD**: En proceso de migración a validación de coherencia DB -2. **Fuente de verdad: `05_ia.md`**: Lee y sigue TODAS las premisas antes de operar. +### Componentes Actuales (DB-First) +- **`./adn/tools/run db`**: Subcomandos CRUD para PostgreSQL +- **API Node.js (puerto 3002)**: Interfaz REST para operaciones DB +- **Frontend Vite (puerto 5174)**: Interfaz web que consume API +- **Docker Compose**: Contenedores PostgreSQL + API + Frontend -3. **DB-First**: La base de datos PostgreSQL es la fuente de verdad para bitácoras y - entradas. Los archivos `.md` se generan mediante exportación (`md_exporter.rb`). +### Flujo de Migración Completo +1. **Fase 1**: Operación híbrida (MD + DB) - **COMPLETADO** +2. **Fase 2**: DB como fuente primaria, MD como histórico - **ACTUAL** +3. **Fase 3**: Eliminación completa de dependencias MD-First - **PLANIFICADO** -4. **Secretos**: NUNCA exponer contraseñas en texto plano. Usar `ns8-candados`. - -5. **Auto-Registro**: Toda acción autónoma de la IA DEBE registrarse como entrada - en la bitácora del día usando `db evento:crear`. - -6. **Topología primero**: Antes de conectarte a un nodo, consulta `./adn/tools/run contexto ` - para entender su ubicación en la red (subred, proxy jump, etc.). - -7. **Exportar al cerrar**: Tras modificar entradas en la DB del día, regenerar el `.md` - correspondiente con el exportador. - -8. **Zona horaria**: Siempre `America/Argentina/Buenos_Aires`. Ya configurada en - `adn/tools/run` y en los contenedores Docker. +### Buenas Prácticas Actuales +1. **Siempre comenzar con `db evento:crear`** antes de cualquier trabajo +2. **Usar `db evento:actualizar`** al finalizar para registrar métricas +3. **Consultar `db evento:listar`** para ver estado actual +4. **Verificar en `http://localhost:5174`** para confirmar cambios +5. **Usar `jornada iniciar/cerrar`** para gestión de tiempo de trabajo