Add README.md for WhatsApp promotion system documentation

2026-05-09 11:30:21 -04:00
parent 232facf1e8
commit 44078a8ffd
1 changed files with 337 additions and 0 deletions
@@ -0,0 +1,337 @@
+# Promoción por WhatsApp
+
+Sistema automatizado de promoción vía WhatsApp utilizando n8n, Supabase y WhatsApp Cloud API.
+
+---
+
+# Descripción General
+
+Este flujo administra la interacción completa con usuarios mediante WhatsApp para registrar participantes en una promoción.
+
+Incluye:
+
+- Validación de mensajes entrantes
+- Gestión de consentimiento de privacidad y marketing
+- Registro de información del usuario
+- Validación y registro de códigos de productos
+- Control de estados del usuario
+- Prevención de fraude y spam
+
+---
+
+# Tecnologías Utilizadas
+
+- n8n
+- Supabase
+- PostgreSQL
+- WhatsApp Cloud API
+
+---
+
+# Arquitectura del Flujo
+
+El sistema funciona mediante una máquina de estados (`state machine`) donde cada usuario tiene un estado actual que determina la siguiente acción del flujo.
+
+## Estados Disponibles
+
+- `CONSENT_PRIVACY`
+- `CONSENT_MARKETING`
+- `ASK_NAME`
+- `ASK_ID`
+- `ASK_EMAIL`
+- `ASK_LOCATION`
+- `ASK_CODE`
+- `MENU_AFTER_CODE`
+- `DONE`
+
+---
+
+# Flujo General
+
+## 1. Recepción y Normalización
+
+El flujo recibe mensajes desde WhatsApp y:
+
+- Extrae el contenido del mensaje
+- Detecta el tipo de mensaje:
+  - Texto
+  - Imagen
+  - Interactivo
+- Normaliza caracteres y acentos
+- Filtra números bloqueados
+
+---
+
+## 2. Validación Inicial
+
+Si el mensaje no contiene contenido válido:
+
+- El flujo se detiene automáticamente
+
+---
+
+## 3. Creación o Consulta del Usuario
+
+Se ejecuta la función RPC:
+
+```sql
+ensure_user_wa
+```
+
+Esta función:
+
+- Crea el usuario si no existe
+- Consulta el estado actual del usuario
+- Devuelve `out_state`
+
+---
+
+# Router de Estados
+
+Según el valor de `out_state`, el flujo dirige al usuario a la etapa correspondiente.
+
+| Estado            | Acción                             |
+| ----------------- | ---------------------------------- |
+| CONSENT_PRIVACY   | Solicitar aceptación de privacidad |
+| CONSENT_MARKETING | Solicitar consentimiento marketing |
+| ASK_NAME          | Solicitar nombre completo          |
+| ASK_ID            | Solicitar identificación           |
+| ASK_EMAIL         | Solicitar correo electrónico       |
+| ASK_LOCATION      | Solicitar ubicación                |
+| ASK_CODE          | Solicitar código del producto      |
+| MENU_AFTER_CODE   | Mostrar menú posterior             |
+| DONE              | Finalizar flujo                    |
+
+---
+
+# Consentimientos
+
+## Consentimiento de Privacidad
+
+El usuario puede responder:
+
+- `SI`
+- `NO`
+
+### Comportamiento
+
+- `SI` → continúa el flujo
+- `NO` → se detiene el avance
+
+### RPC utilizada
+
+```sql
+set_consent_privacy_wa
+```
+
+---
+
+## Consentimiento de Marketing
+
+El usuario puede responder:
+
+- `SI`
+- `NO`
+
+### Comportamiento
+
+- `SI` → opt-in marketing
+- `NO` → opt-out marketing
+
+### RPC utilizada
+
+```sql
+set_consent_marketing_wa
+```
+
+---
+
+# Captura de Datos
+
+## Nombre
+
+### Validaciones
+
+- Mínimo 6 caracteres
+- Debe contener al menos 2 palabras
+- Solo letras permitidas
+
+### RPC
+
+```sql
+set_name_wa
+```
+
+---
+
+## Identificación
+
+### Validaciones
+
+- Campo obligatorio
+- No vacío
+
+### RPC
+
+```sql
+set_id_wa
+```
+
+---
+
+## Email
+
+### Opciones permitidas
+
+- Correo válido
+- `NO` para omitir
+
+### Validación
+
+Se utiliza validación mediante regex para verificar formato email.
+
+### RPC
+
+```sql
+set_email_wa
+```
+
+---
+
+## Ubicación
+
+### Validación
+
+- Debe pertenecer a una lista cerrada de departamentos
+
+### RPC
+
+```sql
+set_location_wa
+```
+
+---
+
+# Registro de Códigos
+
+## Formato del Código
+
+El sistema valida códigos con la siguiente estructura:
+
+- 4 números
+- 1 letra
+- 3 números
+- marcador (`C`, `S`, `M`, `T`)
+- 1 número
+
+### Ejemplo
+
+```txt
+1234A567C9
+```
+
+---
+
+## Registro del Código
+
+### RPC utilizada
+
+```sql
+register_lot_code
+```
+
+---
+
+## Posibles Respuestas
+
+| Respuesta             | Descripción                               |
+| --------------------- | ----------------------------------------- |
+| ❌ Código inválido    | Formato incorrecto                        |
+| ⚠️ Código duplicado   | Código ya registrado                      |
+| 🚫 Límite diario      | Usuario alcanzó límite                    |
+| 🚫 Bloqueo por fraude | Detección antifraude                      |
+| 🎉 Código exitoso     | Registro correcto y generación de cupones |
+
+---
+
+# Menú Posterior al Registro
+
+Después de registrar un código, el usuario puede elegir:
+
+1. Seguir ingresando códigos
+2. Salir
+
+## Opción 1
+
+El estado cambia a:
+
+```txt
+ASK_CODE
+```
+
+## Opción 2
+
+El estado cambia a:
+
+```txt
+DONE
+```
+
+---
+
+# Reinicio del Flujo
+
+Si el usuario envía alguno de estos mensajes:
+
+- `hola`
+- `buenas`
+- `hello`
+
+El sistema reinicia el flujo mediante:
+
+```sql
+restart_wa
+```
+
+---
+
+# Tipos de Mensajes
+
+El flujo soporta:
+
+- Texto simple
+- Botones interactivos
+- Listas interactivas
+
+---
+
+# API Utilizada
+
+- WhatsApp Cloud API
+
+---
+
+# Características Técnicas
+
+- Arquitectura basada en estados
+- Integración con Supabase mediante RPC
+- Manejo intensivo de nodos `Code`
+- Normalización de texto y caracteres
+- Sistema antifraude
+- Validaciones avanzadas
+- Manejo de errores
+
+---
+
+# Estructura del Proyecto
+
+```txt
+Base de datos Supabase/
+├── Base de datos Postgre Presto.txt
+├── Triggers.png
+└── pg-dump-postgres1-1776492006.dmp
+
+Flujo n8n/
+├── Flujo WhatsApp.docx
+└── Flujo con WSP.json
+```