diff --git a/adn/README.md b/adn/README.md index fb9b5add..ab8e2036 100644 --- a/adn/README.md +++ b/adn/README.md @@ -1,48 +1,259 @@ -# 🧬 ADN del Proyecto: srv-ns8 (Arquitectura de Datos y Normas) +# ADN — Arquitectura de Datos y Normas (dtic-DIIAA) -## Resumen Ejecutivo -El directorio `adn/` constituye el "núcleo genético" del servidor `srv-ns8`. No es simplemente una carpeta de documentos, sino un sistema dinámico e interconectado que define las reglas de gobernanza, la ontología de la infraestructura y los protocolos de sincronización del proyecto. Su principio rector es la **Armonía Integral**, donde cualquier cambio en la infraestructura o en los registros debe propagarse para mantener la coherencia del sistema completo. +> **DIRECTIVA PARA AGENTES IA**: Este archivo es tu punto de entrada obligatorio. +> Léelo COMPLETO antes de ejecutar cualquier acción sobre el repositorio. + +## Identidad del Proyecto + +| Clave | Valor | +| :--------------- | :----------------------------------------------------------------- | +| **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) | +| **Zona Horaria** | `America/Argentina/Buenos_Aires` (UTC-3) | --- -## 🔍 Análisis Estructural -- **Tipo de Proyecto**: Sistema de Gobernanza de Infraestructura y Metadatos (Documentación Viva + Automatización). -- **Organización**: Se estructura en **Hebras (1 a 7)**, cada una responsable de un dominio operativo: - - `01_ontologia.md`: Definición de nodos (Proxmox, Xen, VMs, Satélites). - - `02_bitacora.md`: Estándar para el registro diario y reglas de triggers. - - `03_seguridad.md`: Protocolos de protección y acceso seguro. - - `04_iconografia.md`: Taxonomía visual semántica para estados y eventos. - - `05_ia.md`: Normas y directivas específicas para la interacción con IAs. - - `06_gobernanza.md`: Normas de nomenclatura, evolución del sistema y codificación. - - `07_proyectos.md`: Gestión transversal de proyectos e hitos. -- **Archivos Fundamentales**: - - `00_indice.md`: El punto de entrada que explica la interconexión entre Hebras, Bitácoras y Nodos. - - `triggers.yml`: Archivo de configuración que orquesta la automatización de la propagación de datos. +## Principios Rectores del ADN -## ⚙️ Configuración y Dependencias -- **Tecnologías Clave**: - - **Motor de ejecución**: Ruby (utilizado para scripts de automatización como `adn/tools/run`). - - **Formatos**: Markdown para documentación y YAML para reglas de automatización. - - **Entorno**: Dockerizado para servicios de red (Nginx, Homepage, Bitácoras). -- **Configuración Relevante**: - - `triggers.yml`: Define qué acciones disparar ante eventos específicos (ej. cierre de tareas, creación de nuevas bitácoras). -- **Comandos Necesarios**: - - `./adn/tools/run triggers`: Procesa y sincroniza los cambios basados en las reglas del ADN. - - `ruby adn/tools/seguridad/ns8-candados.rb`: Gestiona la seguridad y secretos del servidor. +### Tríptico Rector +Los tres principios que rigen toda decisión operativa del proyecto son: -## 🧠 Contexto para IA -- **Patrones y Convenciones**: Se debe mantener estrictamente la iconografía semántica (`04_iconografia.md`) y seguir las directivas de la Hebra 05. Ningún cambio debe romper la "Armonía Integral" definida en el índice. -- **Áreas Críticas**: - - `triggers.yml` es vital para la integridad de los datos. - - La sincronización entre Bitácoras y Ontología es el punto más sensible de la operación diaria. -- **Deuda Técnica**: El sistema de triggers está en fase de desarrollo (Fase 2: Automatización), por lo que requiere supervisión humana para validar ciertas propagaciones complejas. +1. **Menos es Más (Simplicidad Radical)**: Cada componente debe justificar su existencia y ser atómico y reutilizable. Preferir herramientas unificadas sobre scripts temporales, eliminar duplicaciones y consolidar funcionalidades dispersas. Los componentes deben diseñarse como piezas modulares que puedan ser reutilizadas por otros, evitando monolitos hardcodeados y promoviendo la composición sobre la duplicación. -## 🚀 Próximos Pasos -- **Documentación Pendiente**: Expandir la documentación de red en la Ontología para incluir diagramas de topología actualizados. -- **Preguntas para Nuevos Colaboradores**: - - ¿Cómo se asegura que un nuevo nodo en Proxmox esté correctamente reflejado en la Ontología? - - ¿Qué icono semántico corresponde a una tarea en proceso versus una tarea bloqueada? -- **Primera Tarea Lógica**: Verificar que las últimas entradas de la bitácora cumplan con el formato de la Hebra 02 y que los triggers hayan procesado las actualizaciones de estado. +2. **Armonía Integral**: El ADN, las Bitácoras, los Nodos y los Proyectos forman un organismo interconectado. La coherencia es un requisito de supervivencia. + +3. **Mejora Continua (Evolución Progresiva)**: El ADN no es estático; evoluciona a partir de descubrimientos y buenas prácticas emergentes de la operación diaria. + +### Principio Rector: Armonía Integral + +**Si un dato cambia en un sitio, DEBE propagarse a todos los demás.** + +El ADN, las Bitácoras, los Nodos y los Proyectos forman un organismo interconectado. +Ante cualquier inconsistencia detectada, **resolverla es prioritario antes de avanzar**. --- -*Generado siguiendo docs/prompt/documentacion.md* + +## Estructura del Directorio `adn/` + +``` +adn/ +├── README.md ← ESTE ARCHIVO (punto de entrada IA) +├── 00_indice.md ← Mapa general del ADN y tabla de bitácoras +├── 01_ontologia.md ← Definición de nodos, servicios y topología de red +├── 02_bitacora.md ← Formato del registro diario y reglas de triggers +├── 03_seguridad.md ← Protocolos de seguridad, bóveda y secretos +├── 04_iconografia.md ← Taxonomía visual: iconos semánticos para estados +├── 05_ia.md ← ⚠️ FUENTE ÚNICA DE VERDAD para premisas IA +├── 06_gobernanza.md ← Nomenclatura, codificación, armonía y evolución +├── 07_proyectos.md ← Gestión transversal de proyectos e hitos +├── triggers.yml ← Configuración del motor de triggers (propagación) +├── conocimiento/ ← Base de conocimiento asimilado +│ └── configuracion_bd.md +└── tools/ ← Motor de ejecución y automatización (ver abajo) +``` + +Las hebras `01` a `07` son documentos normativos vivos. La hebra `05_ia.md` es la +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. + +**Punto de entrada**: `./adn/tools/run [opciones]` + +### Subcomandos Disponibles + +| 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 | + +### Subcomandos de Base de Datos (`db`) + +| 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| + +### Ejemplos Frecuentes + +```bash +# Inicio de jornada presencial a las 08:00 +./adn/tools/run jornada iniciar presencial 08:00 + +# Cierre de jornada remota a las 23:00 +./adn/tools/run jornada cerrar remoto 23:00 + +# 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 +./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")' + +# Ver nodos agrupados por servidor +./adn/tools/run nodos agrupar + +# Filtrar VMs de un servidor específico +./adn/tools/run nodos agrupar --servidor srv-pmox1 + +# Listar solo VMs de servicio +./adn/tools/run nodos listar --tipo srvv + +# Buscar nodos relacionados con dasuten +./adn/tools/run nodos buscar dasuten + +# Backup de un nodo +./adn/tools/run backup sql-dasuten +``` + +--- + +## Estructura de tools/ + +``` +adn/tools/ +├── run ← Entry point CLI (ejecutable Ruby) +├── cli/ ← Subcomandos CLI (1 archivo por subcomando) +│ ├── ayuda.rb ← Documentación interna de la herramienta +│ ├── backup.rb ← Backup seguro de nodos +│ ├── cierre.rb ← Cierre de jornada (DB-First) +│ ├── conocimiento.rb ← Asimilación de documentación +│ ├── contexto.rb ← Contexto topológico de nodos +│ ├── db.rb ← Dispatcher de subcomandos DB +│ ├── db/ ← Subcomandos específicos de DB (evento, bitacora, nodo, etc.) +│ ├── generar.rb ← Generación de bitácoras, nodos y proyectos +│ ├── inicio.rb ← Inicio de jornada (DB-First) +│ ├── nodos.rb ← Agrupación de nodos por servidor +│ ├── plan.rb ← Gestión de planes y progreso +│ ├── salud.rb ← Métricas de salud del ADN +│ ├── triggers.rb ← Gestión del motor de triggers +│ └── validador.rb ← Validación de cumplimiento ADN +├── core/ ← Módulos centrales (Singleton) +│ ├── colores.rb ← Constantes de color para terminal +│ ├── conciliador.rb ← Saneamiento preventivo de pendientes +│ ├── configurador.rb ← Carga de configuración YAML +│ ├── eventos.rb ← Bus de eventos (pub/sub desacoplado) +│ ├── logger.rb ← Logger estructurado (JSON) +│ ├── triggers.rb ← Motor de triggers (reacción automática) +│ └── validador.rb ← Validador de formato ADN +├── db/ ← Capa de acceso a datos (PostgreSQL) +│ ├── core/ ← bitacora_db.rb (CRUD principal), buscadores +│ ├── cli/ ← Scripts CLI para exportación masiva +│ ├── exporters/ ← md_exporter.rb (DB → Markdown) +│ └── importers/ ← Importadores (Markdown → DB) +├── config/ ← Configuración +│ ├── database.yml ← Conexión PostgreSQL (puerto 5433) +│ └── config.yml ← Configuración general +├── hooks/ ← Git hooks (pre-commit) +├── parsers/ ← Parsers especializados (plan.rb) +├── seguridad/ ← ns8-candados (gestión de secretos) +└── sondas/ ← Sondas remotas (w-zombi) +``` + +--- + +## Base de Datos (PostgreSQL) + +| Clave | Valor | +| :----------- | :----------------------------- | +| **Host** | `localhost` | +| **Puerto** | `5433` (Docker → 5432 interno) | +| **Database** | `dtic_bitacoras` | +| **Schema** | `bitacoras` | +| **Config** | `adn/tools/config/database.yml`| + +### Tablas Principales (schema `bitacoras`) + +| Tabla | Descripción | +| :---------- | :---------------------------------------------------- | +| `nodos` | Servidores, VMs, PCs, servicios del sistema | +| `bitacoras` | Bitácoras diarias (fecha única por registro) | +| `entradas` | Entradas cronológicas en formato I-F-D-E | +| `temas` | Agrupadores de entradas por nodo | +| `gestion` | Items de control de gestión (pendientes, en proceso) | +| `proyectos` | Proyectos transversales | +| `fases` | Fases de los proyectos | +| `hitos` | Hitos individuales de cada fase | + +### Docker Compose + +Ubicación: `servicios/nginx/dtic-bitacoras/docker-compose.yml` +Servicios: `postgres` (BD), `api` (Node.js, puerto 3002), `frontend` (Vite, puerto 5174). + +--- + +## Directorios del Repositorio + +| Directorio | Propósito | +| :--------------- | :----------------------------------------------------- | +| `adn/` | Núcleo genético: hebras, herramientas, conocimiento | +| `nodos/` | Fichas técnicas de cada nodo (1 archivo .md por nodo) | +| `docs/bitacoras/`| Bitácoras diarias exportadas en Markdown | +| `docs/proyectos/`| Manifiestos de proyectos | +| `docs/plan/` | Planes de mejora y arquitectura | +| `servicios/` | Docker Compose y configs de servicios (nginx, etc.) | +| `logs/` | Logs estructurados del sistema ADN | +| `automatizacion/`| Scripts legacy (en proceso de migración a adn/tools) | + +--- + +## Directivas Críticas para IA + +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. + +2. **Fuente de verdad: `05_ia.md`**: Lee y sigue TODAS las premisas antes de operar. + +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`). + +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.