sales-bot-stacks/README.md

# 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