rmonla/dtic-DIIAA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cfd0e8452a8ba8c45bfc9dc526922f1d0a9d8d03
dtic-DIIAA/adn/README.md
T
Ricardo Monla cfd0e8452a [ADN] Fase 10: Saneamiento y Consolidación - Un solo punto de verdad 
- S1: Eliminar 'triggers' duplicado en run (líneas 109/131)
- S2: Eliminar cli/commit.rb (truncado, sin uso)
- S3: Eliminar cli/inicio.rb y cli/cierre.rb (legacy, jornada.rb los reemplaza)
- S4: Mover 4 planes obsoletos de docs/plan/adn/ a docs/_hist/plan/adn/
- S5: Mover 14 backups de planes y 3 docs técnicos a docs/_hist/
- S6: Eliminar manifiesto vacío P2604_proyecto_p2604.md
- S7: Corregir referencia a plan obsoleto en run
- S8: Dejar de cargar core/validador.rb obsoleto en run
- S9: Limpiar progreso duplicado en P2604_mejoras_ADN.md
- Agregar Fase 10 al plan P2604 con 10 tareas
- Un solo punto de verdad: adn/README.md
- Un solo plan: docs/proy/p2604_mejoras_ADN/P2604_mejoras_ADN.md
- Registro en bitácora: evento 1073
2026-03-15 14:33:32 -03:00

361 lines
21 KiB
Markdown
Raw Blame History

# 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 (lenguaje de desarrollo para componentes y herramientas) |
| **Filosofía** | DB-First (Base de Datos PostgreSQL → Web) |
| **Zona Horaria** | `America/Argentina/Buenos_Aires` (UTC-3) |
| **Red remota** | **Tailscale** (Cuenta: `pcdasu0@frlr.utn.edu.ar`) |
---
## 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 <ID> --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 <nombre> --titulo "Título" --inicio HH:MM
./adn/tools/run db evento:listar [--desde FECHA] [--hasta FECHA] [--nodo NODO]
./adn/tools/run db evento:actualizar <ID> [--fin HH:MM] [--estado ESTADO]
./adn/tools/run db evento:eliminar <ID>
# 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 <nombre> --tipo <tipo>
./adn/tools/run db nodo:listar [--tipo TIPO]
# Estadísticas
./adn/tools/run db estadisticas
```
---
## 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 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 <subcomando> [opciones]`
### Subcomandos Disponibles (DB-First)
| Subcomando | Descripción | Filosofía |
| :------------------------------------ | :----------------------------------------------- | :------------------ |
| `db <subcomando>` | **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 <nodo> [--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 <término>` | Buscar nodos en base de datos | DB-First |
| `salud [--dashboard] [--json]` | Ver salud general del sistema ADN | Incluye DB |
| `backup <nodo> [--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 <nombre>` | Ejecutar procesos técnicos automatizados | Registra en DB |
| `generar bitacora [fecha]` | Generar nueva bitácora en DB (YYYY-MM-DD) | DB-First |
| `generar nodo <nombre>` | Generar ficha de nodo en DB | DB-First |
| `generar proyecto <código>` | Generar manifiesto de proyecto en DB | DB-First |
| `conocimiento asimilar <archivo>` | Asimilar documentación al ADN | Almacena en DB |
| `msp <subcomando>` | Gestión de MSPs NotebookLM (auditar, registrar, listar) | Integración MCP |
| `ayuda [subcomando]` | Mostrar ayuda detallada | - |
| `validador [--watch] [--fix]` | ⚠️ **OBSOLETO** - Validación MD-First antigua | MD-First (evitar) |
### Subcomandos de Base de Datos (`db`) - Fuente de Verdad
| 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 (DB-First)
```bash
# 1. INICIO DE JORNADA (registra en DB)
./adn/tools/run jornada iniciar presencial 08: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"
# 3. LISTAR ACTIVIDADES DEL DÍA (consulta DB)
./adn/tools/run db evento:listar --desde $(date +%Y-%m-%d)
# 4. ACTUALIZAR ENTRADA AL FINALIZAR (DB-First)
./adn/tools/run db evento:actualizar <ID> --fin 12:30 --estado completado
# 5. CERRAR JORNADA (registra en DB)
./adn/tools/run jornada cerrar remoto 18:00
# 6. VER ESTADO ACTUAL (desde DB)
./adn/tools/run jornada estado
# 7. LISTAR NODOS DESDE BASE DE DATOS
./adn/tools/run db nodo:listar --tipo srvv
# 8. BUSCAR NODOS EN DB
./adn/tools/run nodos buscar dasuten
# 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. AUDITAR MSPs (NotebookLM)
./adn/tools/run msp auditar
# 13. LISTAR MSPs DISPONIBLES
./adn/tools/run msp listar
# 14. 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 <subcomando>`.
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. **Reutilizar módulos core**: Antes de crear nueva lógica, verificar si existe módulo en `core/` (ej: `NodosInfo`, `HelpFormatter`, `ErrorHandler`). Duplicar código está prohibido.
6. **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 `candados` (`eval $(ruby adn/tools/seguridad/candados.rb load <clave>)`).
7. **Topología primero**: Antes de conectarte a un nodo, consultar `./adn/tools/run contexto <nodo>` 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/
```
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 (usa NodosInfo)
│ ├── 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)
│ ├── msp.rb ← Gestión de MSPs NotebookLM
│ ├── nodos.rb ← Agrupación de nodos por servidor (usa NodosInfo)
│ ├── 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 reutilizables
│ ├── colores.rb ← Constantes de color para terminal
│ ├── conciliador.rb ← Saneamiento preventivo de pendientes
│ ├── configurador.rb ← Carga de configuración YAML
│ ├── error_handler.rb ← Helper para mensajes de error estandarizados
│ ├── eventos.rb ← Bus de eventos (pub/sub desacoplado)
│ ├── help_formatter.rb ← Formateador de ayuda estandarizado
│ ├── logger.rb ← Logger estructurado (JSON)
│ ├── nodos_info.rb ← Utilidades para extracción de metadatos de fichas
│ ├── 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/ ← 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) |
---
## Notas de Migración (MD-First → DB-First)
### 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
### 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
### 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**
### 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
Reference in New Issue View Git Blame Copy Permalink