sales-bot-stacks/docs/INSTALACION.md

# Guía de Instalación

## Requisitos del Sistema

### Hardware Mínimo
- CPU: 2 cores
- RAM: 4 GB
- Disco: 20 GB

### Software
- Docker 20.10+
- Docker Compose 2.0+
- Git

### Red
- Puerto 5000 (Sales Bot)
- Puerto 8065 (Mattermost)
- Puerto 8080 (NocoDB)

---

## Instalación Paso a Paso

### 1. Clonar el Repositorio

```bash
git clone https://git.consultoria-as.com/<usuario>/stacks.git
cd stacks
```

### 2. Configurar Variables de Entorno

Copiar el archivo de ejemplo y editar:

```bash
cd sales-bot
cp .env.example .env
nano .env
```

Configurar las siguientes variables:

```env
# Mattermost
MATTERMOST_URL=http://<IP>:8065
MATTERMOST_BOT_TOKEN=<tu_token>
MATTERMOST_TEAM_NAME=sales
MATTERMOST_WEBHOOK_SECRET=<tu_secret>
MATTERMOST_WEBHOOK_URL=http://<IP>:8065/hooks/<hook_id>

# NocoDB
NOCODB_URL=http://<IP>: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
LOG_LEVEL=INFO
TZ_OFFSET=-6
```

### 3. Iniciar Mattermost

```bash
cd ../mattermost
docker compose up -d
```

Esperar a que inicie completamente:
```bash
docker compose logs -f
# Esperar mensaje "Server is listening"
```

Acceder a http://<IP>:8065 y completar la configuración inicial:
1. Crear cuenta de administrador
2. Crear team "sales"
3. Crear canales necesarios

### 4. Configurar Bot en Mattermost

1. Ir a **Integraciones > Bot Accounts**
2. Crear nuevo bot:
   - Username: `salesbot`
   - Copiar el token generado

3. Ir a **Integraciones > Outgoing Webhooks**
4. Crear webhook:
   - Canal: canal de ventas
   - URL: `http://<IP>:5000/webhook/mattermost`
   - Copiar el token

5. Ir a **Integraciones > Slash Commands**
6. Crear comandos:
   - `/metas` → `http://<IP>:5000/comando/metas`
   - `/ranking` → `http://<IP>:5000/comando/ranking`

### 5. Iniciar NocoDB

```bash
cd ../nocodb
docker compose up -d
```

Acceder a http://<IP>:8080 y:
1. Crear cuenta
2. Crear base de datos
3. Crear tablas (ver estructura en docs/ARQUITECTURA.md)
4. Obtener API token en Settings

### 6. Configurar Tablas en NocoDB

Crear las siguientes tablas:

**Vendedores:**
```
- Id (Auto)
- username (Text, Required)
- nombre_completo (Text)
- email (Email)
- meta_diaria_tubos (Number, Default: 3)
- activo (Checkbox, Default: true)
- fecha_registro (DateTime)
```

**Ventas:**
```
- Id (Auto)
- vendedor_username (Text, Required)
- monto (Currency)
- cliente (Text)
- fecha_venta (DateTime)
- estado (SingleSelect: pendiente, completada, cancelada)
- canal (Text)
- mensaje_id (Text)
- imagen_ticket (Attachment)
- descripcion (LongText)
```

**Ventas Detalle:**
```
- Id (Auto)
- venta_id (Number)
- producto (Text)
- marca (Text)
- cantidad (Number)
- precio_unitario (Currency)
- importe (Currency)
```

**Metas:**
```
- Id (Auto)
- vendedor_username (Text)
- mes (Text)
- tubos_vendidos (Number)
- comision (Currency)
- meta_diaria (Number)
- porcentaje_completado (Percent)
- total_vendido (Currency)
```

### 7. Obtener IDs de Tablas

En NocoDB, para cada tabla:
1. Abrir la tabla
2. Copiar el ID de la URL: `/table/<TABLE_ID>`

Actualizar estos IDs en el archivo `.env`.

### 8. Iniciar Sales Bot

```bash
cd ../sales-bot
docker compose up -d
```

Verificar que esté corriendo:
```bash
curl http://localhost:5000/health
```

---

## Verificación de la Instalación

### 1. Verificar Servicios

```bash
# Mattermost
curl http://localhost:8065/api/v4/system/ping

# NocoDB
curl http://localhost:8080/api/v2/health

# Sales Bot
curl http://localhost:5000/health
```

### 2. Probar Flujo Completo

1. Enviar mensaje en Mattermost:
   ```
   venta @monto 100 @cliente Prueba
   ```

2. Verificar que el bot responda
3. Verificar registro en NocoDB

---

## Solución de Problemas

### Sales Bot no responde

```bash
# Ver logs
docker compose -f sales-bot/compose.yaml logs -f

# Reiniciar
docker compose -f sales-bot/compose.yaml restart
```

### Error de conexión a Mattermost

Verificar:
1. Token del bot es correcto
2. Bot tiene permisos en el canal
3. URL de Mattermost es accesible

### Error de conexión a NocoDB

Verificar:
1. Token de API es correcto
2. IDs de tablas son correctos
3. URL de NocoDB es accesible

### OCR no funciona

Verificar:
1. Tesseract está instalado en el contenedor
2. Imagen es legible
3. Ver logs para errores específicos

---

## Actualización

```bash
# Detener servicios
docker compose -f sales-bot/compose.yaml down
docker compose -f mattermost/compose.yaml down
docker compose -f nocodb/compose.yaml down

# Actualizar código
git pull

# Reconstruir imágenes
docker compose -f sales-bot/compose.yaml build

# Iniciar servicios
docker compose -f mattermost/compose.yaml up -d
docker compose -f nocodb/compose.yaml up -d
docker compose -f sales-bot/compose.yaml up -d
```

---

## Backup y Restauración

### Backup

```bash
# Backup de Mattermost
docker compose -f mattermost/compose.yaml exec postgres \
  pg_dump -U consultoria-as mattermost > mattermost_backup.sql

# Backup de NocoDB
docker compose -f nocodb/compose.yaml exec postgres \
  pg_dump -U consultoria-as nocodb > nocodb_backup.sql
```

### Restauración

```bash
# Restaurar Mattermost
cat mattermost_backup.sql | docker compose -f mattermost/compose.yaml exec -T postgres \
  psql -U consultoria-as mattermost

# Restaurar NocoDB
cat nocodb_backup.sql | docker compose -f nocodb/compose.yaml exec -T postgres \
  psql -U consultoria-as nocodb
```