Commit inicial: Sales Bot - Sistema de Automatización de Ventas

- Stack completo con Mattermost, NocoDB y Sales Bot - Procesamiento OCR de tickets con Tesseract - Sistema de comisiones por tubos de tinte - Comandos slash /metas y /ranking - Documentación completa del proyecto Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-18 02:41:53 +00:00
commit 5d9cbd4812
21 changed files with 4625 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,219 @@
+# Sales Bot - Sistema de Automatización de Ventas
+
+Sistema integral de automatización de ventas que integra Mattermost, NocoDB y procesamiento OCR para gestionar ventas, comisiones y metas de vendedores.
+
+## Descripción General
+
+**Sales Bot** es una solución completa para equipos de ventas que permite:
+- Registro automático de ventas via chat (Mattermost)
+- Procesamiento OCR de tickets/facturas
+- Gestión de vendedores y metas
+- Cálculo automático de comisiones por tubos de tinte
+- Reportes y ranking de vendedores
+
+## Stack Tecnológico
+
+| Componente | Tecnología |
+|------------|------------|
+| Backend | Python 3.12 + Flask + Gunicorn |
+| Chat | Mattermost Team Edition |
+| Base de Datos | NocoDB + PostgreSQL |
+| OCR | Tesseract (inglés/español) |
+| Visión | OpenCV, Pillow, NumPy |
+| Infraestructura | Docker Compose |
+
+## Estructura del Proyecto
+
+```
+stacks/
+├── mattermost/           # Stack de Mattermost (chat empresarial)
+│   └── compose.yaml
+├── nocodb/               # Stack de NocoDB (base de datos visual)
+│   └── compose.yaml
+└── sales-bot/            # Aplicación principal del bot
+    ├── app.py            # Aplicación Flask principal
+    ├── handlers.py       # Manejadores de eventos de ventas
+    ├── mattermost_client.py    # Cliente API de Mattermost
+    ├── nocodb_client.py        # Cliente API de NocoDB
+    ├── ocr_processor.py        # Procesador OCR para tickets
+    ├── websocket_listener.py   # Listener WebSocket
+    ├── utils.py          # Utilidades
+    ├── Dockerfile
+    ├── compose.yaml
+    ├── requirements.txt
+    └── .env
+```
+
+## Servicios
+
+### Mattermost (Puerto 8065)
+Plataforma de mensajería empresarial donde los vendedores reportan sus ventas.
+
+### NocoDB (Puerto 8080)
+Base de datos visual con interfaz web para gestionar:
+- Vendedores
+- Ventas
+- Detalles de productos
+- Metas
+
+### Sales Bot (Puerto 5000)
+Aplicación principal que orquesta todo el sistema.
+
+## Instalación
+
+### Requisitos Previos
+- Docker y Docker Compose
+- Acceso a red local (192.168.10.204)
+
+### Despliegue
+
+1. **Iniciar Mattermost:**
+```bash
+cd mattermost
+docker compose up -d
+```
+
+2. **Iniciar NocoDB:**
+```bash
+cd nocodb
+docker compose up -d
+```
+
+3. **Iniciar Sales Bot:**
+```bash
+cd sales-bot
+docker compose up -d
+```
+
+## Configuración
+
+### Variables de Entorno (.env)
+
+```env
+# Mattermost
+MATTERMOST_URL=http://192.168.10.204:8065
+MATTERMOST_BOT_TOKEN=<tu_token>
+MATTERMOST_TEAM_NAME=sales
+MATTERMOST_WEBHOOK_SECRET=<tu_secret>
+MATTERMOST_WEBHOOK_URL=http://192.168.10.204:8065/hooks/<hook_id>
+
+# NocoDB
+NOCODB_URL=http://192.168.10.204:8080
+NOCODB_TOKEN=<tu_token>
+NOCODB_TABLE_VENDEDORES=<table_id>
+NOCODB_TABLE_VENTAS=<table_id>
+NOCODB_TABLE_VENTAS_DETALLE=<table_id>
+NOCODB_TABLE_METAS=<table_id>
+
+# Flask
+FLASK_PORT=5000
+FLASK_DEBUG=False
+LOG_LEVEL=INFO
+TZ_OFFSET=-6
+```
+
+## Uso
+
+### Registrar una Venta
+
+En Mattermost, envía un mensaje con el formato:
+```
+venta @monto 1500 @cliente Juan
+```
+
+Opcionalmente adjunta una foto del ticket para procesamiento OCR automático.
+
+### Comandos Slash
+
+| Comando | Descripción |
+|---------|-------------|
+| `/metas` | Muestra progreso de meta del vendedor |
+| `/ranking` | Muestra ranking de vendedores |
+
+## API Endpoints
+
+| Endpoint | Método | Descripción |
+|----------|--------|-------------|
+| `/health` | GET | Health check del servicio |
+| `/webhook/mattermost` | POST | Webhook para mensajes de Mattermost |
+| `/webhook/nocodb` | POST | Webhook para eventos de NocoDB |
+| `/comando/metas` | POST | Comando slash /metas |
+| `/comando/ranking` | POST | Comando slash /ranking |
+
+## Sistema de Comisiones
+
+- **Meta diaria:** 3 tubos de tinte
+- **Comisión:** $10 MXN por cada tubo después del tercero
+
+### Ejemplo:
+- Vendedor vende 5 tubos → Comisión: (5-3) × $10 = $20
+
+## Flujo de Operación
+
+```
+Vendedor envía mensaje + foto
+        ↓
+Webhook → Sales Bot
+        ↓
+Extracción de datos (monto, cliente)
+        ↓
+OCR de imagen (productos, fecha, monto)
+        ↓
+Validación (tolerancia ±5%)
+        ↓
+Registro en NocoDB
+        ↓
+Cálculo de comisiones
+        ↓
+Respuesta en Mattermost con confirmación
+```
+
+## Tablas en NocoDB
+
+| Tabla | Descripción |
+|-------|-------------|
+| Vendedores | Información de vendedores, metas |
+| Ventas | Registro de ventas (monto, cliente, fecha) |
+| Ventas Detalle | Productos por venta (marca, cantidad, precio) |
+| Metas | Metas mensuales y diarias |
+
+## Monitoreo
+
+### Logs
+Los logs se almacenan en `sales-bot/logs/sales-bot.log`
+
+### Health Check
+```bash
+curl http://localhost:5000/health
+```
+
+## Desarrollo
+
+### Requisitos
+```bash
+pip install -r requirements.txt
+```
+
+### Ejecución Local
+```bash
+cd sales-bot
+python app.py
+```
+
+## Características
+
+- OCR robusto con múltiples configuraciones PSM
+- Validación de montos con tolerancia del 5%
+- Detección automática de tubos de tinte
+- Respuestas con emojis motivacionales
+- Health checks en todos los servicios
+- Contenedor con usuario no-root
+- Persistencia de datos en volúmenes Docker
+
+## Licencia
+
+Proyecto privado - Consultoría AS
+
+## Contacto
+
+Consultoría AS - https://consultoria-as.com