🔗 Nexus

← Volver a notas
8 KB 25/07/2026 14:49
🔗

🎯 Proyecto: Programa de Lealtad Digital — Höseg Café

Cliente: Höseg Café — Cafetería de especialidad, Cusco
Presentado por: Disoftx Solutions
Fecha: Julio 2026
Estado: Propuesta comercial
URL presentación: https://proyectofidelidad-hosegcafe.disoftx.solutions


📋 Resumen

Sistema de fidelización 100% digital integrado al sistema de pedidos existente (PWA). El cliente acumula puntos automáticamente en Google Wallet sin necesidad de registrarse — solo marca un checkbox al hacer su pedido.


🧠 El Problema


💡 La Solución

Componente Descripción
Google Wallet API Tarjetas de lealtad digitales gratuitas en el celular del cliente
Registro implícito El cliente marca checkbox al pedir → se crea su tarjeta automáticamente
Puntos en tiempo real Cada compra suma puntos, el wallet se actualiza al instante
Panel Staff El mozo busca por DNI y ve/acumula/canjea puntos desde el admin
QR + Historial web Escaneando el QR del wallet, el cliente ve todas sus compras pasadas

🏗️ Arquitectura Técnica

Cliente (Android/iOS)          Mozo (Admin web)
       │                              │
       ▼                              ▼
┌──────────────────────────────────────────┐
│         Caddy (Zeta - IP pública)        │
│    154.38.186.254 · wildcard DNS         │
├──────────────────────────────────────────┤
│    Docker: caddy_proxy (puertos 80/443)  │
└──────────────────────────────────────────┤
                    │
        ┌───────────┴───────────┐
        │                       │
   Zeta (Docker)           Omni (VPS)
   ┌──────────────┐      ┌──────────────┐
   │ hosegcafe    │      │ postiz       │
   │ (3007)       │      │ nexus        │
   │ z-shield     │      └──────────────┘
   │ medical      │
   │ z-feedback   │
   └──────────────┘

Stack tecnológico

Tecnología Uso
Node.js + Express Backend de Höseg (pedidos, admin, loyalty endpoints)
SQLite (better-sqlite3) Base de datos actual
Google Wallet API Creación y actualización de pases de lealtad
Caddy Proxy reverso + SSL automático (wildcard cert)
Docker Contenedores en Zeta (caddy_proxy, hosegcafe)
PWA Frontend cliente (Service Worker + manifest)

🗄️ Estructura de Datos

Tablas existentes (sin cambios)

-- Pedidos (ya guarda datos del cliente)
orders (id, order_code, customer_name, customer_lastname, 
        customer_dni, customer_phone, customer_hotel, 
        email, order_type, total, status, ...)

-- Suscriptores actual (se expande)
subscribers (id, email, name, source, active, created_at)

Tablas nuevas

-- Programa de lealtad
ALTER TABLE subscribers ADD COLUMN phone TEXT;
ALTER TABLE subscribers ADD COLUMN dni TEXT;
ALTER TABLE subscribers ADD COLUMN total_purchases INTEGER DEFAULT 0;
ALTER TABLE subscribers ADD COLUMN total_spent REAL DEFAULT 0;
ALTER TABLE subscribers ADD COLUMN points INTEGER DEFAULT 0;

-- Pases de Google Wallet
CREATE TABLE loyalty_cards (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  subscriber_id INTEGER NOT NULL,
  google_wallet_object_id TEXT UNIQUE,
  google_wallet_class_id TEXT,
  points INTEGER DEFAULT 0,
  tier TEXT DEFAULT 'bronze',
  last_updated TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  FOREIGN KEY (subscriber_id) REFERENCES subscribers(id)
);

-- Canjes realizados
CREATE TABLE loyalty_redemptions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  subscriber_id INTEGER NOT NULL,
  order_id INTEGER,
  points_used INTEGER NOT NULL,
  reward TEXT NOT NULL,
  redeemed_at TEXT DEFAULT (datetime('now')),
  FOREIGN KEY (subscriber_id) REFERENCES subscribers(id),
  FOREIGN KEY (order_id) REFERENCES orders(id)
);

🔄 Flujo de Usuario

Primera compra (registro implícito)

  1. Cliente pide su café desde la PWA o en mesa
  2. Llena datos (nombre, DNI, teléfono) — ya lo hace en el pedido
  3. Marca checkbox: "Acumular puntos"
  4. Backend verifica si el DNI ya existe → si no, crea subscriber
  5. Backend crea LoyaltyObject en Google Wallet API + genera JWT link
  6. Mozo envía link por WhatsApp al cliente o muestra QR en pantalla
  7. Cliente hace tap → tarjeta guardada en Google Wallet

Siguientes compras

  1. Mozo busca DNI en el admin → ve puntos actuales del cliente
  2. Mozo puede acumular más puntos o canjear
  3. Google Wallet se actualiza automáticamente vía API (PATCH)

Canje

  1. Cliente pide canjear puntos
  2. Mozo selecciona "Canjear" en el admin → descuenta puntos
  3. Puntos actualizados en Google Wallet
  4. Pedido marcado como canjeado

📱 Google Wallet — Qué se muestra

Limitaciones conocidas


🖥️ Admin — Nuevas features para el mozo

Feature Descripción
Buscar cliente por DNI Barra de búsqueda en admin
Mostrar puntos Al lado del pedido
Acumular puntos Checkbox/botón
Canjear recompensas Botón + modal de descuento
Enviar link Wallet Botón "Enviar por WhatsApp"

⚠️ Riesgos y Mitigaciones

Riesgo Mitigación
Google API caída Offline-first: puntos se guardan en SQLite, Google Wallet se actualiza en background
iPhone sin Google Wallet Mostrar versión web del pase + opción futura de Apple Wallet
Doble canje Transacciones SQL + estado pending en redenciones
Desincronización puntos SQLite es fuente de verdad, wallet es espejo
Cliente quita el pase En próxima compra, regenerar link


📝 Historial de decisiones

Fecha Decisión Razón
2026-07-25 Google Wallet sobre Apple Wallet $0 vs $99/año de Apple Developer. Cobertura Android + iOS (vía app)
2026-07-25 Wildcard DNS → Zeta Zeta tiene IP pública (154.38.186.254) y ya maneja múltiples subdominios
2026-07-25 Registro implícito vía checkbox En vez de formulario de suscripción separado. Sin fricción para el cliente
2026-07-25 Eliminar slide de Próximos Pasos No mostrar precios/timing al cliente en presentación
2026-07-25 Eliminar AAAA wildcard IPv6 apuntaba a Stoico, causaba error SSL en móviles
2026-07-25 Correo nexus@disoftx.solutions Email corporativo para registros de APIs y servicios

🔮 Mejoras futuras


📁 Archivos del proyecto

Archivo Ubicación
Presentación web ~/.openclaw/workspace/hoseg-presentation/index.html
Live online https://proyectofidelidad-hosegcafe.disoftx.solutions
Código Höseg (Zeta) /home/opsmgr/proyectos/hosegcafe/
Caddy configs (Zeta) /home/opsmgr/proyectos/caddy/sites/
Caddy config (local) /etc/caddy/Caddyfile (Omni)
Docs proyecto wiki/proyecto-fidelidad-hosegcafe.md (este archivo)

Documentado por Nexus 🔗 · Disoftx Solutions