🚀 Marketing Attribution Bot

Sistema completo de atribución de marketing digital que combina un bot de Telegram para captura de leads, integración con Meta Conversions API (Facebook), y un panel administrativo React para gestión y difusión masiva de mensajes.

📋 Descripción

Este proyecto cierra la brecha entre la inversión publicitaria y el dato real mediante un sistema Servidor-a-Servidor (S2S) que garantiza que cada usuario que interactúa con nuestra publicidad sea atribuido correctamente a la campaña que lo atrajo.

🏗️ Arquitectura

marketing-attribution-bot/
├── 📁 backend/          # API Node.js + Bot Telegram
│   ├── src/            # Código fuente
│   ├── data/           # Base de datos SQLite
│   └── scripts/        # Utilidades (simulate, clean, test)
├── 📁 frontend/         # Panel administrativo React
│   ├── src/            # Componentes React
│   └── build/          # Build de producción
└── 📄 package.json     # Scripts de orquestación

✨ Características

🤖 Bot de Telegram

• Registro automático de usuarios con validación de teléfono
• Sistema de comandos interactivo (/start, /help, /status)
• Sistema de bonos automático
• Broadcast masivo con rate limiting

📊 Panel Administrativo

• Dashboard con estadísticas en tiempo real
• Gestión de usuarios con paginación y búsqueda
• Sistema de broadcast masivo
• Autenticación JWT segura
• Interfaz responsive

🗄️ Base de Datos

• SQLite optimizada con esquema normalizado
• Hashing seguro de datos sensibles
• Timestamps automáticos y auditoría

📡 Integración Meta CAPI

• Tracking automático de eventos de conversión
• Envío de datos hasheados a Meta Pixel
• Modo de prueba configurable

🚀 Instalación Rápida

Prerrequisitos

• Node.js 16+
• npm 8+
• Token de Telegram Bot
• Meta Access Token (opcional)

1. Clonar e Instalar

git clone https://github.com/your-username/marketing-attribution-bot.git
cd marketing-attribution-bot
npm install

2. Configurar Variables de Entorno

# Backend
cp backend/.env.example backend/.env
# Editar backend/.env con tus credenciales

# Frontend (opcional)
cp frontend/.env.example frontend/.env

3. Iniciar Sistema

# Desarrollo - Backend y Frontend por separado
npm run dev          # Backend en puerto 3000
npm run frontend     # Frontend en puerto 3001

# Producción - Sistema completo
npm start            # Backend + Frontend build

🎮 Scripts Disponibles

Sistema Principal

npm start            # Iniciar backend (producción)
npm run dev          # Desarrollo backend
npm run frontend     # Desarrollo frontend
npm run build        # Build frontend para producción
npm test             # Test del sistema

Utilidades de Base de Datos

npm run simulate 100    # Generar 100 usuarios fake
npm run clean:fake      # Limpiar usuarios fake
npm run clean:all       # Limpiar toda la DB
npm run clean:codes     # Limpiar solo códigos
npm run clean:reset     # Reset completo

📁 Estructura Detallada

Backend (/backend)

backend/
├── src/
│   ├── index.js        # Aplicación principal
│   ├── bot.js          # Bot de Telegram
│   ├── server.js       # Servidor Express
│   ├── db.js           # Base de datos
│   ├── security.js     # Seguridad y JWT
│   ├── metaService.js  # Integración Meta CAPI
│   └── bonus.js        # Sistema de bonos
├── data/               # Base de datos SQLite
├── simulate-users.js   # Generador de usuarios
├── clean-db.js         # Limpieza de DB
└── test-system.js      # Test del sistema

Frontend (/frontend)

frontend/
├── src/
│   ├── components/
│   │   ├── Login.js    # Autenticación
│   │   └── Dashboard.js # Panel principal
│   ├── App.js          # Componente raíz
│   └── App.css         # Estilos
└── build/              # Build de producción

🌐 API Endpoints

• POST /api/login - Autenticación admin
• GET /api/stats - Estadísticas del sistema
• GET /api/users - Lista de usuarios (paginada)
• POST /api/broadcast - Envío masivo
• GET /api/health - Health check

🔒 Seguridad

• Hashing SHA-256 para teléfonos
• JWT Authentication para admin
• Rate limiting en broadcast
• Input validation en todos los endpoints
• CORS configurado

📈 Monitoreo

Métricas Clave

• Usuarios registrados por día
• Tasa de conversión de registro
• Errores de broadcast
• Uso de códigos de bono

Health Checks

curl http://localhost:3000/api/health
npm test

🚀 Despliegue

Desarrollo

npm run dev          # Backend
npm run frontend     # Frontend (puerto 3001)

Producción

npm run build        # Build frontend
npm start            # Iniciar sistema completo