Saltar al contenido principal

LealtiApp: Guía de Procesos para Colaboradores No Técnicos

1. Para quién es este documento​

Esta guía está pensada para personas que colaboran con el proyecto sin programar directamente, por ejemplo:

  • operaciones
  • soporte
  • producto
  • QA manual
  • account management
  • dirección comercial
  • partners de implementación

Su objetivo es explicar cómo trabajar con el sistema, qué revisar antes de liberar cambios y qué información conviene entregar al equipo técnico cuando algo falla.

2. Qué hace LealtiApp​

LealtiApp permite que un comercio opere un programa de lealtad propio bajo su subdominio.

Cada comercio puede:

  • registrar visitas de clientes
  • asignar puntos
  • ofrecer recompensas
  • crear promociones y reglas
  • definir niveles de lealtad
  • invitar staff
  • exportar información y revisar auditoría

Cada cliente final puede:

  • iniciar sesión con su teléfono
  • ver sus puntos y nivel
  • escanear QR
  • ver historial
  • canjear recompensas
  • actualizar su perfil
  • usar wallet digital si está activada

3. Cómo está dividido el producto​

Sitio público​

Sirve para:

  • ver marketing
  • revisar pricing y recursos
  • crear un nuevo comercio

Panel administrativo del comercio​

Sirve para:

  • operar el programa
  • registrar visitas
  • gestionar equipo
  • revisar clientes
  • crear y canjear recompensas
  • cambiar configuración

App del cliente final​

Sirve para:

  • consultar estado del cliente
  • escanear visitas
  • ver recompensas activas
  • administrar perfil

4. Lenguaje común del proyecto​

Para evitar confusiones, conviene usar estos términos siempre igual:

  • tenant: un comercio o marca dentro de la plataforma
  • owner: responsable principal del comercio
  • staff: personas del comercio con acceso administrativo
  • customer: cliente final del comercio
  • branch: sucursal
  • visit: visita registrada
  • reward: recompensa del catálogo
  • customer reward: recompensa ya emitida a un cliente
  • redeemable points: puntos que el cliente puede gastar
  • qualifying points: puntos que cuentan para subir de nivel
  • rule: regla promocional que modifica puntos o genera recompensas

5. Procesos operativos principales​

5.1 Alta de un nuevo comercio​

Qué ocurre:

  1. Se crea el comercio desde /signup.
  2. El sistema crea el subdominio.
  3. Se crea el usuario owner.
  4. Se envía un correo con magic link.
  5. Se cargan una sucursal, niveles y reglas base.

Qué debe revisar una persona no técnica:

  • que el correo del owner sea correcto
  • que el subdominio tenga el formato esperado
  • que el owner reciba el email
  • que el link lleve al panel correcto del comercio

Si falla, enviar al equipo técnico:

  • nombre del negocio
  • email usado
  • subdominio esperado
  • fecha y hora aproximada
  • captura del error o texto exacto

5.2 Alta de clientes​

Qué ocurre:

  • el cliente entra al subdominio del comercio
  • inicia sesión con OTP a su teléfono
  • al verificarlo, se crea su perfil mínimo automáticamente

Qué revisar:

  • que el OTP llegue
  • que el cliente no termine en el tenant incorrecto
  • que al entrar vea su panel de cliente

5.3 Registro de visitas​

Hay tres formas:

  • el cliente escanea QR de sucursal
  • el staff escanea QR del cliente
  • el staff registra la visita manualmente

Qué revisar:

  • que la visita quede en la sucursal correcta
  • que los puntos sumados sean razonables
  • que el cliente vea reflejado el cambio
  • que no se dupliquen visitas por error

5.4 Canje de recompensas​

Flujo normal:

  1. El cliente canjea desde su app.
  2. El sistema descuenta puntos.
  3. Se genera un cupón o recompensa activa.
  4. El staff la consume en POS cuando corresponda.

Qué revisar:

  • que el cliente tenga puntos suficientes
  • que la recompensa esté activa
  • que el cupón cambie a usado cuando se consume

5.5 Gestión de equipo​

Desde el panel se puede:

  • invitar staff
  • reenviar acceso
  • editar datos
  • eliminar acceso según permisos

Qué revisar:

  • que cada persona tenga el rol correcto
  • que solo personas autorizadas puedan ver áreas sensibles
  • que los nuevos accesos lleguen al tenant correcto

6. Rutina recomendada antes de liberar cambios​

La persona de producto, operaciones o QA manual debería validar como mínimo:

  1. signup de un comercio nuevo
  2. login admin por magic link
  3. login cliente por OTP
  4. registro de visita
  5. canje de recompensa
  6. cancelación de visita si aplica al cambio
  7. exportación o vista afectada por el cambio
  8. wallet si la funcionalidad estaba involucrada

Check rápido obligatorio:

  • el tenant correcto aparece en toda la navegación
  • no hay mensajes de “Subdominio inválido”
  • no hay mezcla de datos entre comercios
  • los correos y accesos entran al host correcto

