🔗 Nexus

← Volver a notas
27 KB 06/08/2026 03:19
🔗

Hoseg Cash — Arquitectura Consolidada (borrador v1)

Fecha: 2026-08-05 · Fuentes: diseño Daniel/Nexus + informe Gemini (Shopify) + benchmark Café Neira


1. Componentes

Ledger (fuente de verdad del saldo)

Servicio central (Node.js) — API REST

Shopify (custom app + Theme 2.0)

Odoo POS (tienda)

PWA Wallet (cliente)

Wallets nativas


2. Flujos

A. Registro

QR en tienda → formulario (nombre, apellido, DNI, tel, cumpleaños) → instala PWA → login OTP WhatsApp

B. Compra en tienda (acumular)

Cliente muestra QR → cajero escanea (panel staff, su celular) → ingresa monto → ~5 min async → ledger credita → (progreso actualizado)

C. Compra web Shopify (acumular + canjear)

Carrito → cliente ingresa DNI → App Proxy valida (HMAC) → monto = min(saldo, subtotalElegible) → código generado → auto-aplica → checkout → orders/paid → debita usado + acredita ganado (sobre neto pagado, sin ítems no-cashback ni envío) → PATCH Google Wallet

D. Canje en tienda

Cajero panel staff → busca cliente (QR/DNI) → ve saldo → pregunta cuánto → descuento manual en Odoo POS → marca canje en panel → ledger debita

E. Reversiones

refund/cancel → recalcula y revierte cashback de esa compra (anti-fraude)

F. Geofencing (fase 2)

Notificación "Tienda Hoseg - Cerca" (patrón Neira)


3. Correcciones críticas al informe Gemini (para NUESTRO caso)

  1. NO es % de recompensa (5%) — nuestras reglas son umbrales: >S/299→10, >S/699→30, montos CON IGV. El motor de reglas es nuestro (config), no un porcentaje fijo.
  2. IGV: subtotalElegible y umbrales deben calcularse con impuestos incluidos (cart.js tiene totales por línea con tax).
  3. Ledger unificado: el informe solo habla de BD externa — debe convivir con el flujo tienda (poller Odoo + panel staff). El ledger es UNO para ambos canales.
  4. Concurrencia: reserva/bloqueo del saldo durante checkout (el informe lo menciona — es clave para doble uso).
  5. Combinación de cupones: Shopify permite 1 código por checkout por defecto — si el cliente ya tiene otro cupón, hay conflicto (definir política).
  6. Cupón vs descuento manual en tienda: el informe no cubre el POS (eso es nuestro panel staff + descuento manual en Odoo).

4. MVP semana 1 (recorte propuesto)

✅ PWA wallet (OTP, tarjeta, QR, saldo, progreso, Google Wallet)
✅ Servicio central: ledger + reglas + OTP + API
✅ Shopify: app proxy + código + webhook orders/paid (débito+crédito)
✅ Poller Odoo + panel staff (canje manual)
⏳ FASE 2: reversiones completas, geofencing, Apple Wallet, refinamiento tema (cart drawer pulido)

5. Decisiones pendientes (para confirmar con Daniel)

  1. Ledger: Odoo vs BD externa (recomendación: BD externa tras interfaz)
  2. Identificación tienda: QR del cliente (como Neira) vs DNI
  3. Shopify: cart-drawer (UX completa) vs versión simple (página cuenta cliente)
  4. Política de cupones combinados
  5. Aprobación del recorte MVP semana 1

✅ Decisiones confirmadas (2026-08-05 19:54)

  1. Ledger: BD NUESTRA ✅ (Opción 3 confirmada — plataforma propia, replicable)
  2. Identificación en tienda: QR del cliente ✅ (patrón Neira — cajero escanea y pone monto)
  3. Shopify: recomendación Nexus = cart-drawer UX implementada como APP BLOCK (theme app extension, no hack de cart-drawer.liquid — resistente a actualizaciones del tema). Fallback: página de cuenta cliente.
  4. Apple Wallet: info recopilada — ver abajo. Recomendación: fase 2 (Google Wallet cubre iOS).

🍎 Apple Wallet — qué se necesita (2026-08-05 19:54)

✅ Shopify plan Basic — compatibilidad (2026-08-05 19:57)

✅ Tema confirmado (2026-08-05 20:00)

🔄 PIVOT: Sin Odoo — Plataforma 100% nuestra (2026-08-05 20:06) ⭐

Decisión de Daniel: Odoo YA NO se toca. Adiós poller, XML-RPC y gift cards.

