sales-bot-stacks/sales-bot/README.md

Sales Bot

Sistema de automatizacion de ventas para Mattermost con procesamiento OCR, analytics avanzados, reportes PDF y PWA.

Caracteristicas

• Bot de Mattermost: Registro de ventas via chat con confirmacion
• OCR Inteligente: Extraccion automatica de datos de tickets con preprocesamiento adaptativo
• Dashboard PWA: Aplicacion web instalable con soporte offline
• Analytics: Graficas interactivas, predicciones y comparativas
• Reportes PDF: Generacion automatica de reportes diarios y ejecutivos
• Sistema de Comisiones: Calculo automatico con bonos por racha
• Notificaciones Programadas: Recordatorios y resumenes automaticos

Arquitectura

sales-bot/
├── app.py                 # Aplicacion Flask principal
├── handlers.py            # Manejadores de eventos de ventas
├── mattermost_client.py   # Cliente API Mattermost
├── nocodb_client.py       # Cliente API NocoDB
├── websocket_listener.py  # Listener tiempo real
├── scheduler.py           # Tareas programadas
├── utils.py               # Utilidades
├── export_utils.py        # Exportacion Excel/CSV
│
├── analytics/             # Modulo de analytics
│   ├── __init__.py
│   ├── predictions.py     # Predicciones ML (promedio movil + regresion)
│   ├── trends.py          # Analisis de tendencias
│   └── comparisons.py     # Comparativas temporales
│
├── reports/               # Modulo de reportes PDF
│   ├── __init__.py
│   └── pdf_generator.py   # Generador con ReportLab
│
├── ocr/                   # Modulo OCR mejorado
│   ├── __init__.py
│   ├── processor.py       # Procesador principal
│   ├── preprocessor.py    # Preprocesamiento adaptativo
│   ├── patterns.py        # Patrones de tickets
│   └── amount_detector.py # Detector de montos
│
├── templates/             # Templates HTML
│   ├── base.html          # Template base con navbar
│   ├── dashboard.html     # Dashboard principal
│   ├── analytics.html     # Dashboard analytics
│   └── executive.html     # Dashboard ejecutivo
│
├── static/                # Archivos estaticos
│   ├── css/main.css       # Estilos principales
│   ├── js/
│   │   ├── app.js         # Logica principal
│   │   ├── charts.js      # Integracion Chart.js
│   │   ├── camera.js      # Captura de camara
│   │   └── pwa.js         # Service Worker
│   ├── manifest.json      # Manifest PWA
│   └── service-worker.js  # Cache offline
│
├── compose.yaml           # Docker Compose
├── Dockerfile             # Imagen Docker
├── requirements.txt       # Dependencias Python
└── .env.example           # Variables de entorno ejemplo

Instalacion

Con Docker (Recomendado)

# Clonar repositorio
git clone https://git.consultoria-as.com/consultoria-as/sales-bot-stacks.git
cd sales-bot-stacks/sales-bot

# Configurar variables de entorno
cp .env.example .env
nano .env  # Editar con tus credenciales

# Construir e iniciar
docker compose build
docker compose up -d

# Verificar
curl http://localhost:5000/health

Instalacion Manual

# Instalar Tesseract OCR
apt-get update
apt-get install -y tesseract-ocr tesseract-ocr-spa tesseract-ocr-eng

# Instalar dependencias Python
pip install -r requirements.txt

# Configurar variables
cp .env.example .env
nano .env

# Ejecutar
python app.py

Configuracion

Variables de Entorno

Variable	Descripcion	Ejemplo
Mattermost
MATTERMOST_URL	URL de Mattermost	http://192.168.10.204:8065
MATTERMOST_BOT_TOKEN	Token del bot	abc123...
MATTERMOST_TEAM_NAME	Nombre del equipo	sales
MATTERMOST_WEBHOOK_SECRET	Secret del webhook	xyz789...
NocoDB
NOCODB_URL	URL de NocoDB	http://192.168.10.204:8080
NOCODB_TOKEN	Token de API	abc123...
NOCODB_TABLE_VENDEDORES	ID tabla vendedores	tbl_xxx
NOCODB_TABLE_VENTAS	ID tabla ventas	tbl_xxx
NOCODB_TABLE_VENTAS_DETALLE	ID tabla detalles	tbl_xxx
NOCODB_TABLE_METAS	ID tabla metas	tbl_xxx
Flask
FLASK_PORT	Puerto del servidor	5000
FLASK_DEBUG	Modo debug	False
Scheduler
SCHEDULER_ENABLED	Habilitar tareas	True
RECORDATORIO_MEDIODIA_HORA	Hora recordatorio	12
RESUMEN_DIARIO_HORA	Hora resumen diario	18
Comisiones
META_DIARIA_TUBOS_DEFAULT	Meta diaria tubos	3
COMISION_POR_TUBO_DEFAULT	Comision por tubo	10
BONUS_3_DIAS	Bonus 3 dias racha	20
BONUS_5_DIAS	Bonus 5 dias racha	50
BONUS_10_DIAS	Bonus 10 dias racha	150
OCR
OCR_ENABLE_DESKEW	Correccion rotacion	true
OCR_MAX_ROTATION_ANGLE	Angulo max rotacion	15
OCR_CONFIDENCE_THRESHOLD	Umbral confianza	0.6
OCR_USE_ADAPTIVE_PIPELINE	Pipeline adaptativo	true
Reportes
REPORTS_OUTPUT_DIR	Directorio reportes	/app/reports
SCHEDULED_PDF_REPORT_ENABLED	PDF automatico	true
SCHEDULED_PDF_REPORT_HOUR	Hora PDF diario	18

