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)

```bash
# 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

```bash
# 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

```python
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
```python
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
```python
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
```python
processor = OCRProcessor()
result = processor.process(image_bytes)
# result: {texto, monto, cliente, fecha, tubos, formato, confianza}
```

**reports/pdf_generator.py** - PDFs
```python
pdf = SalesReportPDF(ventas, stats)
content = pdf.generar_reporte_diario()
# content: bytes del PDF
```

### Dependencias Principales

```txt
# 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
```bash
# 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
```bash
# 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

```bash
curl http://localhost:5000/health
```

Respuesta:
```json
{
  "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.