# ADN — Arquitectura de Datos y Normas (dtic-DIIAA) > **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) | --- ## Principios Rectores del ADN ### Tríptico Rector Los tres principios que rigen toda decisión operativa del proyecto son: 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. 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**. --- ## 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.