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
470 lines
13 KiB
Markdown
470 lines
13 KiB
Markdown
# CATÁLOGO DE FUNCIONALIDADES REUTILIZABLES
|
|
|
|
**Versión:** 1.0.0
|
|
**Fecha:** 2025-12-08
|
|
**Sistema:** NEXUS SIMCO v3.0
|
|
|
|
---
|
|
|
|
## PROPÓSITO
|
|
|
|
Este catálogo centraliza **código funcional probado y documentado** que puede ser reutilizado entre proyectos. Antes de implementar una funcionalidad común, los agentes DEBEN consultar este catálogo.
|
|
|
|
---
|
|
|
|
## PRINCIPIO FUNDAMENTAL
|
|
|
|
```
|
|
╔══════════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ ANTES DE IMPLEMENTAR, VERIFICAR SI YA EXISTE EN @CATALOG ║
|
|
║ ║
|
|
║ "Código probado > código nuevo" ║
|
|
║ "Reutilizar es más rápido que reinventar" ║
|
|
║ ║
|
|
╚══════════════════════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
---
|
|
|
|
## ESTRUCTURA DEL CATÁLOGO
|
|
|
|
```
|
|
core/catalog/
|
|
├── README.md ← ESTÁS AQUÍ
|
|
├── CATALOG-INDEX.yml # Índice máquina-readable
|
|
│
|
|
├── auth/ # Autenticación y autorización
|
|
│ ├── README.md # Descripción, cuándo usar
|
|
│ ├── IMPLEMENTATION.md # Guía de implementación
|
|
│ └── _reference/ # Código de referencia
|
|
│
|
|
├── session-management/ # Gestión de sesiones
|
|
│ ├── README.md
|
|
│ ├── IMPLEMENTATION.md
|
|
│ └── _reference/
|
|
│
|
|
├── rate-limiting/ # Limitación de tasa
|
|
│ ├── README.md
|
|
│ ├── IMPLEMENTATION.md
|
|
│ └── _reference/
|
|
│
|
|
├── notifications/ # Sistema de notificaciones
|
|
│ ├── README.md
|
|
│ ├── IMPLEMENTATION.md
|
|
│ └── _reference/
|
|
│
|
|
├── multi-tenancy/ # Soporte multi-tenant
|
|
│ ├── README.md
|
|
│ ├── IMPLEMENTATION.md
|
|
│ └── _reference/
|
|
│
|
|
├── feature-flags/ # Feature flags dinámicos
|
|
│ ├── README.md
|
|
│ ├── IMPLEMENTATION.md
|
|
│ └── _reference/
|
|
│
|
|
├── websocket/ # Comunicación en tiempo real
|
|
│ ├── README.md
|
|
│ ├── IMPLEMENTATION.md
|
|
│ └── _reference/
|
|
│
|
|
└── payments/ # Integración de pagos
|
|
├── README.md
|
|
├── IMPLEMENTATION.md
|
|
└── _reference/
|
|
```
|
|
|
|
---
|
|
|
|
## CÓMO USAR EL CATÁLOGO
|
|
|
|
### Para Agentes: Flujo de Verificación
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ ANTES de implementar funcionalidad común: │
|
|
│ │
|
|
│ 1. Consultar @CATALOG_INDEX │
|
|
│ → ¿Existe la funcionalidad? │
|
|
│ │
|
|
│ 2. Si existe: │
|
|
│ → Leer {funcionalidad}/README.md │
|
|
│ → Verificar compatibilidad de stack │
|
|
│ → Seguir {funcionalidad}/IMPLEMENTATION.md │
|
|
│ → Copiar código de _reference/ │
|
|
│ │
|
|
│ 3. Si NO existe: │
|
|
│ → Implementar siguiendo @SIMCO │
|
|
│ → Considerar agregar al catálogo después │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Alias Disponibles
|
|
|
|
```yaml
|
|
@CATALOG: core/catalog/
|
|
@CATALOG_INDEX: core/catalog/CATALOG-INDEX.yml
|
|
@CATALOG_AUTH: core/catalog/auth/
|
|
@CATALOG_SESSION: core/catalog/session-management/
|
|
@CATALOG_RATELIMIT: core/catalog/rate-limiting/
|
|
@CATALOG_NOTIFY: core/catalog/notifications/
|
|
@CATALOG_TENANT: core/catalog/multi-tenancy/
|
|
@CATALOG_FLAGS: core/catalog/feature-flags/
|
|
@CATALOG_WS: core/catalog/websocket/
|
|
@CATALOG_PAYMENTS: core/catalog/payments/
|
|
```
|
|
|
|
---
|
|
|
|
## FUNCIONALIDADES DISPONIBLES
|
|
|
|
### Estado Actual
|
|
|
|
| Funcionalidad | Estado | Origen | Stack |
|
|
|---------------|--------|--------|-------|
|
|
| auth | 🟢 Production-Ready | Gamilit | NestJS + JWT + Passport |
|
|
| session-management | 🟢 Production-Ready | Gamilit | NestJS + TypeORM |
|
|
| rate-limiting | 🟢 Production-Ready | Gamilit | NestJS + @nestjs/throttler |
|
|
| notifications | 🟢 Production-Ready | Gamilit | NestJS + Email/Push/WebPush |
|
|
| multi-tenancy | 🟢 Production-Ready | Gamilit | NestJS + PostgreSQL RLS |
|
|
| feature-flags | 🟢 Production-Ready | Gamilit | NestJS + TypeORM |
|
|
| websocket | 🟢 Production-Ready | Trading | NestJS + Socket.io |
|
|
| payments | 🟢 Production-Ready | Trading | NestJS + Stripe |
|
|
|
|
**Leyenda:**
|
|
- 🟢 Production-Ready: README.md + IMPLEMENTATION.md completos
|
|
- 🟡 Documentando: En proceso de documentación
|
|
- 🔴 Pendiente: Identificado pero no documentado
|
|
|
|
**Última actualización:** 2025-12-08
|
|
|
|
---
|
|
|
|
## ESTRUCTURA DE CADA FUNCIONALIDAD
|
|
|
|
Cada funcionalidad en el catálogo incluye:
|
|
|
|
### README.md
|
|
```markdown
|
|
# {Nombre} - Catálogo de Funcionalidad
|
|
|
|
## Metadata
|
|
- Versión, origen, estado, stack
|
|
|
|
## Descripción
|
|
- Qué hace
|
|
- Cuándo usar
|
|
- Cuándo NO usar
|
|
|
|
## Características
|
|
- Lista de features incluidas
|
|
|
|
## Dependencias
|
|
- npm packages
|
|
- Tablas de BD
|
|
- Servicios externos
|
|
|
|
## Trade-offs
|
|
- Limitaciones conocidas
|
|
- Alternativas
|
|
```
|
|
|
|
### IMPLEMENTATION.md
|
|
```markdown
|
|
# Implementación: {Nombre}
|
|
|
|
## Prerequisitos
|
|
- Lo que debe existir antes
|
|
|
|
## Pasos de Implementación
|
|
1. Paso detallado 1
|
|
2. Paso detallado 2
|
|
...
|
|
|
|
## Configuración
|
|
- Variables de entorno
|
|
- Opciones de configuración
|
|
|
|
## Verificación
|
|
- Cómo validar que funciona
|
|
|
|
## Troubleshooting
|
|
- Problemas comunes y soluciones
|
|
```
|
|
|
|
### _reference/
|
|
```
|
|
_reference/
|
|
├── {archivo1}.ts # Código de referencia
|
|
├── {archivo2}.ts
|
|
├── {archivo}.spec.ts # Tests
|
|
└── README.md # Descripción de cada archivo
|
|
```
|
|
|
|
---
|
|
|
|
## CONTRIBUIR AL CATÁLOGO
|
|
|
|
### IMPORTANTE: Directiva de Mantenimiento
|
|
|
|
```
|
|
╔══════════════════════════════════════════════════════════════════════════════╗
|
|
║ CUANDO IMPLEMENTES UNA FUNCIONALIDAD REUTILIZABLE EN UN PROYECTO: ║
|
|
║ ║
|
|
║ 1. EVALÚA si es candidata para el catálogo (ver criterios abajo) ║
|
|
║ 2. DOCUMENTA mientras desarrollas (más fácil que después) ║
|
|
║ 3. EXTRAE al catálogo cuando esté estable ║
|
|
║ ║
|
|
║ El catálogo crece con cada proyecto exitoso. ║
|
|
╚══════════════════════════════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
### Criterios de Inclusión
|
|
|
|
Una funcionalidad DEBE agregarse al catálogo si cumple **TODOS** estos criterios:
|
|
|
|
| Criterio | Descripción |
|
|
|----------|-------------|
|
|
| ✅ Probada | Funciona en producción (al menos 1 proyecto) |
|
|
| ✅ Reutilizable | No es específica de un dominio de negocio |
|
|
| ✅ Común | Se necesita en múltiples proyectos típicamente |
|
|
| ✅ Compleja | Tiene suficiente complejidad que justifica documentar |
|
|
| ✅ Estable | API/estructura no cambia frecuentemente |
|
|
|
|
**Ejemplos de funcionalidades candidatas:**
|
|
- Autenticación, sesiones, rate limiting
|
|
- Notificaciones, emails, push
|
|
- Pagos, suscripciones
|
|
- WebSockets, real-time
|
|
- Multi-tenancy, feature flags
|
|
- File upload, image processing
|
|
- Audit logs, activity tracking
|
|
- Caching strategies
|
|
|
|
**Ejemplos que NO van al catálogo:**
|
|
- Lógica de negocio específica (cálculo de comisiones de trading)
|
|
- UI components específicos (aunque pueden ir a un catálogo de UI)
|
|
- Configuraciones específicas de un proyecto
|
|
|
|
### Proceso de Adición (Checklist)
|
|
|
|
```markdown
|
|
PASO 1: PREPARAR ESTRUCTURA
|
|
[ ] Crear directorio: core/catalog/{nombre-en-kebab-case}/
|
|
[ ] Crear README.md vacío
|
|
[ ] Crear IMPLEMENTATION.md vacío
|
|
|
|
PASO 2: DOCUMENTAR README.md
|
|
[ ] Agregar metadata (versión, origen, estado, fecha)
|
|
[ ] Escribir descripción clara
|
|
[ ] Listar características
|
|
[ ] Definir stack tecnológico
|
|
[ ] Listar dependencias NPM
|
|
[ ] Listar tablas de BD requeridas
|
|
[ ] Documentar endpoints principales
|
|
[ ] Agregar diagrama de flujo si aplica
|
|
|
|
PASO 3: DOCUMENTAR IMPLEMENTATION.md
|
|
[ ] Listar pre-requisitos
|
|
[ ] Escribir pasos numerados de implementación
|
|
[ ] Incluir código de ejemplo en cada paso
|
|
[ ] Documentar variables de entorno
|
|
[ ] Crear checklist de verificación
|
|
[ ] Agregar sección de troubleshooting
|
|
|
|
PASO 4: ACTUALIZAR ÍNDICES (OBLIGATORIO)
|
|
[ ] Actualizar CATALOG-INDEX.yml:
|
|
- Agregar entrada bajo funcionalidades:
|
|
- Incluir: nombre, path, alias, estado, origen, version
|
|
- Incluir: stack, keywords, caracteristicas
|
|
- Incluir: dependencias_npm, tablas_requeridas
|
|
[ ] Actualizar este README.md:
|
|
- Agregar fila en tabla de "Estado Actual"
|
|
- Agregar en estructura de directorios
|
|
|
|
PASO 5: ACTUALIZAR ALIASES (OBLIGATORIO)
|
|
[ ] Editar core/orchestration/referencias/ALIASES.yml:
|
|
- Agregar alias @CATALOG_{NOMBRE}
|
|
- Ejemplo: @CATALOG_AUDIT: "core/catalog/audit-logs/"
|
|
|
|
PASO 6: VALIDAR
|
|
[ ] Verificar que grep encuentra la funcionalidad en CATALOG-INDEX.yml
|
|
[ ] Verificar que el alias funciona
|
|
[ ] Revisar que README e IMPLEMENTATION son claros
|
|
```
|
|
|
|
### Plantilla para Nueva Funcionalidad
|
|
|
|
**README.md:**
|
|
```markdown
|
|
# {Nombre de la Funcionalidad}
|
|
|
|
**Versión:** 1.0.0
|
|
**Origen:** projects/{proyecto}
|
|
**Estado:** Production-Ready | Documentando
|
|
**Última actualización:** YYYY-MM-DD
|
|
|
|
---
|
|
|
|
## Descripción
|
|
|
|
{Descripción clara de qué hace y para qué sirve}
|
|
|
|
---
|
|
|
|
## Características
|
|
|
|
| Característica | Descripción |
|
|
|----------------|-------------|
|
|
| ... | ... |
|
|
|
|
---
|
|
|
|
## Stack Tecnológico
|
|
|
|
\`\`\`yaml
|
|
backend:
|
|
framework: NestJS
|
|
# ...
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
## Dependencias NPM
|
|
|
|
\`\`\`json
|
|
{
|
|
"paquete": "^version"
|
|
}
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
## Tablas Requeridas
|
|
|
|
| Tabla | Propósito |
|
|
|-------|-----------|
|
|
| ... | ... |
|
|
|
|
---
|
|
|
|
## Endpoints Principales
|
|
|
|
| Método | Ruta | Descripción |
|
|
|--------|------|-------------|
|
|
| ... | ... | ... |
|
|
|
|
---
|
|
|
|
**Mantenido por:** Sistema NEXUS
|
|
**Proyecto origen:** {Proyecto}
|
|
```
|
|
|
|
**IMPLEMENTATION.md:**
|
|
```markdown
|
|
# Guía de Implementación: {Nombre}
|
|
|
|
**Versión:** 1.0.0
|
|
**Tiempo estimado:** X-Y horas
|
|
**Complejidad:** Baja | Media | Alta
|
|
|
|
---
|
|
|
|
## Pre-requisitos
|
|
|
|
- [ ] Requisito 1
|
|
- [ ] Requisito 2
|
|
|
|
---
|
|
|
|
## Paso 1: {Nombre del Paso}
|
|
|
|
{Descripción}
|
|
|
|
\`\`\`typescript
|
|
// Código de ejemplo
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
## Variables de Entorno
|
|
|
|
\`\`\`env
|
|
VARIABLE=valor
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
## Checklist de Implementación
|
|
|
|
- [ ] Paso completado 1
|
|
- [ ] Paso completado 2
|
|
- [ ] Build pasa sin errores
|
|
- [ ] Tests pasan
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Error: "{mensaje}"
|
|
{Solución}
|
|
|
|
---
|
|
|
|
**Versión:** 1.0.0
|
|
**Sistema:** SIMCO Catálogo
|
|
```
|
|
|
|
---
|
|
|
|
## INTEGRACIÓN CON SIMCO
|
|
|
|
Este catálogo se integra con el sistema SIMCO:
|
|
|
|
| Directiva | Integración |
|
|
|-----------|-------------|
|
|
| @SIMCO-REUTILIZAR | Directiva específica para reutilización |
|
|
| PRINCIPIO-ANTI-DUPLICACION | Verificar @CATALOG antes de crear |
|
|
| SIMCO-CREAR | Paso 0: Verificar catálogo |
|
|
| SIMCO-BUSCAR | Incluir @CATALOG como fuente |
|
|
| SIMCO-DELEGACION | Incluir @CATALOG en contexto |
|
|
|
|
---
|
|
|
|
## MANTENIMIENTO
|
|
|
|
### Actualizar Funcionalidad Existente
|
|
|
|
```markdown
|
|
Cuando el código de referencia mejore en un proyecto:
|
|
|
|
1. Evaluar si el cambio es generalizable
|
|
2. Si sí: actualizar _reference/ y IMPLEMENTATION.md
|
|
3. Incrementar versión en README.md
|
|
4. Documentar cambio en historial
|
|
```
|
|
|
|
### Deprecar Funcionalidad
|
|
|
|
```markdown
|
|
Si una funcionalidad ya no es recomendada:
|
|
|
|
1. Marcar como "⚠️ Deprecated" en README.md
|
|
2. Documentar razón y alternativa
|
|
3. NO eliminar inmediatamente
|
|
4. Eliminar después de 2 versiones mayores
|
|
```
|
|
|
|
---
|
|
|
|
## REFERENCIAS
|
|
|
|
- **Sistema SIMCO:** `/core/orchestration/directivas/simco/`
|
|
- **Principios:** `/core/orchestration/directivas/principios/`
|
|
- **Aliases:** `/core/orchestration/referencias/ALIASES.yml`
|
|
|
|
---
|
|
|
|
**Versión:** 1.0.0 | **Sistema:** NEXUS SIMCO | **Mantenido por:** Tech Lead
|