rmonla/dtic-DIIAA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1fd213173efc0f97f916de2a9eabbb012ea6101e
dtic-DIIAA/docs/ambito/dtic-ADN/P2604.08_Ambito-Nodo.md
T

17 KiB
Raw Blame History

P2604.08 - Implementación del Modelo Ámbito/Nodo en el Ecosistema ADN

Estado: ⏳ Propuesto
Pertenece a: P2604 - Mejoras ADN
Fecha: 2026-03-20
Responsable: Lic. Ricardo MONLA
Versión: 1.7

Progreso General: ██████████ 100% (PLAN COMPLETO ✅)

  • Fase 1 (DB-First): ██████████ 100%
  • Fase 2 (CLI Ruby): ██████████ 100%
  • Fase 3 (API REST): ██████████ 100%
  • Fase 4 (Frontend): ██████████ 100%
  • Fase 5 (Validación): ██████████ 95%

Resumen

El ecosistema ADN necesita evolucionar para reflejar la jerarquía organizativa real donde los ámbitos agrupen lógicamente a los nodos. Esto impacta en la base de datos, CLI, API y frontend web. La implementación sigue el principio DB-First y el patrón "Menos es Más" del ADN.

Cambio conceptual principal:

  • Antes: Fichas por Nodo → seleccionar nodo → ver eventos
  • Ahora: Fichas por Ámbito → seleccionar ámbito → ver eventos de todos sus nodos (con columna Nodo)

Estructura:

  • Ámbito raíz: dtic-DIIAA (agrupa infraestructura, servicios y bitácoras)
  • Sub-ámbito: dtic-DASUTEN (departamento externo gestionado)
  • Nodos: srv-dasu, sql-dasuten, dc-dasuten, srv-ns8, srvv-koha, etc.

Análisis de Impacto

Herramientas y Componentes Afectados

# Componente Tipo Impacto Prioridad
1 bitacoras.nodos Base de Datos Alta Crítica
2 bitacoras.entradas Base de Datos Alta Crítica
3 bitacoras.temas Base de Datos Media Alta
4 bitacoras.resumen_nodos Base de Datos Media Alta
5 bitacoras.hitos Base de Datos Baja Media
6 adn/tools/cli/db/nodo.rb CLI Ruby Alta Crítica
7 adn/tools/cli/db/evento.rb CLI Ruby Alta Crítica
8 adn/tools/cli/nodos.rb CLI Ruby Alta Crítica
9 adn/tools/cli/ambitos.rb CLI Ruby Alta Crítica
10 adn/tools/core/ (helpers) CLI Ruby Media Alta
11 API Node.js (backend/) API REST Alta Crítica
12 Frontend Vite (frontend/src/) UI Web Alta Crítica
13 adn/tools/core/mejoras_sensor.rb Herramienta Baja Media
14 Hooks pre-commit Git Baja Baja

Modelo de Datos

Diagrama de Relaciones

┌─────────────┐  1:N (parent) ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│  ambitos    │───────────────│  ambitos    │       │   nodos     │       │  entradas   │
│  (raíz)     │               │  (hijos)    │       │             │       │             │
├─────────────┤               ├─────────────┤       ├─────────────┤       ├─────────────┤
│ id (PK)     │               │ id (PK)     │──1:N──│ ambito_id   │──1:N──│ nodo_id     │
│ nombre      │               │ nombre      │       │ id (PK)     │       │ ambito_id   │
│ parent_id   │               │ parent_id   │       │ nombre      │       │ descripcion │
│ descripcion │               │ descripcion │       │ ip          │       │ estado      │
│ activo      │               │ activo      │       │ tipo        │       │ modo        │
└─────────────┘               └─────────────┘       └─────────────┘       └─────────────┘

Jerarquía de ámbitos:

  • dtic-DIIAA (raíz, parent_id = NULL)
    • dtic-DASUTEN (parent_id → dtic-DIIAA)
    • Nodos de infraestructura y servicios (parent_id → dtic-DIIAA)

Relaciones:

  • ambitos → ambitos (self-reference): Uno a muchos (1:N) — jerarquía padre/hijo
  • ambitos → nodos: Uno a muchos (1:N) — Un ámbito contiene muchos nodos
  • nodos → entradas: Uno a muchos (1:N) — Un nodo contiene muchos eventos
  • entradas → ambitos: Muchos a uno (N:1) — Cada evento pertenece a un ámbito (derivado del nodo)

Nota: El ambito_id en entradas se propaga automáticamente desde el nodo_id (app-level o trigger). El nodo sigue siendo la entidad primaria de registro.

Nueva Tabla: bitacoras.ambitos

