[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
This commit is contained in:
Ricardo Monla
@@ -0,0 +1,105 @@
|
||||
# Documentación Técnica: ADN CLI
|
||||
|
||||
> Referencia para desarrolladores | Proyecto: dtic-DIIAA
|
||||
|
||||
## Punto de Entrada
|
||||
|
||||
```bash
|
||||
./adn/tools/run <subcomando> [opciones]
|
||||
```
|
||||
|
||||
## Estructura de Comandos
|
||||
|
||||
```
|
||||
adn/tools/
|
||||
├── run # Punto de entrada
|
||||
├── cli/ # Subcomandos (18 archivos)
|
||||
│ ├── db.rb # CRUD de base de datos
|
||||
│ ├── jornada.rb # Gestión de jornada
|
||||
│ ├── nodos.rb # Gestión de nodos
|
||||
│ └── ...
|
||||
├── core/ # Módulos reutilizables
|
||||
│ ├── constants.rb # Constantes globales
|
||||
│ ├── logger.rb # Logging estructurado
|
||||
│ ├── colores.rb # Colores ANSI
|
||||
│ ├── error_handler.rb # Helper de errores
|
||||
│ ├── help_formatter.rb # Ayuda estandarizada
|
||||
│ └── validador.rb # Validaciones
|
||||
└── spec/ # Tests
|
||||
```
|
||||
|
||||
## Constantes Principales
|
||||
|
||||
```ruby
|
||||
ADN::PROJECT_ROOT # Raíz del proyecto
|
||||
ADN::NODOS_DIR # Directorio de nodos
|
||||
ADN::BITACORAS_DIR # Directorio de bitácoras
|
||||
ADN::LOGS_DIR # Directorio de logs
|
||||
ADN::ESTADOS # Hash de estados (⏳✅❌⚠️⏸️📍)
|
||||
ADN::MODOS # Hash de modos (P/R)
|
||||
ADN::DB_CONFIG # Configuración de PostgreSQL
|
||||
```
|
||||
|
||||
## Excepciones Personalizadas
|
||||
|
||||
```ruby
|
||||
ADN::Error # Error base
|
||||
ADN::ConfigError # Error de configuración
|
||||
ADN::DBError # Error de base de datos
|
||||
ADN::ValidationError # Error de validación
|
||||
ADN::NetworkError # Error de red
|
||||
```
|
||||
|
||||
## Helpers Disponibles
|
||||
|
||||
### ADN::ErrorHandler
|
||||
```ruby
|
||||
ADN::ErrorHandler.error("mensaje") # Sale con código 1
|
||||
ADN::ErrorHandler.warning("mensaje") # Muestra warning
|
||||
ADN::ErrorHandler.info("mensaje") # Muestra info
|
||||
ADN::ErrorHandler.success("mensaje") # Muestra éxito
|
||||
```
|
||||
|
||||
### ADN::HelpFormatter
|
||||
```ruby
|
||||
ADN::HelpFormatter.generar_help(
|
||||
titulo: "Comando",
|
||||
descripcion: "Hace algo",
|
||||
uso: "Uso: comando [OPCIONES]",
|
||||
opciones: [{names: ["h"], desc: "Ayuda"}],
|
||||
ejemplos: [{cmd: "comando -h", desc: "Ejemplo"}]
|
||||
)
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
cd adn/tools
|
||||
bundle exec rspec spec/ --format documentation
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
Los logs se guardan en `logs/adn/YYYY-MM-DD.log` con formato JSON.
|
||||
|
||||
```ruby
|
||||
logger.info("mensaje", { clave: "valor" })
|
||||
logger.error("error", { detalle: "info" })
|
||||
```
|
||||
|
||||
### Rotación
|
||||
- Por tamaño: >10MB
|
||||
- Mantiene: 7 archivos
|
||||
|
||||
## Variables de Entorno
|
||||
|
||||
| Variable | Descripción |
|
||||
| :--- | :--- |
|
||||
| `ADN_DEBUG` | Activa logs de debug (1 o true) |
|
||||
| `TZ` | Zona horaria (default: America/Argentina/Buenos_Aires) |
|
||||
|
||||
## Próximos Pasos
|
||||
|
||||
- [ ] Usar HelpFormatter en todos los CLI
|
||||
- [ ] Migrar a ADN::ErrorHandler
|
||||
- [ ] Agregar más tests en spec/
|
||||
@@ -0,0 +1,124 @@
|
||||
# Documentación Técnica: Módulos Core ADN
|
||||
|
||||
> Referencia de módulos centrales | Proyecto: dtic-DIIAA
|
||||
|
||||
## core/constants.rb
|
||||
|
||||
Constantes globales del sistema.
|
||||
|
||||
```ruby
|
||||
# Rutas
|
||||
ADN::PROJECT_ROOT
|
||||
ADN::NODOS_DIR
|
||||
ADN::BITACORAS_DIR
|
||||
ADN::LOGS_DIR
|
||||
ADN::TOOLS_DIR
|
||||
ADN::SEGURIDAD_DIR
|
||||
|
||||
# Estados (iconos)
|
||||
ADN::ESTADOS = {
|
||||
pendiente: '⏳',
|
||||
completado: '✅',
|
||||
fallido: '❌',
|
||||
advertencia: '⚠️',
|
||||
pausado: '⏸️',
|
||||
en_proceso: '📍'
|
||||
}
|
||||
|
||||
# Modos de trabajo
|
||||
ADN::MODOS = {
|
||||
presencial: 'P',
|
||||
remoto: 'R'
|
||||
}
|
||||
|
||||
# DB
|
||||
ADN::DB_CONFIG = { host: 'localhost', puerto: 5433, ... }
|
||||
```
|
||||
|
||||
## core/logger.rb
|
||||
|
||||
Logging estructurado JSON.
|
||||
|
||||
```ruby
|
||||
logger = ADN::Logger.new(
|
||||
directorio: 'logs/adn',
|
||||
terminal: true,
|
||||
colores: true,
|
||||
nivel: 'INFO'
|
||||
)
|
||||
|
||||
logger.info("mensaje", { dato: "valor" })
|
||||
logger.error("error", { exception: e })
|
||||
```
|
||||
|
||||
### Métodos
|
||||
- `debug`, `info`, `exito`, `advertencia`, `error`
|
||||
- `buffer` - obtener logs en memoria
|
||||
- `limpiar_buffer`
|
||||
- `cerrar`
|
||||
|
||||
## core/colores.rb
|
||||
|
||||
Códigos ANSI para terminal.
|
||||
|
||||
```ruby
|
||||
Color::RESET
|
||||
Color::BOLD
|
||||
Color::GREEN
|
||||
Color::CYAN
|
||||
Color::YELLOW
|
||||
Color::RED
|
||||
Color::MAGENTA
|
||||
Color::DIM
|
||||
```
|
||||
|
||||
## core/error_handler.rb
|
||||
|
||||
Helper para mensajes estandarizados.
|
||||
|
||||
```ruby
|
||||
ADN::ErrorHandler.error("msg")
|
||||
ADN::ErrorHandler.warning("msg")
|
||||
ADN::ErrorHandler.info("msg")
|
||||
ADN::ErrorHandler.success("msg")
|
||||
ADN::ErrorHandler.debug("msg")
|
||||
```
|
||||
|
||||
## core/help_formatter.rb
|
||||
|
||||
Generador de ayuda estandarizado.
|
||||
|
||||
```ruby
|
||||
ADN::HelpFormatter.generar_help(
|
||||
titulo: "Comando",
|
||||
descripcion: "Hace algo",
|
||||
uso: "Uso: cmd [opciones]",
|
||||
opciones: [...],
|
||||
ejemplos: [...]
|
||||
)
|
||||
```
|
||||
|
||||
## core/validador.rb
|
||||
|
||||
Validador de cumplimiento ADN (para MD-First legacy).
|
||||
|
||||
⚠️ **DEPRECATED**: Usar validaciones en DB en su lugar.
|
||||
|
||||
## core/triggers.rb
|
||||
|
||||
Motor de triggers para propagación automática.
|
||||
|
||||
## core/eventos.rb
|
||||
|
||||
Bus de eventos (pub/sub).
|
||||
|
||||
## Dependencias
|
||||
|
||||
```
|
||||
adn/tools/
|
||||
├── core/
|
||||
│ ├── constants.rb (requiere colores)
|
||||
│ ├── logger.rb (requiere colores)
|
||||
│ ├── error_handler.rb
|
||||
│ └── help_formatter.rb (requiere colores)
|
||||
```
|
||||
@@ -0,0 +1,83 @@
|
||||
# Guía de Testing ADN
|
||||
|
||||
> Cómo escribir tests para el sistema ADN
|
||||
|
||||
## Estructura de Tests
|
||||
|
||||
```
|
||||
adn/tools/
|
||||
└── spec/
|
||||
├── spec_helper.rb
|
||||
├── db/
|
||||
│ └── evento_spec.rb
|
||||
└── core/
|
||||
├── colores_spec.rb
|
||||
└── validador_spec.rb
|
||||
```
|
||||
|
||||
## Ejecutar Tests
|
||||
|
||||
```bash
|
||||
cd adn/tools
|
||||
|
||||
# Todos los tests
|
||||
bundle exec rspec
|
||||
|
||||
# Un archivo específico
|
||||
bundle exec rspec spec/db/evento_spec.rb
|
||||
|
||||
# Con output detallado
|
||||
bundle exec rspec --format documentation
|
||||
```
|
||||
|
||||
## Escribir un Test
|
||||
|
||||
```ruby
|
||||
# spec/core/mi_modulo_spec.rb
|
||||
|
||||
require_relative '../spec_helper'
|
||||
$LOAD_PATH.unshift File.expand_path('../../core', __dir__)
|
||||
require 'mi_modulo'
|
||||
|
||||
describe 'ADN::MiModulo' do
|
||||
describe '.metodo' do
|
||||
it 'hace algo esperado' do
|
||||
expect(resultado).to eq(valor_esperado)
|
||||
end
|
||||
|
||||
it 'rechaza valor inválido' do
|
||||
expect { metodo(inválido) }.to raise_error(ADN::ValidationError)
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Buenos Patrones
|
||||
|
||||
1. **Un describe por clase/módulo**
|
||||
2. **Un it por comportamiento**
|
||||
3. **Tests independientes** (sin orden ni dependencias)
|
||||
4. **Nombres descriptivos**: `it 'valida formato HH:MM'`
|
||||
|
||||
## Helpers Disponibles
|
||||
|
||||
- `expect(...).to eq(valor)`
|
||||
- `expect(...).to match(/regex/)`
|
||||
- `expect(...).to be true/false`
|
||||
- `expect { }.to raise_error(Error)`
|
||||
|
||||
## Cobertura
|
||||
|
||||
| Módulo | Tests |
|
||||
| :--- | :--- |
|
||||
| db/evento | 3 |
|
||||
| core/colores | 6 |
|
||||
| core/validador | 6 |
|
||||
| **Total** | **15** |
|
||||
|
||||
## Próximos Tests
|
||||
|
||||
- [ ] spec/core/error_handler_spec.rb
|
||||
- [ ] spec/core/help_formatter_spec.rb
|
||||
- [ ] spec/cli/db_spec.rb
|
||||
- [ ] spec/cli/jornada_spec.rb
|
||||
Reference in New Issue
Block a user