7. Cómo reportar incidencias bien​

Cuando se reporte un problema al equipo técnico, evitar frases como “no sirve” o “está roto”. El reporte mínimo debería incluir:

  • tenant afectado
  • URL exacta
  • usuario afectado: owner, staff o cliente
  • acción intentada
  • resultado esperado
  • resultado real
  • fecha y hora
  • si fue constante o intermitente
  • captura de pantalla o video corto

Ejemplo útil:

Tenant: taqueria-demo
URL: https://taqueria-demo.lealtia.app/admin/staff
Usuario: owner@demo.com
Acción: reenviar invitación a staff
Esperado: envío de magic link al correo del staff
Real: aparece mensaje "Error interno del servidor"
Hora: 2026-04-04 11:32 Europe/Madrid

8. Qué hacer cuando algo falla​

Si falla el acceso del staff​

Revisar primero:

  • email correcto
  • si el comercio existe
  • si el enlace abre el subdominio correcto

Escalar a técnico si:

  • el correo nunca llega
  • el link lleva al dominio raíz y no al tenant
  • el usuario entra pero no ve el panel

Si falla el acceso del cliente​

Revisar:

  • teléfono correcto
  • si el OTP llegó
  • si el cliente está entrando desde el subdominio correcto

Escalar si:

  • no llega OTP repetidamente
  • el cliente entra a otro tenant
  • el perfil no se crea tras verificar teléfono

Si fallan puntos o niveles​

Revisar:

  • si la visita se registró
  • si la regla promocional esperada estaba activa
  • si el cambio afecta solo puntos gastables o también puntos de nivel

Escalar con:

  • customer
  • branch
  • monto de cuenta si existía
  • puntos esperados y puntos reales

Si falla PassKit / wallet​

Revisar:

  • si el tenant tenía la wallet configurada
  • si el cliente ya estaba enrolado
  • si el error fue al alta o en una actualización posterior

9. Buenas prácticas para trabajar con el equipo técnico​

  • Definir siempre si el cambio es por tenant específico o global.
  • Separar claramente “bug”, “mejora” y “cambio de proceso”.
  • No mezclar varios problemas distintos en el mismo ticket.
  • Si un bug afecta datos, avisarlo como prioridad alta.
  • Si un cambio impacta operación diaria, pedir checklist de smoke antes de liberar.

10. Buenas prácticas para demos, onboarding y soporte​

  • Usar un tenant demo para pruebas comerciales.
  • No usar producción para experimentar reglas nuevas.
  • Antes de una demo, verificar:
    • acceso del owner
    • cliente demo con puntos
    • recompensas activas
    • al menos una sucursal operativa
  • Después de una configuración importante, validar una visita real de punta a punta.

11. Cuándo involucrar al equipo técnico de inmediato​

Escalar sin esperar si ocurre cualquiera de estos casos:

  • usuarios viendo datos de otro comercio
  • links de acceso llegando al dominio incorrecto
  • imposibilidad de registrar visitas
  • canjes descontando puntos de forma incorrecta
  • errores masivos en login
  • exports vacíos o corruptos en producción
  • fallos repetidos de wallet después de cambios recientes

12. Checklist operativo por rol​

Producto​

  • definir objetivo del cambio
  • listar flujo afectado
  • definir criterio de aceptación observable
  • pedir validación multi-tenant cuando corresponda

QA manual​

  • probar caso feliz
  • probar caso negativo
  • probar con tenant correcto
  • validar mensajes visibles para usuario

Operaciones / soporte​

  • confirmar tenant, usuario y hora
  • intentar reproducir
  • recopilar evidencia
  • escalar con contexto completo

Comercial / onboarding​

  • confirmar datos del owner
  • confirmar subdominio
  • verificar recepción del acceso
  • acompañar primera entrada al panel

13. Cambios que requieren doble validación​

Pedir siempre validación funcional y técnica si el cambio toca:

  • login por email o OTP
  • subdominios o dominios
  • registro de visitas
  • puntos, niveles o reglas
  • recompensas y canjes
  • exports
  • wallet / PassKit
  • cron o automatizaciones

14. Qué no asumir​

  • que todos los errores son visuales; muchos son de contexto tenant
  • que puntos y niveles son lo mismo
  • que una recompensa canjeada ya está consumida
  • que un owner y un staff tienen el mismo alcance
  • que un problema en un tenant afecta a todos

15. Resumen práctico​

Para colaborar bien sin tocar código, hay tres hábitos que más ayudan:

  1. reportar siempre con tenant, usuario, URL y hora
  2. validar los flujos completos, no solo una pantalla aislada
  3. tratar auth, puntos y multitenancy como áreas críticas

Con eso, el equipo técnico puede diagnosticar más rápido y se reduce mucho el riesgo de liberar cambios incompletos.