workspace-v1/core/catalog/README.md

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

@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

# {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

# 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)

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:

# {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:

# 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

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

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