Cambios clave

  1. Regla única: compra > S/299 → S/30 cashback (se simplifica; antes 299→10 / 699→30)
  2. Reglas configurables desde el panel admin: el admin puede añadir/modificar reglas (motor config-driven en BD)
  3. Sin integración Odoo: el cashback en tienda lo genera el vendedor desde su app
  4. Nuevo: App Vendedor — el vendedor escanea el QR del cliente, ingresa el monto de la venta → el sistema calcula y genera el cashback (patrón Neira)
  5. Nuevo: Panel Admin — modificar reglas/umbrales + reportes (ventas, cashback, clientes, sucursales)

Superficies de la plataforma (3 apps + Shopify)

Superficie Usuario Funciones
PWA Cliente Cliente Tarjeta+QR, saldo, historial, progreso, Google Wallet
App Vendedor Cajero/vendedor Escanear QR cliente → monto venta → genera cashback · ver saldo · canje manual
Panel Admin Admin (14 Diez SAC) Reglas (añadir/editar), reportes, sucursales, usuarios
Shopify Cliente web App block carrito + cupón + webhooks (acredita/revierte)

Nota

📱 OTP WhatsApp — opciones sin Meta Business (2026-08-05 20:24)

📱 Aclaración OTP (2026-08-05 20:25)

🔐 Login SIN OTP — magic link (2026-08-05 20:28) ⭐

🧾 FLUJO DEFINITIVO: Registro del cliente (2026-08-05 20:43)

  1. QR en tienda (mostrador/posters/boletas) → URL pública hoseg.cash/registro
  2. Formulario: nombre, apellido, DNI, teléfono, cumpleaños (validación: formato, duplicados DNI/tel → si existe, ofrecer recuperar wallet)
  3. Al enviar (backend):
  4. Crea cliente en ledger + genera token wallet (secreto) + código tarjeta visible (HC-XXXX) + contenido QR
  5. Página éxito: tarjeta virtual + botones: "Abrir mi wallet" · "Instalar app" · "Añadir a Google Wallet" (JWT) · "Enviarme el link por WhatsApp" (wa.me con texto precargado — el cliente se lo envía a sí mismo, SIN API)
  6. PWA: link hoseg.cash/w/<token> → abre wallet directo (sin login): tarjeta, QR, saldo S/0, progreso. Instalación PWA (Add to Home Screen) → token en localStorage → abre siempre directo
  7. Compra tienda: cliente muestra QR → app vendedor escanea → monto → regla (>299 → +S/30) → cashback acreditado → visible en wallet (async ~5min opcional)
  8. Recuperación (celular nuevo/perdido): vendedor verifica DNI → regenera link (verificación humana)
  9. Detalles backend: transacción + auditoría en ledger; si cierra la página antes de instalar, el link sigue válido (historial/WhatsApp self-message)

📲 PWA install (2026-08-05 20:46)

🚀 PRODUCCIÓN v0.1 DESPLEGADA (2026-08-05 21:20) ✅

🪪 Google Wallet — botón implementado en producción (2026-08-05 21:30)

✅ Google Wallet CONFIGURADO (2026-08-05 23:02)

🐛 Fix Google Wallet (2026-08-05 23:15)

🔧 Ajustes UX wallet (2026-08-05 23:40)

⚡ Sync en vivo Google Wallet VERIFICADA (2026-08-05 23:50)

🧪 Modo demo — usuarios de prueba (2026-08-06 00:21)

📜 Historial en Google Wallet (2026-08-06 00:35)

🔧 Correcciones 2026-08-06 00:47 (Daniel)

  1. Progreso acumulativo: "tu próximo cashback" ahora suma TODAS las compras (aunque no cumplan la regla) → objetivo: llegar al umbral. Regla pasó a CUMULATIVA: cuando las compras acumuladas desde el último cashback alcanzan S/299 → +S/30 (contador se reinicia). Verificado en prod: 120+120+120 → 360 → +30 → reset.
  2. Bug doble "S/": la tarjeta mostraba "S/ S/ 180.00" (literal HTML + prefijo del JS) → corregido (solo número en JS).
  3. Comportamiento: el excedente sobre el umbral no se arrastra (se reinicia a 0) — revisar si se quiere arrastre.

🧱 Regla POR BLOQUES corregida (2026-08-06 01:10) ⭐