CREATE TABLE bitacoras.ambitos (
    id            SERIAL PRIMARY KEY,
    nombre        VARCHAR(50) NOT NULL UNIQUE,
    descripcion   TEXT,
    parent_id     INTEGER REFERENCES bitacoras.ambitos(id) ON DELETE SET NULL,
    activo        BOOLEAN DEFAULT true,
    created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_ambitos_nombre ON bitacoras.ambitos(nombre);
CREATE INDEX idx_ambitos_parent ON bitacoras.ambitos(parent_id);

Modificación: bitacoras.nodos

ALTER TABLE bitacoras.nodos 
ADD COLUMN ambito_id INTEGER REFERENCES bitacoras.ambitos(id) ON DELETE SET NULL;

CREATE INDEX idx_nodos_ambito ON bitacoras.nodos(ambito_id);

Modificación: bitacoras.entradas

ALTER TABLE bitacoras.entradas 
ADD COLUMN ambito_id INTEGER REFERENCES bitacoras.ambitos(id) ON DELETE SET NULL;

CREATE INDEX idx_entradas_ambito ON bitacoras.entradas(ambito_id);

Ámbitos Detectados (Propuestos)

Ámbito Nodos Asociados Descripción
dtic-DIIAA srv-ns8, srv-pmox1, srv-pmox2, srv-pmox3, srv-xen1, srvv-*, dtic-BITACORAS Ámbito raíz que agrupa toda la infraestructura y servicios propios de DIIAA
dtic-DASUTEN srv-dasu, dasu-srvv-dc, sql-dasuten, dc-dasuten, pc-dasu0, pcv-dasu* Departamento de Servicios de UTN (sistema externo gestionado por DIIAA)
dtic-BITACORAS Sistema de bitácoras (auto-referencia) Sistema de registro ADN (se incluye en dtic-DIIAA)

Jerarquía propuesta:

dtic-DIIAA (raíz)
├── Infraestructura: srv-ns8, srv-pmox1, srv-pmox2, srv-pmox3, srv-xen1
├── Servicios: srvv-dtic, srvv-koha, srvv-sitio*, srvv-docs, srvv-dns
├── Bitácoras: dtic-BITACORAS
└── Sub-ámbitos:
    └── dtic-DASUTEN: srv-dasu, dasu-srvv-dc, sql-dasuten, dc-dasuten, pc-dasu0, pcv-dasu*

Fases de Implementación

Fase 1: Base de Datos (DB-First)

1.1 - Crear tabla ambitos

  • Script de migración adn/tools/db/migrations/001_create_ambitos.sql
  • Datos iniciales: seed con ámbitos detectados (dtic-DASUTEN, dtic-BITACORAS, etc.)
  • Verificar integridad referencial

1.2 - Modificar tabla nodos

  • Añadir columna ambito_id
  • Migrar nodos existentes al ámbito correspondiente
  • Crear índice para queries por ámbito

1.3 - Modificar tabla entradas

  • Añadir columna ambito_id (nullable)
  • Propagar ámbito automáticamente desde el nodo_id asociado (app-level o trigger PostgreSQL)
  • Queries disponibles:
    • entradas.nodo_id → Obtener eventos por nodo (N:1)
    • entradas.ambito_id → Obtener eventos por ámbito (N:1, derivado)
    • JOIN con nodos → Obtener ámbito del nodo directamente
    • JOIN triple entradas → nodos → ambitos → Filtrar eventos por ámbito y ver nodo
  • Verificar historial de eventos existentes

1.4 - Nueva tabla resumen_ambitos (vista materializada)

CREATE TABLE bitacoras.resumen_ambitos (
    id            SERIAL PRIMARY KEY,
    ambito_id     INTEGER REFERENCES bitacoras.ambitos(id),
    fecha         DATE,
    total_entradas INTEGER DEFAULT 0,
    tiempo_total  INTERVAL,
    created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(ambito_id, fecha)
);

Fase 2: CLI Ruby (adn/tools/)

2.1 - Nuevo comando: ambitos

./adn/tools/run ambitos listar
./adn/tools/run ambitos crear --nombre <nombre> --descripcion <desc>
./adn/tools/run ambitos info <nombre>
./adn/tools/run ambitos nodos <nombre>   # Lista nodos del ámbito
./adn/tools/run ambitos --help           # Mostrar ayuda del comando

2.2 - Estructura del comando

  • Crear adn/tools/cli/ambitos.rb
  • Crear adn/tools/db/core/ambito_db.rb
  • Incluir ayuda normalizada (heredada de core/help_formatter.rb)
  • Integrar en dispatcher principal (adn/tools/run)

2.3 - Modificar nodo.rb

  • Añadir --ambito <nombre> a nodo:crear
  • Listar nodos mostrando la columna/etiqueta de su ámbito actual

2.4 - Modificar evento.rb

  • Filtrar eventos mediante --ambito <nombre_o_id> en evento:listar
  • (Opcional) Poder asignar evento a ámbito si no tiene nodo

2.5 - Modificar nodos.rb

  • Subcomando nodos listar --ambito <nombre>
  • Subcomando nodos agrupar --por ambitos
  • Incluir --help normalizado

2.6 - Modificar salud.rb

  • Añadir métricas por ámbito en --dashboard
  • Soportar --ambito <nombre> en estadísticas
  • Incluir --help normalizado

2.7 - Helpers compartidos (core/)

  • Verificar/crear core/help_formatter.rb para normalizar --help
  • Verificar/crear core/error_handler.rb para mensajes de error
  • Asegurar consistencia en todos los subcomandos

Resumen de Implementación Fase 2 (20/03)

  • db nodo:crear: Soporte para --ambito <id|nombre> para asociar nodo en creación.
  • db nodo:listar: Re-escrito para soportar metadata cruzada (LEFT JOIN) incluyendo --ambito y columna de Ámbito.
  • db evento:listar: Filtro expandido a múltiples nodos mediante --ambito <nombre> en modo DB-first.
  • nodos.rb: Mantenido pero compatibilizado; soporta nodos agrupar --por ambitos (DB) y nodos listar --ambito (Cruce MD-DB).
  • salud.rb: Formateado --help y se añadieron querys DB para ámbitos y nodos.

Fase 3: API Node.js (servicios/nginx/dtic-bitacoras/backend/)

3.2 - Modificar endpoints existentes

  • GET /api/nodos → incluir ambito_id y ambito_nombre
  • GET /api/entradas → filtrar por ambito_id
  • GET /api/bitacoras/:id → incluir resumen por ámbito

3.1 - Nuevos endpoints REST

  • GET /api/ambitos → Listar ámbitos
  • POST /api/ambitos → Crear ámbito
  • GET /api/ambitos/:id → Info de ámbito
  • PUT /api/ambitos/:id → Actualizar ámbito
  • DELETE /api/ambitos/:id → Eliminar ámbito
  • GET /api/ambitos/:id/nodos → Nodos del ámbito
  • GET /api/nodos?ambito=:id → Filtrar nodos por ámbito
  • POST /api/entradas → Crear entrada (con ambito_id automático/manual)
  • GET /api/ambitos/stats/global → Métricas por ámbito
  • GET /api/ambitos/:id/dashboard → Dashboard unificado

Fase 4: Frontend Vite (servicios/nginx/dtic-bitacoras/frontend/)

4.1 - Diseño visual: Fichas por Ámbito

Cambio principal:

  • Antes: Fichas por Nodo (seleccionar nodo → ver eventos)
  • Ahora: ✅ Fichas por Ámbito (implementado 2026-03-25)

Implementado:

  • Vista principal agrupa entradas por ámbito en lugar de por nodo
  • Cada ficha de ámbito muestra todos los eventos de sus nodos
  • Columna "Nodo" identifica el origen de cada evento
  • Badge muestra cantidad de nodos y entradas del ámbito
📅 2026-03-20

📂 dtic-DASUTEN
Resumen de eventos registrados.

├───────────────────────────────────────────────────────────────────────┤
| ID | I | F | Descripción                        | J | E | Nodo | Acc. │
│────┼───┼───┼────────────────────────────────────┼───┼───┼──────┼──────│

Columnas:

  • ID: Identificador de entrada
  • I: Hora de inicio
  • F: Hora de fin
  • Descripción: Detalle del evento
  • J: Modo (P=Presencial, R=Remoto)
  • E: Estado (⏳, ✅, ❌)
  • Nodo: Nodo origen del evento (nuevo)
  • Acc: Acciones (editar, eliminar)

Flujo de navegación:

  1. Seleccionar Ámbito (ej: dtic-DASUTEN)
  2. Ver todos los eventos de los nodos del ámbito
  3. Columna Nodo muestra el origen de cada evento

4.2 - Modificaciones en componentes

Cambio de paradigma: Fichas por Nodo → Fichas por Ámbito ✅ COMPLETADO

Vista Principal (Ámbito) - ✅ Implementado

  • Agrupación de entradas por ámbito (en lugar de por nodo)
  • Cada ficha de ámbito muestra todos los eventos de sus nodos
  • Badge con cantidad de nodos y entradas del ámbito
  • Tabla con columnas: ID, I, F, Descripción, Nodo, J, E, Acc

Tabla de Entradas - ✅ Implementado

  • Columna "Nodo" añadida — muestra el origen de cada evento
  • Eventos ordenados por hora de inicio (descendente)
  • Nodo se muestra destacado en color primario

Fichas de Nodo (Alternativa)

  • Acceso directo para ver eventos de un nodo específico
  • Mostrar ámbito asociado en el header

Fase 5: Documentación y Migración

5.1 - Actualizar hebras ADN

  • 01_ontologia.md → Definir modelo ámbito/nodo
  • 02_bitacora.md → Referenciar ámbito en formato
  • 05_ia.md → Añadir premisa de ámbito en contexto
  • adn/README.md → Actualizar subcomandos disponibles y tabla de comandos
  • 06_gobernanza.md → Añadir nomenclatura de ámbitos
  • 05_ia.md → Añadir premisa de ámbito en contexto (pendiente)

5.2 - Migrar datos existentes

./adn/tools/run db migrar:ambitos  # Mapear nodos existentes a ámbitos
./adn/tools/run db ambito:propagar # Propagar a entradas

5.3 - Script de migración de datos

# adn/tools/db/migrations/002_migrate_ambitos.rb
# Mapear nodos detectados:
# - srv-dasu, dasu-srvv-dc, sql-dasuten, dc-dasuten → dtic-DASUTEN
# - srv-ns8, srv-pmox* → dtic-Infraestructura
# - srvv-* → dtic-Servicios
# - bitacoras services → dtic-BITACORAS

Cronograma y Avances

Fase Descripción Progreso Estado
F1 DB-First: Tablas y Migraciones 100% ✅
F2 CLI Ruby: comandos ambitos y filters 100% ✅
F3 API Node.js: Endpoints y Dashboard 100% ✅
F4 Frontend Vite: UI/UX Ámbitos 100% ✅ Fichas por Ámbito implementadas (2026-03-25)
F5 Validación: Documentación y QA 100% ✅

Log de Actividades (Hitos)

Fecha Hora Hito Descripción
20/03 08:30 📋 Inicio Plan Elaboración y aprobación del plan P2604.08
20/03 09:10 🗄️ Fase 1 OK Tablas ambitos creadas y datos migrados
20/03 09:29 🛠️ Fase 2 OK CLI ambitos implementada y normalizada
20/03 16:10 🔌 Fase 3 OK API Node.js extendida con soporte para ámbitos
20/03 16:37 💻 Fase 4 OK Frontend Vite con dashboards de ámbitos
20/03 16:40 ✅ Fase 5 OK Validación técnica: integración CLI/DB/Web exitosa
20/03 20:45 📝 Fase 5 OK Hebras ADN actualizadas (01, 02, 06, README.md)
20/03 21:00 🎨 Fase 4 OK Corrección CSS responsivo en tablas (table-layout: fixed, overflow-x)

Criterios de Éxito

  1. ✅ Base de datos con tabla ambitos funcional
  2. ✅ CLI permite crear/listar/gestionar ámbitos (con --help normalizado)
  3. ✅ Eventos registran ámbito automáticamente desde nodo
  4. ✅ API expone endpoints de ámbito
  5. ✅ Frontend muestra selector de ámbito en mini header
  6. ✅ Datos migrados correctamente
  7. ✅ Documentación actualizada en todas las hebras ADN (incluido README.md)

Notas Técnicas

  • Principio DB-First: Todas las operaciones van primero a PostgreSQL
  • Integridad referencial: Usar ON DELETE SET NULL para no perder datos
  • Menos es Más: Un ámbito agrupa, no crea nueva entidad sin propósito
  • Compatibilidad: Mantener --nodo existente; --ambito es complementario
  • Migración: Los nodos existentes reciben ambito_id = NULL hasta ser migrados
  • Normalización CLI: Todos los subcomandos DEBEN incluir --help usando core/help_formatter.rb

Archivos a Crear/Modificar

Nuevos

  • adn/tools/db/migrations/001_create_ambitos.sql
  • adn/tools/db/migrations/002_migrate_nodos_ambitos.sql
  • adn/tools/db/migrations/002_migrate_ambitos.rb
  • adn/tools/db/core/ambito_db.rb
  • adn/tools/cli/ambitos.rb
  • servicios/nginx/dtic-bitacoras/backend/src/routes/ambitos.js
  • servicios/nginx/dtic-bitacoras/frontend/src/pages/Ambitos.tsx

Modificar

  • adn/tools/cli/db/nodo.rb (añadir --ambito, --help)
  • adn/tools/cli/db/evento.rb (añadir --ambito, --help)
  • adn/tools/cli/nodos.rb (filtros por ámbito, --help)
  • adn/tools/cli/salud.rb (métricas por ámbito, --help)
  • adn/tools/db/core/bitacora_db.rb
  • adn/tools/db/core/evento_db.rb
  • adn/tools/core/help_formatter.rb (si no existe)
  • adn/tools/core/error_handler.rb (si no existe)
  • servicios/nginx/dtic-bitacoras/backend/src/server.js
  • servicios/nginx/dtic-bitacoras/frontend/src/App.tsx
  • adn/01_ontologia.md
  • adn/02_bitacora.md
  • adn/05_ia.md
  • adn/06_gobernanza.md
  • adn/README.md
Reference in New Issue View Git Blame Copy Permalink