66161b1566
Sistema NEXUS v3.4 migrado con: Estructura principal: - core/orchestration: Sistema SIMCO + CAPVED (27 directivas, 28 perfiles) - core/catalog: Catalogo de funcionalidades reutilizables - shared/knowledge-base: Base de conocimiento compartida - devtools/scripts: Herramientas de desarrollo - control-plane/registries: Control de servicios y CI/CD - orchestration/: Configuracion de orquestacion de agentes Proyectos incluidos (11): - gamilit (submodule -> GitHub) - trading-platform (OrbiquanTIA) - erp-suite con 5 verticales: - erp-core, construccion, vidrio-templado - mecanicas-diesel, retail, clinicas - betting-analytics - inmobiliaria-analytics - platform_marketing_content - pos-micro, erp-basico Configuracion: - .gitignore completo para Node.js/Python/Docker - gamilit como submodule (git@github.com:rckrdmrd/gamilit-workspace.git) - Sistema de puertos estandarizado (3005-3199) Generated with NEXUS v3.4 Migration System EPIC-010: Configuracion Git y Repositorios
334 lines
8.3 KiB
Markdown
334 lines
8.3 KiB
Markdown
# Guia de Uso: Sistema de Propagacion de Mejoras
|
|
|
|
**Version:** 1.0.0
|
|
**Sistema:** NEXUS v3.4
|
|
**Directiva:** @PROPAGACION
|
|
**Fecha:** 2026-01-04
|
|
|
|
---
|
|
|
|
## Quick Start (5 pasos)
|
|
|
|
```bash
|
|
# 1. Verificar estado actual de modulos
|
|
./devtools/scripts/propagation/check-module-versions.sh
|
|
|
|
# 2. Ver dashboard visual
|
|
./devtools/scripts/propagation/generate-propagation-report.sh
|
|
|
|
# 3. Iniciar propagacion de una mejora
|
|
./devtools/scripts/propagation/propagate-module-update.sh <modulo> <version> <origen>
|
|
|
|
# 4. Completar tareas generadas por proyecto
|
|
|
|
# 5. Actualizar TRAZABILIDAD-PROYECTOS.yml
|
|
```
|
|
|
|
---
|
|
|
|
## Que es el Sistema de Propagacion?
|
|
|
|
El sistema de propagacion permite que cuando mejoras un modulo compartido en un proyecto, esa mejora se propague automaticamente a todos los proyectos que usan ese modulo.
|
|
|
|
### Flujo basico
|
|
|
|
```
|
|
Tu mejora en Proyecto A
|
|
|
|
|
v
|
|
Se registra en Knowledge-Base
|
|
|
|
|
v
|
|
Se identifican proyectos B, C, D que usan el modulo
|
|
|
|
|
v
|
|
Se crean tareas de propagacion
|
|
|
|
|
v
|
|
Se propaga a cada proyecto
|
|
|
|
|
v
|
|
Se actualiza trazabilidad
|
|
```
|
|
|
|
---
|
|
|
|
## Cuando Usar Este Sistema
|
|
|
|
### Usar propagacion cuando:
|
|
|
|
- Corriges un **bug** en un modulo compartido
|
|
- Aplicas un **fix de seguridad**
|
|
- Agregas una **feature generica** que beneficia a otros
|
|
- Mejoras el **performance** de un modulo
|
|
|
|
### NO usar propagacion cuando:
|
|
|
|
- El cambio es **especifico** de reglas de negocio de tu proyecto
|
|
- El cambio es puramente **estetico** o de estilo personal
|
|
- El modulo **no existe** en el knowledge-base
|
|
|
|
---
|
|
|
|
## Comandos Disponibles
|
|
|
|
### 1. propagate-module-update.sh
|
|
|
|
Inicia el proceso de propagacion.
|
|
|
|
```bash
|
|
# Uso basico
|
|
./devtools/scripts/propagation/propagate-module-update.sh <modulo> <version> <origen>
|
|
|
|
# Ejemplo: Propagar mejora de auth-jwt-nestjs desde gamilit
|
|
./devtools/scripts/propagation/propagate-module-update.sh auth-jwt-nestjs 2.2.0 gamilit
|
|
|
|
# Simular sin hacer cambios
|
|
./devtools/scripts/propagation/propagate-module-update.sh auth-jwt-nestjs 2.2.0 gamilit --dry-run
|
|
|
|
# Actualizar registro automaticamente
|
|
./devtools/scripts/propagation/propagate-module-update.sh auth-jwt-nestjs 2.2.0 gamilit --update-registry
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
==========================================
|
|
PROPAGATE MODULE UPDATE
|
|
Sistema: NEXUS v3.4
|
|
==========================================
|
|
|
|
[OK] Modulo 'auth-jwt-nestjs' encontrado en catalogo
|
|
[OK] Proyecto origen 'gamilit' verificado
|
|
|
|
============================================
|
|
PROPAGACION DE MEJORAS
|
|
============================================
|
|
|
|
Modulo: auth-jwt-nestjs
|
|
Version nueva: 2.2.0
|
|
Proyecto origen: gamilit
|
|
|
|
Proyectos a propagar:
|
|
- erp-core (tiene v2.1.0)
|
|
- trading-platform (tiene v2.1.0)
|
|
```
|
|
|
|
### 2. check-module-versions.sh
|
|
|
|
Detecta modulos desactualizados.
|
|
|
|
```bash
|
|
# Verificar todos los modulos
|
|
./devtools/scripts/propagation/check-module-versions.sh
|
|
|
|
# Verificar un modulo especifico
|
|
./devtools/scripts/propagation/check-module-versions.sh --modulo auth-jwt-nestjs
|
|
|
|
# Verificar un proyecto especifico
|
|
./devtools/scripts/propagation/check-module-versions.sh --proyecto gamilit
|
|
|
|
# Modo verbose (mostrar todo, no solo desactualizados)
|
|
./devtools/scripts/propagation/check-module-versions.sh --verbose
|
|
```
|
|
|
|
**Exit codes:**
|
|
- `0` = Todos los proyectos al dia
|
|
- `1` = Hay desactualizaciones
|
|
- `2` = Error de configuracion
|
|
|
|
### 3. generate-propagation-report.sh
|
|
|
|
Genera dashboard visual.
|
|
|
|
```bash
|
|
# Dashboard en terminal
|
|
./devtools/scripts/propagation/generate-propagation-report.sh
|
|
|
|
# Sin colores (para logs)
|
|
./devtools/scripts/propagation/generate-propagation-report.sh --no-color
|
|
|
|
# Formato Markdown
|
|
./devtools/scripts/propagation/generate-propagation-report.sh --markdown
|
|
|
|
# Guardar a archivo
|
|
./devtools/scripts/propagation/generate-propagation-report.sh --output estado.md --markdown
|
|
```
|
|
|
|
---
|
|
|
|
## Proceso Paso a Paso
|
|
|
|
### Paso 1: Verificar si tu cambio es propagable
|
|
|
|
**Preguntate:**
|
|
|
|
1. El modulo existe en `CATALOGO-MODULOS.yml`?
|
|
```bash
|
|
grep "tu-modulo" shared/knowledge-base/CATALOGO-MODULOS.yml
|
|
```
|
|
|
|
2. El cambio es generico (no especifico de tu proyecto)?
|
|
|
|
3. El cambio beneficia a otros proyectos?
|
|
|
|
Si la respuesta es SI a las tres, tu cambio es propagable.
|
|
|
|
### Paso 2: Determinar tipo de cambio
|
|
|
|
| Tipo | Descripcion | SLA |
|
|
|------|-------------|-----|
|
|
| security-fix | Vulnerabilidad de seguridad | 24 horas |
|
|
| bug-fix | Correccion de error | 48 horas |
|
|
| feature | Nueva funcionalidad | Evaluar |
|
|
| refactor | Mejora interna | Opcional |
|
|
| performance | Optimizacion | Evaluar |
|
|
|
|
### Paso 3: Ejecutar script de propagacion
|
|
|
|
```bash
|
|
./devtools/scripts/propagation/propagate-module-update.sh \
|
|
auth-jwt-nestjs \
|
|
2.2.0 \
|
|
gamilit
|
|
```
|
|
|
|
### Paso 4: Revisar proyectos afectados
|
|
|
|
El script mostrara que proyectos necesitan recibir la propagacion.
|
|
|
|
### Paso 5: Crear tareas de propagacion
|
|
|
|
Para cada proyecto destino:
|
|
1. Usar template `templates/TAREA-PROPAGACION.md`
|
|
2. Completar con datos del modulo y proyecto
|
|
3. Asignar a responsable del proyecto
|
|
|
|
### Paso 6: Implementar en cada proyecto
|
|
|
|
En cada proyecto destino:
|
|
```bash
|
|
# 1. Crear branch
|
|
git checkout -b feat/upgrade-modulo-X.Y.Z
|
|
|
|
# 2. Aplicar cambios
|
|
# (segun guia de migracion si es breaking change)
|
|
|
|
# 3. Build y tests
|
|
npm run build
|
|
npm run test
|
|
|
|
# 4. Commit con mensaje estandar
|
|
git commit -m "chore(deps): propagate modulo vX.Y.Z from proyecto-origen
|
|
|
|
- Descripcion del cambio
|
|
- Propagation ID: PROP-2026-XXX
|
|
|
|
See: @PROPAGACION"
|
|
```
|
|
|
|
### Paso 7: Actualizar registros
|
|
|
|
1. Actualizar `REGISTRO-PROPAGACIONES.yml`:
|
|
- Marcar destino como "completado"
|
|
- Agregar commit hash
|
|
- Agregar fecha
|
|
|
|
2. Actualizar `TRAZABILIDAD-PROYECTOS.yml`:
|
|
- Actualizar version del modulo en el proyecto
|
|
- Actualizar `ultima_sincronizacion`
|
|
|
|
3. Actualizar `HERENCIA-SIMCO.md` del proyecto:
|
|
- Actualizar tabla de modulos usados
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "Modulo no encontrado en catalogo"
|
|
|
|
**Problema:** El modulo no esta registrado en knowledge-base.
|
|
|
|
**Solucion:**
|
|
1. Verificar nombre exacto del modulo
|
|
2. Si el modulo es nuevo, primero agregarlo a `CATALOGO-MODULOS.yml`
|
|
3. Ver EPIC-006 para proceso de agregar modulos
|
|
|
|
### "Sin proyectos para propagar"
|
|
|
|
**Problema:** El modulo solo es usado por el proyecto origen.
|
|
|
|
**Solucion:** No es necesario propagar. La mejora ya esta aplicada.
|
|
|
|
### "TRAZABILIDAD-PROYECTOS.yml no encontrado"
|
|
|
|
**Problema:** Archivos del knowledge-base no estan en su lugar.
|
|
|
|
**Solucion:**
|
|
```bash
|
|
ls -la /home/isem/workspace-v1/shared/knowledge-base/
|
|
```
|
|
Si no existe, ejecutar EPIC-006 primero.
|
|
|
|
### "Breaking change detectado"
|
|
|
|
**Problema:** El cambio rompe compatibilidad.
|
|
|
|
**Solucion:**
|
|
1. Crear `MIGRATION-X.Y-to-X.Z.md` en el directorio del modulo
|
|
2. Marcar `breaking_change: true` en registro
|
|
3. Evaluar cada proyecto destino individualmente
|
|
4. Considerar crear EPIC dedicada si es muy complejo
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
**P: Que pasa si mi cambio es un breaking change?**
|
|
|
|
R: Debes crear una guia de migracion (`MIGRATION-X.Y-to-X.Z.md`) y marcar `breaking_change: true` en el registro. Considera crear un EPIC dedicado si afecta a muchos proyectos.
|
|
|
|
**P: Puedo propagar a solo algunos proyectos?**
|
|
|
|
R: Si. Puedes marcar destinos como "descartado" con `razon_descarte` explicando por que no aplica a ese proyecto.
|
|
|
|
**P: Quien decide si una mejora se propaga?**
|
|
|
|
R: El desarrollador que hace la mejora inicia el proceso. El responsable de cada proyecto destino decide si aplica o descarta.
|
|
|
|
**P: Que pasa si un proyecto no quiere recibir la propagacion?**
|
|
|
|
R: Se marca como "descartado" con la razon. Esto se documenta para futuras referencias.
|
|
|
|
**P: Con que frecuencia debo ejecutar check-module-versions.sh?**
|
|
|
|
R: Recomendado: semanalmente o como parte del proceso de CI/CD.
|
|
|
|
**P: Como se que modulos son los mas importantes de mantener actualizados?**
|
|
|
|
R: Los modulos con tipo `security-fix` siempre tienen prioridad. Ejecuta el reporte para ver estado general.
|
|
|
|
---
|
|
|
|
## Archivos Clave
|
|
|
|
| Archivo | Proposito |
|
|
|---------|-----------|
|
|
| `CATALOGO-MODULOS.yml` | Lista maestra de modulos disponibles |
|
|
| `TRAZABILIDAD-PROYECTOS.yml` | Mapeo modulo-proyecto con versiones |
|
|
| `REGISTRO-PROPAGACIONES.yml` | Historial de propagaciones |
|
|
| `templates/TAREA-PROPAGACION.md` | Template para tareas |
|
|
|
|
---
|
|
|
|
## Ver Tambien
|
|
|
|
- @PROPAGACION - Directiva oficial
|
|
- REGISTRO-PROPAGACIONES.yml - Historial
|
|
- TRAZABILIDAD-PROYECTOS.yml - Mapeo
|
|
- CATALOGO-MODULOS.yml - Lista de modulos
|
|
|
|
---
|
|
|
|
**Creado:** EPIC-007
|
|
**Sistema:** NEXUS v3.4
|