# ═══════════════════════════════════════════════════════════════════════════════
# ÍNDICE DEL CATÁLOGO DE FUNCIONALIDADES REUTILIZABLES
# ═══════════════════════════════════════════════════════════════════════════════
#
# Versión: 1.0.0
# Fecha: 2025-12-08
# Propósito: Índice máquina-readable para búsqueda rápida de funcionalidades
#
# USO:
#   Los agentes consultan este archivo ANTES de implementar funcionalidades comunes.
#   Usar: grep -i "{funcionalidad}" @CATALOG_INDEX
#
# ═══════════════════════════════════════════════════════════════════════════════

version: "1.1.0"
fecha_actualizacion: "2025-12-27"
total_funcionalidades: 11

# ─────────────────────────────────────────────────────────────────────────────────
# ÍNDICE DE FUNCIONALIDADES
# ─────────────────────────────────────────────────────────────────────────────────

funcionalidades:

  # ═══════════════════════════════════════════════════════════════════
  # AUTENTICACIÓN Y SEGURIDAD
  # ═══════════════════════════════════════════════════════════════════

  auth:
    nombre: "Autenticación y Autorización"
    path: "core/catalog/auth/"
    alias: "@CATALOG_AUTH"
    estado: "production-ready"  # production-ready | documentando | pendiente
    origen: "projects/gamilit"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "JWT"
      - "Passport"
      - "bcrypt"
      - "TypeORM"
    keywords:
      - "login"
      - "registro"
      - "jwt"
      - "token"
      - "password"
      - "oauth"
      - "social-login"
      - "autenticacion"
      - "authorization"
      - "guard"
    caracteristicas:
      - "JWT access + refresh tokens"
      - "Password hashing con bcrypt"
      - "Multiple OAuth providers"
      - "Auth attempts tracking"
      - "Password recovery"
    dependencias_npm:
      - "@nestjs/jwt"
      - "@nestjs/passport"
      - "passport-jwt"
      - "bcrypt"
    tablas_requeridas:
      - "auth.users"
      - "auth.user_sessions"
      - "auth.auth_attempts"

  session-management:
    nombre: "Gestión de Sesiones"
    path: "core/catalog/session-management/"
    alias: "@CATALOG_SESSION"
    estado: "production-ready"
    origen: "projects/gamilit"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "TypeORM"
      - "PostgreSQL"
    keywords:
      - "sesion"
      - "session"
      - "logout"
      - "dispositivo"
      - "device"
      - "concurrent"
      - "max-sessions"
    caracteristicas:
      - "Máximo N sesiones concurrentes"
      - "Auto-cleanup de sesiones expiradas"
      - "Tracking de dispositivos"
      - "Logout de sesión específica"
      - "Logout de todas las sesiones"
    dependencias_npm:
      - "typeorm"
    tablas_requeridas:
      - "auth.user_sessions"

  rate-limiting:
    nombre: "Limitación de Tasa (Rate Limiting)"
    path: "core/catalog/rate-limiting/"
    alias: "@CATALOG_RATELIMIT"
    estado: "production-ready"
    origen: "projects/gamilit"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "Redis (opcional)"
    keywords:
      - "rate-limit"
      - "throttle"
      - "429"
      - "too-many-requests"
      - "abuse"
      - "ddos"
      - "limite"
    caracteristicas:
      - "Rate limiting por usuario/IP"
      - "Configuración por endpoint"
      - "Headers de límite estándar"
      - "Respuestas 429 con retry-after"
    dependencias_npm:
      - "@nestjs/throttler"
    tablas_requeridas: []

  # ═══════════════════════════════════════════════════════════════════
  # COMUNICACIÓN Y NOTIFICACIONES
  # ═══════════════════════════════════════════════════════════════════

  notifications:
    nombre: "Sistema de Notificaciones"
    path: "core/catalog/notifications/"
    alias: "@CATALOG_NOTIFY"
    estado: "production-ready"
    origen: "projects/gamilit"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "TypeORM"
      - "Nodemailer"
      - "FCM (opcional)"
    keywords:
      - "notificacion"
      - "notification"
      - "email"
      - "push"
      - "in-app"
      - "alerta"
      - "mensaje"
    caracteristicas:
      - "Notificaciones email"
      - "Notificaciones in-app"
      - "Push notifications (FCM)"
      - "Preferencias de usuario"
      - "Historial de notificaciones"
      - "Templates de email"
    dependencias_npm:
      - "nodemailer"
      - "@nestjs/mailer"
      - "firebase-admin (opcional)"
    tablas_requeridas:
      - "notifications.notifications"
      - "notifications.notification_preferences"
      - "notifications.notification_templates"

  websocket:
    nombre: "Comunicación WebSocket"
    path: "core/catalog/websocket/"
    alias: "@CATALOG_WS"
    estado: "production-ready"
    origen: "projects/trading-platform"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "Socket.io"
    keywords:
      - "websocket"
      - "socket"
      - "realtime"
      - "tiempo-real"
      - "streaming"
      - "live"
      - "push"
    caracteristicas:
      - "Conexiones WebSocket"
      - "Rooms/canales"
      - "Autenticación de socket"
      - "Broadcasting"
      - "Heartbeat/ping"
    dependencias_npm:
      - "@nestjs/websockets"
      - "@nestjs/platform-socket.io"
      - "socket.io"
    tablas_requeridas: []

  # ═══════════════════════════════════════════════════════════════════
  # ARQUITECTURA MULTI-TENANT
  # ═══════════════════════════════════════════════════════════════════

  multi-tenancy:
    nombre: "Soporte Multi-Tenant"
    path: "core/catalog/multi-tenancy/"
    alias: "@CATALOG_TENANT"
    estado: "production-ready"
    origen: "projects/gamilit"
    version: "1.0.0"
    stack:
      - "PostgreSQL"
      - "RLS"
      - "NestJS"
    keywords:
      - "tenant"
      - "multi-tenant"
      - "organization"
      - "empresa"
      - "aislamiento"
      - "rls"
      - "row-level-security"
    caracteristicas:
      - "Aislamiento por tenant"
      - "Row Level Security (RLS)"
      - "Tenant context en requests"
      - "Configuración por tenant"
    dependencias_npm:
      - "typeorm"
    tablas_requeridas:
      - "core.organizations"
      - "core.organization_members"

  # ═══════════════════════════════════════════════════════════════════
  # FEATURE FLAGS Y CONFIGURACIÓN
  # ═══════════════════════════════════════════════════════════════════

  feature-flags:
    nombre: "Feature Flags Dinámicos"
    path: "core/catalog/feature-flags/"
    alias: "@CATALOG_FLAGS"
    estado: "production-ready"
    origen: "projects/gamilit"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "TypeORM"
      - "PostgreSQL"
    keywords:
      - "feature-flag"
      - "toggle"
      - "feature"
      - "bandera"
      - "a/b-test"
      - "rollout"
      - "configuracion"
    caracteristicas:
      - "Flags por ambiente"
      - "Flags por usuario/rol"
      - "Activación gradual (rollout)"
      - "Cache de flags"
      - "UI de administración"
    dependencias_npm:
      - "typeorm"
    tablas_requeridas:
      - "config.feature_flags"
      - "config.feature_flag_rules"

  # ═══════════════════════════════════════════════════════════════════
  # PAGOS E INTEGRACIONES
  # ═══════════════════════════════════════════════════════════════════

  payments:
    nombre: "Integración de Pagos"
    path: "core/catalog/payments/"
    alias: "@CATALOG_PAYMENTS"
    estado: "production-ready"
    origen: "projects/trading-platform"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "Stripe"
    keywords:
      - "pago"
      - "payment"
      - "stripe"
      - "subscription"
      - "suscripcion"
      - "factura"
      - "invoice"
      - "checkout"
    caracteristicas:
      - "Integración Stripe"
      - "Webhooks de pago"
      - "Suscripciones"
      - "Checkout sessions"
      - "Historial de pagos"
    dependencias_npm:
      - "stripe"
    tablas_requeridas:
      - "billing.subscriptions"
      - "billing.payments"
      - "billing.invoices"

  # ═══════════════════════════════════════════════════════════════════
  # TEMPLATES Y ARQUITECTURA
  # ═══════════════════════════════════════════════════════════════════

  template-saas:
    nombre: "Template SaaS Multi-tenant"
    path: "core/catalog/template-saas/"
    alias: "@CATALOG_SAAS"
    estado: "production-ready"
    origen: "projects/erp-core, projects/gamilit"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "React"
      - "PostgreSQL"
      - "Stripe"
    keywords:
      - "saas"
      - "template"
      - "multi-tenant"
      - "suscripcion"
      - "subscription"
      - "billing"
      - "onboarding"
      - "plans"
      - "pricing"
    caracteristicas:
      - "Estructura de proyecto SaaS"
      - "Sistema de planes y pricing"
      - "Suscripciones con Stripe"
      - "Flujo de onboarding"
      - "Dashboard de admin"
      - "Metricas de uso"
    dependencias_npm:
      - "stripe"
      - "@nestjs/config"
      - "zustand"
    tablas_requeridas:
      - "billing.plans"
      - "billing.subscriptions"
      - "billing.payments"

  portales:
    nombre: "Portales y Dashboards"
    path: "core/catalog/portales/"
    alias: "@CATALOG_PORTALES"
    estado: "production-ready"
    origen: "projects/gamilit, projects/trading-platform"
    version: "1.0.0"
    stack:
      - "React"
      - "NestJS"
      - "Socket.io"
      - "Recharts"
    keywords:
      - "portal"
      - "dashboard"
      - "widget"
      - "metricas"
      - "kpi"
      - "charts"
      - "graficos"
      - "admin"
      - "layout"
    caracteristicas:
      - "Dashboards multi-rol"
      - "Widgets configurables"
      - "Metricas en tiempo real"
      - "Layouts personalizables"
      - "Preferencias de usuario"
    dependencias_npm:
      - "recharts"
      - "react-grid-layout"
      - "socket.io-client"
    tablas_requeridas:
      - "config.dashboard_layouts"
      - "config.user_dashboard_preferences"
      - "config.widgets"

  audit-logs:
    nombre: "Sistema de Auditoria"
    path: "core/catalog/audit-logs/"
    alias: "@CATALOG_AUDIT"
    estado: "production-ready"
    origen: "projects/gamilit, projects/erp-core"
    version: "1.0.0"
    stack:
      - "NestJS"
      - "TypeORM"
      - "PostgreSQL"
    keywords:
      - "audit"
      - "auditoria"
      - "log"
      - "tracking"
      - "historial"
      - "cambios"
      - "acceso"
      - "compliance"
      - "gdpr"
      - "hipaa"
    caracteristicas:
      - "Entity tracking automatico"
      - "Access logs para recursos sensibles"
      - "Action logs de usuario"
      - "Busqueda y filtrado"
      - "Politicas de retencion"
      - "Exportacion CSV/JSON"
    dependencias_npm:
      - "typeorm"
      - "nestjs-cls"
    tablas_requeridas:
      - "audit.entity_logs"
      - "audit.access_logs"
      - "audit.action_logs"

