[ADN] Actualización completa a filosofía DB-First - Clarificación Ruby como lenguaje y registro en bitácora web
This commit is contained in:
Ricardo Monla
+167
-79
@@ -10,11 +10,74 @@
|
|||||||
| **Nombre** | dtic-DIIAA (Departamento de Investigación de IA y Automatización) |
|
| **Nombre** | dtic-DIIAA (Departamento de Investigación de IA y Automatización) |
|
||||||
| **Repositorio** | `/home/rmonla/Documentos/GitHub/dtic-DIIAA` |
|
| **Repositorio** | `/home/rmonla/Documentos/GitHub/dtic-DIIAA` |
|
||||||
| **Idioma** | Español (TODO: docs, commits, comentarios, interacciones) |
|
| **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) |
|
| **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
|
## Principios Rectores del ADN
|
||||||
|
|
||||||
### Tríptico Rector
|
### 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`
|
## Herramienta CLI: `adn/tools/run`
|
||||||
|
|
||||||
> **REGLA**: Antes de crear scripts temporales o ejecutar SQL directo,
|
> **REGLA DB-FIRST**: Antes de crear scripts temporales o ejecutar SQL directo,
|
||||||
> busca si ya existe un subcomando que haga lo que necesitas.
|
> busca si ya existe un subcomando `db` que haga lo que necesitas.
|
||||||
|
|
||||||
**Punto de entrada**: `./adn/tools/run <subcomando> [opciones]`
|
**Punto de entrada**: `./adn/tools/run <subcomando> [opciones]`
|
||||||
|
|
||||||
### Subcomandos Disponibles
|
### Subcomandos Disponibles (DB-First)
|
||||||
|
|
||||||
| Subcomando | Descripción |
|
| Subcomando | Descripción | Filosofía |
|
||||||
| :------------------------------------ | :----------------------------------------------- |
|
| :------------------------------------ | :----------------------------------------------- | :------------------ |
|
||||||
| `validador [--watch] [--fix]` | Validar cumplimiento del ADN en bitácoras |
|
| `db <subcomando>` | **Operaciones DB-First** (fuente de verdad) | PostgreSQL Primario |
|
||||||
| `contexto <nodo> [--cmd]` | Obtener contexto topológico y SSH de un nodo |
|
| `jornada iniciar [modo] [HH:MM]` | Registrar inicio de jornada laboral en DB | DB-First |
|
||||||
| `nodos agrupar [--servidor SRV]` | Agrupar VMs por servidor anfitrión |
|
| `jornada cerrar [modo] [HH:MM]` | Registrar cierre de jornada laboral en DB | DB-First |
|
||||||
| `nodos listar [--tipo TIPO]` | Listar fichas de nodos (.md) |
|
| `jornada estado` | Ver estado de la jornada actual desde DB | DB-First |
|
||||||
| `nodos buscar <término>` | Buscar nodos por nombre o contenido |
|
| `contexto <nodo> [--cmd]` | Obtener contexto topológico y SSH de un nodo | Consulta DB |
|
||||||
| `jornada iniciar [modo] [HH:MM]` | Registrar inicio de jornada laboral |
|
| `nodos agrupar [--servidor SRV]` | Agrupar VMs por servidor anfitrión | Consulta DB |
|
||||||
| `jornada cerrar [modo] [HH:MM]` | Registrar cierre de jornada laboral |
|
| `nodos listar [--tipo TIPO]` | Listar nodos desde base de datos | DB-First |
|
||||||
| `jornada estado` | Ver estado de la jornada actual |
|
| `nodos buscar <término>` | Buscar nodos en base de datos | DB-First |
|
||||||
| `salud [--dashboard] [--json]` | Ver salud general del sistema ADN |
|
| `salud [--dashboard] [--json]` | Ver salud general del sistema ADN | Incluye DB |
|
||||||
| `generar bitacora [fecha]` | Generar nueva bitácora (YYYY-MM-DD, default: hoy) |
|
| `backup <nodo> [--mode MODO]` | Ejecutar backup seguro de un nodo | Registra en DB |
|
||||||
| `generar nodo <nombre>` | Generar ficha de nodo |
|
| `triggers [--listar/--registrar]` | Gestión del motor de triggers | Sincroniza DB |
|
||||||
| `generar proyecto <código>` | Generar manifiesto de proyecto |
|
| `plan [subcomando]` | Gestión de planes y progreso de proyectos | DB-First |
|
||||||
| `conocimiento asimilar <archivo>` | Asimilar documentación al ADN |
|
| `estados` | Listar tareas en proceso (⏳) desde DB | DB-First |
|
||||||
| `backup <nodo> [--mode MODO]` | Ejecutar backup seguro de un nodo |
|
| `proceso <nombre>` | Ejecutar procesos técnicos automatizados | Registra en DB |
|
||||||
| `triggers [--listar/--registrar]` | Gestión del motor de triggers |
|
| `generar bitacora [fecha]` | Generar nueva bitácora en DB (YYYY-MM-DD) | DB-First |
|
||||||
| `plan [subcomando]` | Gestión de planes y progreso de proyectos |
|
| `generar nodo <nombre>` | Generar ficha de nodo en DB | DB-First |
|
||||||
| `ayuda [subcomando]` | Mostrar ayuda detallada |
|
| `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 |
|
| Subcomando | Descripción | Filosofía |
|
||||||
| :------------------------ | :--------------------------------------------- |
|
| :------------------------ | :--------------------------------------------- | :------------------ |
|
||||||
| `db salud:bd` | Verificar conexión y estado de PostgreSQL |
|
| `db salud:bd` | Verificar conexión y estado de PostgreSQL | DB-First |
|
||||||
| `db bitacora:crear` | Crear nueva bitácora diaria en DB |
|
| `db bitacora:crear` | Crear nueva bitácora diaria en DB | DB-First |
|
||||||
| `db bitacora:listar` | Listar bitácoras existentes |
|
| `db bitacora:listar` | Listar bitácoras existentes desde DB | DB-First |
|
||||||
| `db evento:crear` | Crear nueva entrada cronológica (I-F-D-E) |
|
| `db evento:crear` | Crear nueva entrada cronológica (I-F-D-E) | DB-First |
|
||||||
| `db evento:listar` | Listar entradas con filtros (nodo, estado, fecha)|
|
| `db evento:listar` | Listar entradas con filtros desde DB | DB-First |
|
||||||
| `db evento:actualizar` | Actualizar una entrada existente |
|
| `db evento:actualizar` | Actualizar una entrada existente en DB | DB-First |
|
||||||
| `db evento:eliminar` | Eliminar una entrada existente por ID |
|
| `db evento:eliminar` | Eliminar una entrada existente por ID de DB | DB-First |
|
||||||
| `db nodo:crear` | Crear nuevo nodo (servidor/VM/PC/servicio) |
|
| `db nodo:crear` | Crear nuevo nodo en DB | DB-First |
|
||||||
| `db nodo:listar` | Listar nodos del sistema |
|
| `db nodo:listar` | Listar nodos desde DB | DB-First |
|
||||||
| `db estadisticas` | Mostrar estadísticas del sistema |
|
| `db estadisticas` | Mostrar estadísticas del sistema desde DB | DB-First |
|
||||||
| `db archivar:md` | Mover archivos .md migrados al archivo histórico|
|
| `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
|
```bash
|
||||||
# Inicio de jornada presencial a las 08:00
|
# 1. INICIO DE JORNADA (registra en DB)
|
||||||
./adn/tools/run jornada iniciar presencial 08:00
|
./adn/tools/run jornada iniciar presencial 08:00
|
||||||
|
|
||||||
# Cierre de jornada remota a las 23:00
|
# 2. REGISTRAR ACTIVIDAD DE DESARROLLO RUBY (DB-First)
|
||||||
./adn/tools/run jornada cerrar remoto 23:00
|
./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
|
# 3. LISTAR ACTIVIDADES DEL DÍA (consulta DB)
|
||||||
./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)
|
./adn/tools/run db evento:listar --desde $(date +%Y-%m-%d)
|
||||||
|
|
||||||
# Exportar bitácora a Markdown
|
# 4. ACTUALIZAR ENTRADA AL FINALIZAR (DB-First)
|
||||||
ruby -I adn/tools/db -e 'require "core/bitacora_db"; require "exporters/md_exporter";
|
./adn/tools/run db evento:actualizar <ID> --fin 12:30 --estado completado
|
||||||
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
|
# 5. CERRAR JORNADA (registra en DB)
|
||||||
./adn/tools/run nodos agrupar
|
./adn/tools/run jornada cerrar remoto 18:00
|
||||||
|
|
||||||
# Filtrar VMs de un servidor específico
|
# 6. VER ESTADO ACTUAL (desde DB)
|
||||||
./adn/tools/run nodos agrupar --servidor srv-pmox1
|
./adn/tools/run jornada estado
|
||||||
|
|
||||||
# Listar solo VMs de servicio
|
# 7. LISTAR NODOS DESDE BASE DE DATOS
|
||||||
./adn/tools/run nodos listar --tipo srvv
|
./adn/tools/run db nodo:listar --tipo srvv
|
||||||
|
|
||||||
# Buscar nodos relacionados con dasuten
|
# 8. BUSCAR NODOS EN DB
|
||||||
./adn/tools/run nodos buscar dasuten
|
./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
|
./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/
|
## 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.
|
### Componentes Obsoletos (MD-First)
|
||||||
NO crees scripts temporales en `/tmp/` ni ejecutes SQL directo si existe un subcomando.
|
- **`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
|
### Flujo de Migración Completo
|
||||||
entradas. Los archivos `.md` se generan mediante exportación (`md_exporter.rb`).
|
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`.
|
### Buenas Prácticas Actuales
|
||||||
|
1. **Siempre comenzar con `db evento:crear`** antes de cualquier trabajo
|
||||||
5. **Auto-Registro**: Toda acción autónoma de la IA DEBE registrarse como entrada
|
2. **Usar `db evento:actualizar`** al finalizar para registrar métricas
|
||||||
en la bitácora del día usando `db evento:crear`.
|
3. **Consultar `db evento:listar`** para ver estado actual
|
||||||
|
4. **Verificar en `http://localhost:5174`** para confirmar cambios
|
||||||
6. **Topología primero**: Antes de conectarte a un nodo, consulta `./adn/tools/run contexto <nodo>`
|
5. **Usar `jornada iniciar/cerrar`** para gestión de tiempo de trabajo
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user