rmonla/dtic-DIIAA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[ADN] Actualización completa a filosofía DB-First - Clarificación Ruby como lenguaje y registro en bitácora web

Browse Source
This commit is contained in:
Ricardo Monla
2026-03-12 05:57:34 -03:00
parent 28803f3b24
commit 4b000aeb89
1 changed files with 167 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
adn/README.md
+167 -79
View File
@@ -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 <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
@@ -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 <subcomando> [opciones]`
### Subcomandos Disponibles
### Subcomandos Disponibles (DB-First)
| 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 |
| 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 |
| `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 <ID> --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 <ID> --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 <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. **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 <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/
```
@@ -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 <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.
### 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