# ─────────────────────────────────────────────────────────────────────────────────
# BÚSQUEDA RÁPIDA POR KEYWORD
# ─────────────────────────────────────────────────────────────────────────────────
#
# Para buscar funcionalidad por keyword:
#   grep -i "{keyword}" core/catalog/CATALOG-INDEX.yml
#
# Ejemplos:
#   grep -i "login" → auth
#   grep -i "sesion" → session-management
#   grep -i "429" → rate-limiting
#   grep -i "email" → notifications
#   grep -i "realtime" → websocket
#   grep -i "tenant" → multi-tenancy
#   grep -i "toggle" → feature-flags
#   grep -i "stripe" → payments
#   grep -i "saas" → template-saas
#   grep -i "dashboard" → portales
#   grep -i "audit" → audit-logs
#
# ─────────────────────────────────────────────────────────────────────────────────

# ─────────────────────────────────────────────────────────────────────────────────
# INSTRUCCIONES PARA AGENTES
# ─────────────────────────────────────────────────────────────────────────────────

instrucciones:
  cuando_consultar: |
    SIEMPRE consultar este índice ANTES de implementar:
    - Autenticación/login
    - Gestión de sesiones
    - Rate limiting
    - Notificaciones
    - WebSockets/tiempo real
    - Multi-tenancy
    - Feature flags
    - Pagos/suscripciones
    - Template SaaS/onboarding
    - Dashboards/portales
    - Auditoria/logs

  como_buscar: |
    1. Buscar por keyword:
       grep -i "{lo que necesito}" @CATALOG_INDEX

    2. Si encuentra match:
       - Leer path indicado
       - Verificar estado (preferir production-ready)
       - Verificar stack compatible

    3. Si NO encuentra:
       - Proceder con implementación nueva
       - Considerar agregar al catálogo después

  que_hacer_si_encuentra: |
    1. Ir a: core/catalog/{funcionalidad}/
    2. Leer: README.md (descripción y trade-offs)
    3. Seguir: IMPLEMENTATION.md (pasos)
    4. Copiar: _reference/ (código base)
    5. Adaptar: configuración al proyecto actual
    6. Validar: ejecutar tests de referencia

# ═══════════════════════════════════════════════════════════════════════════════
# FIN DEL ÍNDICE
# ═══════════════════════════════════════════════════════════════════════════════