HlgCodes Inc | Hub

documentacion-de-procesos-catalogqr

Se lee en 4 min

📄 Documentación de Procesos – CatalogQR (Agnostic SaaS)

Este documento describe el flujo operativo de la plataforma CatalogQR, un ecosistema SaaS diseñado para la digitalización de inventarios y catálogos interactivos. El sistema es totalmente agnóstico, permitiendo que cualquier unidad de negocio (Retail, Servicios, Gastronomía, etc.) publique su oferta de manera profesional mediante códigos QR.

🏗️ Arquitectura y Actores

  1. Super Admin (Staff): Administra la plataforma y planes a nivel global.
  2. Merchant (Negocio): Entidad que gestiona su inventario y recibe órdenes.
  3. Customer (Público): Usuario final que interactúa con el catálogo vía QR.

🔄 Proceso 1: Ciclo de Vida de una Orden (End-to-End)

Este proceso describe el viaje desde que un cliente llega al establecimiento hasta que recibe su pedido.

  1. Ingreso y Autenticación de Ubicación:
    • El Cliente escanea el código QR físico.
    • Sistema: Captura el slug del negocio y opcionalmente el table_number.
  2. Exploración del Catálogo:
    • SvelteKit consulta la tabla products filtrando por business_id (Aislamiento RLS).
    • Decisión: ¿El producto tiene stock? Si no (stock_quantity < 1), se muestra como “No disponible”.
  3. Configuración del Carrito:
    • El Cliente selecciona productos y define extras (ej. ingredientes adicionales o tallas).
    • El sistema calcula el subtotal dinámicamente usando los precios de la DB.
  4. Checkout e Integración de Pagos (Wompi):
    • Firma de Integridad: El backend genera un hash SHA-256 combinando: referencia + monto + integridad_secret.
    • Redirect: Se abre el Widget de Wompi.
    • Gateway: ¿Pago Exitoso?
      • NO: El cliente regresa al carrito con un mensaje de error.
      • SÍ: Wompi dispara un Webhook al endpoint /api/webhooks/wompi.
  5. Procesamiento de la Orden:
    • Base de Datos: Se crea el registro en orders y order_items. El estado inicial es pending o paid según el webhook.
    • Inventario: Se ejecuta el trigger update_stock_on_order para descontar cantidades.
  6. Notificación Multi-canal:
    • WhatsApp: El sistema envía un mensaje automático al Merchant vía WAHA.
    • Live Dashboard: El Merchant ve la orden aparecer en tiempo real (Supabase Realtime).
  7. Despacho y Cierre:
    • El Merchant cambia el estado a confirmed → in_delivery → delivered.
    • Cierre: El proceso termina cuando el estado es delivered.

🎫 Proceso 2: Gestión de Soporte Técnico (SaaS Helpdesk)

Flujo interno para garantizar la continuidad operativa de los comercios.

  1. Detección de Incidencia: El Merchant encuentra un problema y accede al panel de soporte.
  2. Creación del Ticket:
    • Ingresa Sujeto, Descripción y Prioridad (Baja, Media, Alta, Crítica).
    • DB: Inserción en support_tickets.
  3. Triage y Asignación:
    • El Staff (Super Admin) recibe notificación y cambia estado a in_progress.
    • Se crea un hilo en support_messages para comunicación directa.
  4. Resolución:
    • Decisión: ¿Se requiere cambio de código o base de datos?
      • SÍ: Se escala a Hotfix en Gitflow.
      • NO: Se resuelve mediante configuración.
  5. Validación y Cierre:
    • El Staff marca como resolved.
    • El Merchant recibe email de confirmación (SMTP2GO).

💳 Proceso 3: Onboarding y Configuración de Comercio

Flujo de entrada de un nuevo cliente al ecosistema SaaS.

  1. Registro de Identidad: El usuario crea su cuenta (merchant_profiles).
  2. Configuración del Tenant:
    • Se define el slug único y nombre del negocio (businesses).
    • Se vincula un Plan SaaS (ej. Pro, Premium) que define límites de productos.
  3. Aprovisionamiento de Pagos:
    • El Merchant ingresa sus propias Keys de Wompi en el panel de configuración.
    • El sistema valida la conectividad con la pasarela.
  4. Carga de Inventario:
    • Creación de categorías y productos iniciales.
    • Generación del Código QR Maestro con branding personalizado.

📊 Guía para Diagramación (BPMN / Swimlanes)

Si estás realizando el diagrama para tu actividad, te recomiendo usar estas Calles (Lanes):

  • Cliente: Inicia el flujo, elige productos y paga.
  • Sistema (CatalogQR): Procesa lógica, calcula subtotales y valida firmas.
  • Pasarela (Wompi): Procesa la transacción bancaria.
  • Merchant (Negocio): Recibe notificaciones y prepara el pedido.
  • Staff (Soporte): Solo interviene en el Proceso 2.

🔗 Documentación Relacionada

Vista Gráfica