🎨 Consultas de Daniel (01:10)

  1. ¿Se pueden modificar las tarjetas de Google Wallet? → SÍ: color (hexBackgroundColor), logo, imágenes, textos, QR. Daniel puede pasar el diseño → se actualiza la clase (en demo sin re-aprobación; en producción publicada puede requerir re-review)
  2. ¿Clasificación por nivel de compra + cambio de color de tarjeta? → SÍ viable:
  3. Niveles configurables en admin (nombre, monto mínimo acumulado, color): ej Bronze/Silver/Gold
  4. PWA: color de tarjeta cambia según nivel + badge
  5. Google Wallet: una clase por nivel (cada una con su color) → el objeto se mueve entre clases vía PATCH al cambiar de nivel
  6. Pendiente de implementar (proponer después de estabilizar flujo actual)

🏅 NIVELES CONFIGURABLES implementados (2026-08-06 01:19)

🔔 Notificaciones vía Google Wallet + Geofencing + TZ (2026-08-06 01:40) ✅

  1. Broadcast "Notificar a todos" (admin → tab Notificaciones): título + mensaje → PATCH a todos los objetos de Google Wallet (los que tienen el pase reciben notificación; sin pase se cuentan como fallidos). Verificado: mensaje llegó al pase de Daniel.
  2. Cumpleaños automático: mensaje prediseñado editable + checkbox activar (settings birthday_message/birthday_enabled) · cron 8:00 AM hora Lima (TZ America/Lima en contenedor) · usa {nombre} · endpoint manual /api/notify/birthday/run para probar.
  3. Geolocalización en Google Wallet: class tiene locations (LatLongPoint latitude/longitude — campo correcto, NO lat/lng) con las 5 sucursales → Google notifica al estar cerca. PATCH requiere reviewStatus UNDER_REVIEW. Verificado: 5 locations en la clase.
  4. Hora servidor GMT-5: TZ=America/Lima en el contenedor (verificado: -05).
  5. Nota: demo mode limita a testers (10) — para producción completa: Perfil de Empresa + publicación.

🔔 Descubrimiento + Web Push (2026-08-06 01:45)

🏪 Sucursales configurables + link wallet + saldo pase (2026-08-06 02:00)

  1. Admin → tab Sucursales: editar nombre/dirección/lat/lng de cada punto de venta (coords desde Google Maps: clic derecho → copiar) + añadir nuevas. Al guardar → re-PATCH del geofencing en Google Wallet (syncClassLocations). Endpoints PUT/POST /api/branches (admin).
  2. Clientes → link del wallet: cada cliente muestra "abrir" + botón 💬 WhatsApp (wa.me/51...) para reenviar el link si lo pierde. También en export CSV.
  3. Saldo en pase Google Wallet: el API de Google normaliza el balance a string ("S/ 180.00") — el valor en Google es CORRECTO; el 0.00 en el celular = pase sin sincronizar (pull-to-refresh o quitar/re-agregar el pase). moneyObj usa currencyCode PEN + micros.
  4. Endpoint POST /api/gwallet/sync (admin) para re-sincronizar saldos de todos los pases.

📨 addMessage (Wallet API v1) implementado (2026-08-06 02:30)

🔍 Diagnóstico pase + notificaciones (2026-08-06 02:40)

📨 Ciclo de vida de mensajes Google Wallet (2026-08-06 02:50) — implementado

  1. displayInterval: formato correcto = start/end con {date: RFC3339} (NO startTime/endTime — Google los ignora). El admin elige días de expiración (default 7); el mensaje desaparece solo del pase al vencer. Verificado: fin guardado.
  2. Límite de mensajes: cleanup conserva máx 3 (2 más recientes + nuevo) — Google limita push a 3/24h por pase.
  3. messageType: "TEXT_AND_NOTIFY" → mensaje en el pase + NOTIFICACIÓN PUSH real al celular (verificado: se guarda como textAndNotify).
  4. ⚠️ Regla Google: Android NO envía push en las primeras 12h tras instalar el pase (el mensaje sí aparece). Daniel debe esperar 12h para ver el popup de su pase re-agregado.

✅ PUSH DE GOOGLE WALLET CONFIRMADO (2026-08-06 02:44)

🐛 Fix: "Cashback 0" en la PARTE POSTERIOR del pase (2026-08-06 02:55)

🎨 Pase Google Wallet con COLOR POR NIVEL (2026-08-06 03:05)

🏷️ Nivel en el pase + capacidades (2026-08-06 03:10)

🔗 Redes sociales + nivel en el FRENTE del pase (2026-08-06 03:15)

🖼️ Imagen HERO en el frente del pase (2026-08-06 03:20)