Uso

Dashboard Web

Accede al dashboard en: http://tu-servidor:5000/dashboard

Funcionalidades del Dashboard:

• KPIs en tiempo real (ventas hoy/mes, vendedores activos)
• Grafica de tendencias (7/14/30 dias) con predicciones
• Comparativas semanales y mensuales
• Ranking de vendedores con tubos y comisiones
• Tabla de Top Performers con % de meta
• Generacion de reportes PDF
• Captura de tickets desde camara (mobile)

PWA (Progressive Web App):

• Instalable en celular desde Chrome/Safari
• Funciona offline con datos cacheados
• Notificaciones push (futuro)

Comandos de Mattermost

Comandos Basicos:

/metas          - Ver tu progreso del mes
/ranking        - Ver ranking de vendedores
/ayuda          - Mostrar ayuda completa

Comandos de Gestion:

/cancelar <id> [motivo]              - Cancelar una venta
/editar <id> @monto X @cliente Y     - Editar una venta
/deshacer                            - Deshacer ultima venta (5 min)

Comandos de Comisiones:

/comisiones     - Ver historial de comisiones
/racha          - Ver racha actual y bonos
/exportar [csv] [mes]  - Exportar ventas a Excel/CSV

Comandos de Reportes:

/reporte diario     - Generar PDF del dia
/reporte semanal    - Generar PDF de la semana
/reporte ejecutivo  - Generar PDF ejecutivo

Registro de Ventas

Formatos Soportados:

# Formato con @
venta @monto 1500 @cliente Juan Perez @tubos 5

# Formato con etiquetas
venta monto: 1500 cliente: Juan

# Formato natural
venta $1,500 a Juan Perez

# Con foto de ticket (OCR automatico)
[Adjuntar imagen del ticket]

Flujo de Confirmacion:

1. Envias mensaje de venta o foto de ticket
2. El bot muestra preview con datos extraidos
3. Respondes si para confirmar o no para cancelar
4. Timeout de 2 minutos si no respondes

API Endpoints

Dashboard

Metodo	Endpoint	Descripcion
GET	/dashboard	Dashboard principal
GET	/dashboard/analytics	Dashboard analytics
GET	/dashboard/executive	Dashboard ejecutivo

API Dashboard

Metodo	Endpoint	Descripcion
GET	/api/dashboard/resumen	KPIs del dia y mes
GET	/api/dashboard/ranking	Ranking vendedores
GET	/api/dashboard/ventas-recientes	Ultimas ventas
GET	/api/dashboard/metas	Estado de metas

API Analytics

Metodo	Endpoint	Params	Descripcion
GET	/api/analytics/trends	days, vendedor	Tendencias de ventas
GET	/api/analytics/predictions	days, predict	Predicciones ML
GET	/api/analytics/comparisons	type (weekly/monthly/yearly)	Comparativas
GET	/api/analytics/performance/<username>	-	Rendimiento vendedor

API Reportes

Metodo	Endpoint	Body	Descripcion
POST	/api/reports/generate	{type, vendedor}	Generar PDF
GET	/api/reports/download/<id>	-	Descargar PDF

API OCR

Metodo	Endpoint	Body	Descripcion
POST	/api/capture/ticket	{image, user_name}	Procesar ticket base64

Webhooks

Metodo	Endpoint	Descripcion
POST	/webhook/mattermost	Webhook saliente Mattermost
POST	/webhook/nocodb	Webhook NocoDB

Comandos Slash

Metodo	Endpoint	Descripcion
POST	/comando/metas	Comando /metas
POST	/comando/ranking	Comando /ranking
POST	/comando/ayuda	Comando /ayuda
POST	/comando/cancelar	Comando /cancelar
POST	/comando/editar	Comando /editar
POST	/comando/deshacer	Comando /deshacer
POST	/comando/comisiones	Comando /comisiones
POST	/comando/racha	Comando /racha
POST	/comando/exportar	Comando /exportar
POST	/comando/reporte	Comando /reporte

Utilidades

Metodo	Endpoint	Descripcion
GET	/health	Health check
GET	/manifest.json	PWA manifest
GET	/service-worker.js	Service worker
POST	/reporte/diario	Generar reporte manual
GET	/test/mattermost	Test conexion Mattermost
GET	/test/nocodb	Test conexion NocoDB

Sistema de Comisiones

Calculo de Comisiones

Meta diaria: 3 tubos
Comision: $10 por tubo despues de meta

Ejemplo:
- Vendiste 7 tubos
- Tubos comisionables: 7 - 3 = 4
- Comision: 4 x $10 = $40

Bonos por Racha

