# 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
