# 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