Dias Consecutivos	Bonus
3 dias	$20
5 dias	$50
10 dias	$150

Niveles de Racha

• CONSTRUYENDO: 0-2 dias
• RACHA ACTIVA: 3-4 dias
• EN FUEGO: 5-9 dias
• LEGENDARIO: 10+ dias

OCR - Procesamiento de Tickets

Formatos Soportados

• OXXO
• Walmart / Bodega Aurrera
• Soriana
• 7-Eleven
• Farmacias (Guadalajara, Similares, etc.)
• Tiendas de pintura/tinte (Cromatique, etc.)
• Tickets genericos

Preprocesamiento Adaptativo

El sistema detecta automaticamente la mejor configuracion:

• Standard: Tickets con buena iluminacion
• Low Contrast: Tickets deslavados
• Noisy: Tickets con ruido/manchas
• Rotated: Tickets inclinados (hasta 15 grados)
• Dark: Tickets oscuros
• Light: Tickets sobreexpuestos

Patrones de Monto Detectados

1. TOTAL A PAGAR: $X,XXX.XX
2. GRAN TOTAL: $X,XXX.XX
3. TOTAL: $X,XXX.XX
4. IMPORTE: $X,XXX.XX
5. A COBRAR: $X,XXX.XX
6. SUMA: $X,XXX.XX
7. SUBTOTAL: $X,XXX.XX

Marcas de Tinte Reconocidas

• Alfaparf Evolution
• Wella Koleston
• Loreal Majirel
• Matrix SoColor
• Schwarzkopf Igora
• Revlon
• Cromatique

Analytics y Predicciones

Algoritmo de Prediccion

Combina dos metodos:

1. Promedio Movil: Ultimos 7 dias
2. Regresion Lineal: Tendencia historica

prediccion = (promedio_movil + prediccion_lineal) / 2

Metricas Disponibles

• Tendencia: Increasing / Stable / Decreasing
• Confianza: 0-100% (basado en R-squared)
• Predicciones: Siguiente dia, 3 dias, semana

Comparativas

• Semanal: Esta semana vs anterior
• Mensual: Este mes vs anterior (3 meses)
• Anual: YTD actual vs YTD anterior

Reportes PDF

Reporte Diario

• Resumen de KPIs del dia
• Grafica de tendencias
• Top 5 vendedores
• Detalle de ventas

Reporte Ejecutivo

• KPIs del mes
• Comparativas mensuales
• Ranking completo
• Graficas de rendimiento
• Proyecciones

Desarrollo

Estructura de Codigo

app.py - Aplicacion principal

app = Flask(__name__)

# Rutas del dashboard
@app.route('/dashboard')
@app.route('/dashboard/analytics')
@app.route('/dashboard/executive')

# API endpoints
@app.route('/api/dashboard/...')
@app.route('/api/analytics/...')
@app.route('/api/reports/...')

# Comandos slash
@app.route('/comando/...')

analytics/predictions.py - Predicciones

def prediccion_basica(ventas_diarias, dias_prediccion=7):
    # Promedio movil + regresion lineal
    return {
        'predicciones': [...],
        'tendencia': 'increasing|stable|decreasing',
        'confidence': 0.85
    }

ocr/processor.py - OCR

processor = OCRProcessor()
result = processor.process(image_bytes)
# result: {texto, monto, cliente, fecha, tubos, formato, confianza}

reports/pdf_generator.py - PDFs

pdf = SalesReportPDF(ventas, stats)
content = pdf.generar_reporte_diario()
# content: bytes del PDF

Dependencias Principales

# Web Framework
Flask==3.0.0
gunicorn==21.2.0

# OCR
pytesseract==0.3.10
Pillow==10.2.0
opencv-python==4.9.0.80

# PDF
reportlab==4.1.0
matplotlib==3.8.2

# Analytics
scipy==1.12.0
pandas==2.1.4
numpy==1.26.3

# OCR Mejorado
imutils==0.5.4
deskew==1.1.0

# Mattermost
mattermostdriver==7.3.2

# Scheduler
APScheduler==3.10.4

# Excel
openpyxl==3.1.2

Troubleshooting

El dashboard no carga

# Verificar que el contenedor esta corriendo
docker ps | grep sales-bot

# Ver logs
docker logs sales-bot --tail 100

# Reconstruir imagen
docker compose build --no-cache
docker compose up -d

OCR no detecta el monto

• Verificar que la imagen tenga buena iluminacion
• Probar con imagen de mayor resolucion
• El ticket no debe estar muy inclinado (max 15 grados)

Predicciones muestran 0

• Se requieren al menos 3 dias de datos historicos
• Verificar que hay ventas registradas

PDF no se genera

# Verificar que reportlab esta instalado
docker exec sales-bot pip list | grep reportlab

# Si no esta, reconstruir imagen
docker compose build --no-cache

Health Check

curl http://localhost:5000/health

Respuesta:

{
  "status": "healthy",
  "timestamp": "2026-01-19T10:30:45",
  "version": "1.0.0"
}

Licencia

Proyecto privado - Consultoria AS

Contacto

Para soporte tecnico contactar al equipo de desarrollo.