260 lines
13 KiB
Markdown
260 lines
13 KiB
Markdown
# 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 <subcomando> [opciones]`
|
|
|
|
### Subcomandos Disponibles
|
|
|
|
| Subcomando | Descripción |
|
|
| :------------------------------------ | :----------------------------------------------- |
|
|
| `validador [--watch] [--fix]` | Validar cumplimiento del ADN en bitácoras |
|
|
| `contexto <nodo> [--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 <término>` | 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 <nombre>` | Generar ficha de nodo |
|
|
| `generar proyecto <código>` | Generar manifiesto de proyecto |
|
|
| `conocimiento asimilar <archivo>` | Asimilar documentación al ADN |
|
|
| `backup <nodo> [--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 <ID> --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 <nodo>`
|
|
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.
|