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)
- Clientes: nombre, apellido, DNI, teléfono, email, cumpleaños
- Saldos + transacciones (acumulación / canje / reversión) + reservas (concurrencia)
- Reglas config-driven: umbrales S/299→10 · S/699→30 (montos CON IGV) · exclusión liquidación · sin cashback sobre cashback
- ⚠️ DECISIÓN PENDIENTE: Odoo vs BD externa (recomendación: BD externa tras interfaz, swappeable)
Servicio central (Node.js) — API REST
- OTP por WhatsApp (login sin contraseña — patrón Neira)
- Wallet: saldo, historial, progreso próximo cashback
- Canje: reservar → generar código → debitar (async en webhook)
- Webhooks Shopify (orders/paid, refunds/create, orders/cancelled)
- Poller Odoo POS (acumulación tienda)
- Google Wallet: JWT "añadir" + PATCH de saldo · Apple Wallet fase 2
Shopify (custom app + Theme 2.0)
- Cart drawer: input DNI → App Proxy → código dinámico → auto-aplicar antes del checkout
- Tag
no-cashbacken productos de liquidación - App Proxy con validación HMAC
- Cupón vía GraphQL
discountCodeAppCreate: un solo uso, vence 24h, monto = min(saldo, subtotalElegible) - Débito del cashback usado + acreditación del ganado en
orders/paid(async) - Reversiones en refunds/cancelled
Odoo POS (tienda)
- Identificación del cliente: QR del cliente (patrón Neira) o DNI/teléfono
- Cajero: panel staff (ver saldo, canjear manual, registrar venta)
- Poller: lee pos.order → aplica reglas → credita ledger
PWA Wallet (cliente)
- Login OTP WhatsApp
- Tarjeta digital + QR + saldo + barra progreso próximo cashback (no estrellas)
- Tiendas (dirección + mapa) · Configuración
- Añadir a Google Wallet
Wallets nativas
- Google Wallet: gratis (JWT + PATCH) ✅
- Apple Wallet: $99/año + cert .p12 — FASE 2
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)
- 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.
- IGV: subtotalElegible y umbrales deben calcularse con impuestos incluidos (cart.js tiene totales por línea con tax).
- 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.
- Concurrencia: reserva/bloqueo del saldo durante checkout (el informe lo menciona — es clave para doble uso).
- 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).
- 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)
- Ledger: Odoo vs BD externa (recomendación: BD externa tras interfaz)
- Identificación tienda: QR del cliente (como Neira) vs DNI
- Shopify: cart-drawer (UX completa) vs versión simple (página cuenta cliente)
- Política de cupones combinados
- Aprobación del recorte MVP semana 1
✅ Decisiones confirmadas (2026-08-05 19:54)
- Ledger: BD NUESTRA ✅ (Opción 3 confirmada — plataforma propia, replicable)
- Identificación en tienda: QR del cliente ✅ (patrón Neira — cajero escanea y pone monto)
- 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.
- Apple Wallet: info recopilada — ver abajo. Recomendación: fase 2 (Google Wallet cubre iOS).
🍎 Apple Wallet — qué se necesita (2026-08-05 19:54)
- $99/año Apple Developer Program (la parte fácil)
- Enrollment: individual = rápido · empresa = verificación DUNS que puede tardar días (14 Diez SAC → ojo)
- Pass Type ID (ej: pass.com.hoseg.cash) + certificado Pass Type ID (.p12) → se firma el .pkpass (5 min una vez enrolado)
- APNs key (opcional) para push de actualización de saldo
- Código: librería passkit-generator (Node) en nuestro servicio → 1-2 días de desarrollo
- Tiempo real depende de la cuenta Apple, no del código
- Recomendación: NO bloquear el lanzamiento — Google Wallet funciona en iPhone (vía app). Apple Wallet = fase 2.
✅ Shopify plan Basic — compatibilidad (2026-08-05 19:57)
- TODO el diseño funciona en Basic (tema OS 2.0): app block cart, App Proxy, discountCodeAppCreate (GraphQL), webhooks, custom app, fetch('/discount/CODE')
- No se necesita Plus: no usamos checkout.liquid, ni checkout UI extensions, ni Shopify Functions
- Único requisito: tema OS 2.0 (si OS 1.0 → app block va en la página del carrito, no en el drawer)
- Pendiente: confirmar versión del tema de la tienda
✅ Tema confirmado (2026-08-05 20:00)
- Tema: Act Hosegstore v2.1 (Versión 2.0.0, activo) → OS 2.0 ✅
- App block en cart drawer: SOPORTADO. Sin bloqueos en Shopify.
🔄 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
- Regla única: compra > S/299 → S/30 cashback (se simplifica; antes 299→10 / 699→30)
- Reglas configurables desde el panel admin: el admin puede añadir/modificar reglas (motor config-driven en BD)
- Sin integración Odoo: el cashback en tienda lo genera el vendedor desde su app
- 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)
- 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
- Canje en tienda: vendedor ve saldo en su app → descuento manual en Odoo POS (fuera de nuestro sistema) → marca canje en app vendedor
- Reglas: tabla
rules(min_amount, reward, activa) — motor evalúa el umbral más alto alcanzado (no acumulativo por ahora) - OTP WhatsApp: Meta Cloud API (conversaciones de autenticación = GRATIS desde nov 2024) — pendiente cuenta Meta Business + número
📱 OTP WhatsApp — opciones sin Meta Business (2026-08-05 20:24)
- A) Crear Meta Business + Cloud API (gratis, auth gratis, ~30-60min setup; número no puede estar en WhatsApp normal)
- B) Twilio Verify SMS (~$0.05-0.10/msg a Perú, integración 15min)
- C) OTP modo desarrollo para MVP semana 1 (código en panel/logs) → swap de proveedor sin tocar lógica
- Plan: C ahora (no bloquea) + A en paralelo + B como fallback
📱 Aclaración OTP (2026-08-05 20:25)
- El CLIENTE no necesita WhatsApp Business — solo WhatsApp normal (o SMS)
- WhatsApp Business es solo del lado REMITENTE (la empresa) y solo si se elige WhatsApp (Meta)
- SMS (Twilio) = sin WhatsApp Business en absoluto
- MVP: modo desarrollo (código en panel admin) → swap de proveedor después
🔐 Login SIN OTP — magic link (2026-08-05 20:28) ⭐
- Decisión propuesta: prescindir de OTP/password en el MVP — el token del QR es la identidad
- Flujo: registrar (QR→form) → link personal
hoseg.cash/w/<token>→ PWA guarda token → abre directo - Recuperación: vendedor verifica DNI en tienda → regenera link (verificación humana, costo 0)
- OTP/password = fase 2 opcional (self-service)
- Impacto: cero dependencias externas (ni Twilio ni Meta) para el lanzamiento
- Seguridad: token = credencial bearer; mitigación: device binding + límite de canjes; monto pequeño = riesgo bajo
- App stores: PWA = gratis, sin tiendas. Nativo costaría $25 Play (única) / $99 año Apple — NO necesario
🧾 FLUJO DEFINITIVO: Registro del cliente (2026-08-05 20:43)
- QR en tienda (mostrador/posters/boletas) → URL pública
hoseg.cash/registro - Formulario: nombre, apellido, DNI, teléfono, cumpleaños (validación: formato, duplicados DNI/tel → si existe, ofrecer recuperar wallet)
- Al enviar (backend):
- Crea cliente en ledger + genera token wallet (secreto) + código tarjeta visible (HC-XXXX) + contenido QR
- 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)
- 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 - Compra tienda: cliente muestra QR → app vendedor escanea → monto → regla (>299 → +S/30) → cashback acreditado → visible en wallet (async ~5min opcional)
- Recuperación (celular nuevo/perdido): vendedor verifica DNI → regenera link (verificación humana)
- 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)
- Instalar PWA NO requiere cuenta Google/Apple (Android: Chrome → Instalar · iPhone: Safari → Añadir a pantalla)
- Google Wallet SÍ requiere cuenta Google — pero es opcional y aparte de la app
🚀 PRODUCCIÓN v0.1 DESPLEGADA (2026-08-05 21:20) ✅
- Dominio: https://hoseg-cash.disoftx.solutions (Zeta, docker container
hoseg-cash, caddy reverse_proxy hoseg-cash:3010) - Presentación: https://hoseg-cash-presentacion.disoftx.solutions (flujo cliente, colores #E22B4F, logo real, botón fullscreen)
- Código:
hoseg-cash/server/(Express + better-sqlite3 + JWT + bcrypt) — data en volumen ./data - Admin: /admin · Vendedor: /vendedor (escáner QR html5-qrcode + ingreso manual) · Registro: /registro · Wallet: /w/:token
- Acceso: admin@hoseg.com / hoseg2025 (⚠️ cambiar)
- Implementado:
- Dashboard: clientes, cash añadido, cash canjeado, saldo circulante, por sucursal, por origen (tienda/web)
- Clientes: búsqueda + export CSV · Tarjetas · Usuarios (roles admin/vendedor + sucursal + activar/desactivar)
- Reglas CRUD (299→30 por defecto, motor: mayor umbral alcanzado, no acumulativo)
- Config: tag exclusión Shopify (no-cashback), store, API key/secret/token
- Webhook /webhook/shopify/orders-paid listo con verificación HMAC (pendiente credenciales reales)
- Sucursales: Larcomar, Marriott Lima, Marriott Cusco, Casa Hoseg, Cusco Plaza
- Pruebas OK: registro público → login → venta 800→+30 → canje → dashboard → webhook
- Pendiente: credenciales Shopify reales (activar webhook+app block), issuer Google Wallet (pases reales), cambiar password admin, producción de reglas de negocio finas (excluir ítems tag en webhook)
🪪 Google Wallet — botón implementado en producción (2026-08-05 21:30)
- Endpoint
GET /api/wallet/:token/gwallet→ genera JWT firmado (RS256 con service account) → link pay.google.com/gp/v/save/... - Probado local: JWT válido (class 3388...HOSEG_CASH, object con QR + saldo + nombre)
- Botón "Añadir a Google Wallet" agregado al wallet del cliente — muestra "Disponible próximamente" hasta configurar
- Admin → Config → sección Google Wallet: Issuer ID + contenido JSON del service account → al guardar, el botón se activa
- Pendiente de Daniel: pasos Google Console (issuer + service account) → pegar en admin
✅ Google Wallet CONFIGURADO (2026-08-05 23:02)
- Issuer ID: 3388000000023168817 (cuenta de pruebas Disoftx — producción: crear issuer 14 Diez SAC)
- Service account: hoseg-cash-wallet@hosegcash.iam.gserviceaccount.com (agregado en Usuarios de la consola)
- Config pegada en Admin → Config → Google Wallet (issuer + JSON en settings de la BD)
- Verificado: endpoint /api/wallet/:token/gwallet genera JWT válido (class 3388000000023168817.HOSEG_CASH, object HC-906B65, saldo S/30, QR)
- Pendiente: prueba en celular de Daniel (botón en wallet → agregar a billetera nativa)
🐛 Fix Google Wallet (2026-08-05 23:15)
- Error: "Ocurrió un error" al guardar en wallet
- Causa raíz (diagnóstico con API): LoyaltyClass requiere
reviewStatus+programLogo(campo exacto, no imageModulesData) - Fix: clase con reviewStatus UNDER_REVIEW + programLogo (logo Hoseg de hosegstore.com CDN)
- Verificado: clase 3388000000023168817.HOSEG_CASH creada vía API (HTTP 200, estado approved); JWT del botón incluye reviewStatus + programLogo
- Diag endpoint: GET /api/diag/gwallet (admin) — crea la clase vía API y reporta el error exacto de Google
🔧 Ajustes UX wallet (2026-08-05 23:40)
- Wallet: auto-refresh cada 10s + al volver a la pestaña (saldo/historial se actualizan solos)
- QR del wallet: ahora es QR REAL escaneable (npm qrcode, endpoint /api/wallet/:token/qr.png) — antes era decorativo
- Google Wallet pass: accountId = código de tarjeta (HC-XXXX), no DNI; detalles: saldo + tarjeta
- Para ver cambios en el pase: quitar de Google Wallet y re-agregar
⚡ Sync en vivo Google Wallet VERIFICADA (2026-08-05 23:50)
- Implementado: tras venta/canje, el servidor hace PATCH al loyaltyObject de Google (mismo JWT bearer del service account)
- Verificado: venta +30 → objeto Google pasó de S/0.00 a S/60.00 (HTTP 200)
- Diag extendido: /api/diag/gwallet?card=HC-XXXX muestra el saldo del objeto en Google
- Nota: el wallet PWA necesita recargar la pestaña (la versión vieja no tenía auto-refresh)
🧪 Modo demo — usuarios de prueba (2026-08-06 00:21)
- Cindy (otra cuenta Google) no puede agregar el pase: "Este pase solo se usa para pruebas. Pide acceso al administrador"
- Fix: en la consola (pay.google.com/business/console) → API de Google Wallet → agregar el Gmail como tester/usuario de prueba (límite ~10 en demo)
- El admin (Daniel) sí puede porque es dueño del emisor
- Producción real: completar Perfil de Empresa → solicitar publicación (revisión Google, días) — para cuando salga con 14 Diez SAC
📜 Historial en Google Wallet (2026-08-06 00:35)
- Limitación Google: el pase NO muestra historial completo (solo saldo/puntos/QR/mensajes)
- Implementado: pase muestra SALDO + ÚLTIMO MOVIMIENTO en vivo (messages con messageState READY, PATCH tras cada venta/canje) + link "Ver historial y canjear" → PWA con historial completo
- Verificado: mensaje "🛍️ Compra: +S/ 30.00 · 2026-08-06" presente en el objeto de Google
- Saldo de pruebas de Daniel: S/180 (resetear antes de datos reales)
🔧 Correcciones 2026-08-06 00:47 (Daniel)
- 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.
- Bug doble "S/": la tarjeta mostraba "S/ S/ 180.00" (literal HTML + prefijo del JS) → corregido (solo número en JS).
- 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) ⭐
- Entendimiento correcto: cada S/[mínimo] ACUMULADO en compras → S/[recompensa] por bloque
- Ej: regla 299→30: compra S/900 = 3 bloques → S/90 · compras 100+100+100 → +30 al llegar · sobrante se arrastra
- Implementado: columna clients.acc_sales (acumulador), bloques = floor((acc+venta)/min), reward = bloques×recompensa, sobrante = total mod min
- Admin actualizado: texto "Reglas de cashback (por bloques)" con ejemplo
- Verificado en prod: S/900 → 3 bloques → S/90
🎨 Consultas de Daniel (01:10)
- ¿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)
- ¿Clasificación por nivel de compra + cambio de color de tarjeta? → SÍ viable:
- Niveles configurables en admin (nombre, monto mínimo acumulado, color): ej Bronze/Silver/Gold
- PWA: color de tarjeta cambia según nivel + badge
- Google Wallet: una clase por nivel (cada una con su color) → el objeto se mueve entre clases vía PATCH al cambiar de nivel
- Pendiente de implementar (proponer después de estabilizar flujo actual)
🏅 NIVELES CONFIGURABLES implementados (2026-08-06 01:19)
- Tabla tiers (nombre, min_sales, color #hex) + CRUD admin (tab "Niveles": nombre, monto, color picker + hex)
- Seed: Bronce (0, #CD7F32) · Plata (1000, #9EA7AD) · Oro (3000, #D4AF37)
- Tier del cliente = según COMPRAS TOTALES de por vida (SUM sale_amount)
- Wallet: tarjeta cambia de color por nivel + badge 🏅 (verificado: Juan 1120 → Plata)
- Endpoints: GET/POST/PUT/DELETE /api/tiers (admin) · wallet incluye tier + total_sales
🔔 Notificaciones vía Google Wallet + Geofencing + TZ (2026-08-06 01:40) ✅
- 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.
- 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.
- 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.
- Hora servidor GMT-5: TZ=America/Lima en el contenedor (verificado: -05).
- Nota: demo mode limita a testers (10) — para producción completa: Perfil de Empresa + publicación.
🔔 Descubrimiento + Web Push (2026-08-06 01:45)
- Hallazgo: Google Wallet NO lanza notificación emergente al actualizar un pase (el mensaje solo aparece DENTRO de la tarjeta). Las únicas notifs automáticas de Google = ubicación (geofencing ya configurado).
- Solución implementada: Web Push en la PWA wallet (gratis, VAPID):
- Botón "🔔 Activar notificaciones" en el wallet → suscripción guardada (tabla push_subs)
- Broadcast ahora envía a DOS canales: Web Push (pop-up en celular) + mensaje en pase Google Wallet
- /api/push/vapid · /api/push/subscribe · sendPushToClient (borra subs 404/410)
- sw.js con manejo de push + click → abre wallet
- Verificado: VAPID OK, sw.js e icon servidos
- Para probar: activar notifs en wallet → broadcast → pop-up
🏪 Sucursales configurables + link wallet + saldo pase (2026-08-06 02:00)
- 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).
- 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.
- 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. - Endpoint POST /api/gwallet/sync (admin) para re-sincronizar saldos de todos los pases.
📨 addMessage (Wallet API v1) implementado (2026-08-06 02:30)
- Daniel indicó: mensajes directos con notificación = endpoint
addMessagede la Wallet API (POST /walletobjects/v1/loyaltyObject/{id}/addMessage), NO PATCH de messages (silencioso) - Implementado
gwalletAddMessage(cardCode, header, body)— appends el mensaje y dispara la notificación en el dispositivo - Broadcast y cumpleaños ahora usan addMessage · PATCH queda solo para saldo/último movimiento
- Verificado: pase de Daniel tiene los mensajes añadidos (append, no replace)
- Nota: el mensaje aparece como notificación dentro de Google Wallet (depende de notificaciones habilitadas en el celular); Web Push sigue siendo el canal para pop-ups del sistema
🔍 Diagnóstico pase + notificaciones (2026-08-06 02:40)
- accountId del pase era DNI (objeto creado antes del fix; re-agregar con mismo ID NO recrea el objeto — Google restaura el existente) → corregido vía PATCH (accountId = HC-6629F8) + sync masivo ahora incluye accountId.
- Saldo 0.00 en celular vs S/180 en API: el pase en el teléfono no se sincronizó (re-agregar con el objeto corregido en servidor lo arregla).
- Realidad de las notificaciones Google Wallet (confirmado con prueba de Daniel):
- addMessage SÍ agrega el mensaje al pase (visible en la sección de mensajes de la tarjeta) pero NO genera popup del sistema
- La única notificación automática de Google Wallet = geofencing (cerca de tienda)
- Popup reales = Web Push (botón "🔔 Activar notificaciones" en el wallet PWA)
- Broadcast envía a AMBOS canales: Web Push (popup) + addMessage (mensaje en pase)
📨 Ciclo de vida de mensajes Google Wallet (2026-08-06 02:50) — implementado
- displayInterval: formato correcto =
start/endcon{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. - Límite de mensajes: cleanup conserva máx 3 (2 más recientes + nuevo) — Google limita push a 3/24h por pase.
- messageType: "TEXT_AND_NOTIFY" → mensaje en el pase + NOTIFICACIÓN PUSH real al celular (verificado: se guarda como textAndNotify).
- ⚠️ 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)
- Daniel recibió la notificación en su Android: "New message — Press to see the pass" (billetera)
- El canal completo funciona: Notificar a todos (push+pase con expiración) · Cumpleaños · Geofencing · Saldo en vivo
- Nota: el texto del popup lo controla Google ("New message"); el contenido está en el pase
🐛 Fix: "Cashback 0" en la PARTE POSTERIOR del pase (2026-08-06 02:55)
- Causa: la parte posterior muestra los
textModulesData— el módulo "Cashback disponible" se creó con S/0.00 y NUNCA se actualizaba (solo se actualizaba loyaltyPoints) - Fix: gwalletPatchBalance y /api/gwallet/sync ahora incluyen textModulesData con el saldo actualizado en cada venta/canje
- Verificado: textModules = "Cashback disponible = S/ 180.00" en el objeto
- El teléfono necesita refrescar el pase (deslizar hacia abajo / reabrir / re-agregar)
🎨 Pase Google Wallet con COLOR POR NIVEL (2026-08-06 03:05)
- Implementado: una clase de loyalty POR NIVEL (HOSEG_CASH_{NOMBRE}) con su hexBackgroundColor
- helpers: gwalletTierClassId / gwalletTierClassDef / gwalletEnsureTierClasses (crea/actualiza clases en Google)
- El objeto se mueve entre clases vía PATCH classId (en venta/canje/sync) → el color cambia solo al subir de nivel
- Al editar un nivel en admin → se actualiza el color de la clase
- Verificado: clases Bronce/Oro/Diamante/"Spreading warmth" creadas; pase de Daniel → clase SPREADING_WARMSTH (rosa #e01fda)
- Nota: rewardTier no se guardó (undefined) — el color sí; revisar si se quiere mostrar el nombre del nivel en el pase
- Niveles actuales en prod (definidos por Daniel): Bronce #CD7F32, Oro #D4AF37, Diamante #4FC3F7, "Spreading warmth" #E01FDA
🏷️ Nivel en el pase + capacidades (2026-08-06 03:10)
rewardTierNO existe en LoyaltyClass v1 (Google lo ignora) → el nivel se muestra vía textModule "Nivel" (verificado en pase: "Nivel = Spreading warmsth")- Capacidades del pase (todo lo que se puede agregar): color por clase, programLogo, heroImage (imageModulesData), textModulesData (datos clave), messages (promos con expiración+push), linksModuleData (botones), locations (geofencing), barcode QR, validTimeInterval (validez), groupingInfo (agrupación), displayInterval (mensajes temporales)
- Pendiente de diseño: Daniel pasará diseño del pase (color/logo/imágenes) cuando lo tenga
🔗 Redes sociales + nivel en el FRENTE del pase (2026-08-06 03:15)
- Nivel en el frente: el label del saldo ahora incluye el nivel: "Spreading warmsth · Cashback" (el frente muestra label+saldo; rewardTier no existe en la API)
- Botones de redes (linksModuleData): 📸 Instagram · 👍 Facebook · 🎵 TikTok · 𝕏 X · 🌐 Web — tappables (abren la app/red directo). Google no permite logos por link → se usan emojis en la descripción
- Admin → Config → "Redes sociales": 5 campos configurables (dejar vacío = no se muestra). Al guardar + sync → se actualiza el pase
- Verificado: label + 6 links en el objeto (5 redes + Ver historial)
- Links de prueba puestos: @hosegstore (Daniel debe verificar/corregir en admin)
🖼️ Imagen HERO en el frente del pase (2026-08-06 03:20)
- imageModulesData (mainImage) con banner generado (1200x600, gradiente rosa, "Hoseg Cash — Acumula cashback")
- Configurable desde admin: campo "Imagen principal del pase (URL)" (setting gwallet_hero) — la diseñadora puede cambiar el banner sin tocar código
- Detalle API: contentDescription requiere
language(TranslatedString) — "Language cannot be empty" - FRENTE del pase (máximo configurable): color por nivel · logo · nombre · label con nivel ("Spreading warmth · Cashback") · IMAGEN HERO · QR · callout de mensajes
- ATRÁS (layout fijo Google): redes sociales, módulos de texto, botón historial
- Banner actual: placeholder — diseñadora debe pasar el definitivo