---
id: EPIC-MCH-012
type: Epic
title: "MCH-012: Chat LLM Dueno"
code: MCH-012
status: Completado
status_real: "Completado"
status_nota: "Implementado en Sprint 2 - Role-based chat con funciones de dueño"
phase: 3
priority: P1
created_at: 2026-01-07
updated_at: 2026-01-18
simco_version: "4.0.1"
story_points: 55
dependencies:
  blocks: []
  depends_on: []
---

# MCH-012: Chat LLM Dueno

## Metadata
- **Codigo:** MCH-012
- **Fase:** 3 - Asistente IA
- **Prioridad:** P1
- **Estado:** Completado
- **Sprint Asignado:** Sprint 2
- **Fecha completado:** 2026-01-18
- **Story Points:** 55

## Descripcion

Asistente IA conversacional para duenos de negocio: consultas de ventas, inventario, clientes; generacion de reportes; sugerencias de negocio; todo via chat en la app o WhatsApp.

## Objetivos

1. Chat conversacional en app/WhatsApp
2. Consultas de ventas y metricas
3. Gestion de inventario via chat
4. Alertas y sugerencias proactivas
5. Generacion de reportes por voz

## Alcance

### Incluido
- "¿Cuanto vendi hoy/esta semana?"
- "¿Cuantas Cocas me quedan?"
- "Sube el precio de las Sabritas a $20"
- "¿Quien me debe mas?"
- "Dame el reporte de la semana"
- Alertas: stock bajo, pagos pendientes

### Excluido
- Operaciones bancarias
- Gestion de empleados avanzada
- Analisis financiero complejo

## Casos de Uso

### Consulta de Ventas
```
Dueno: "¿Cuanto vendi hoy?"
Bot: "Hoy llevas $3,450 en 23 ventas.
      Top productos: Coca-Cola (15), Sabritas (12).
      Comparado con ayer: +15% 📈"
```

### Consulta de Inventario
```
Dueno: "¿Tengo Coca de 600?"
Bot: "Te quedan 8 Coca-Cola 600ml.
      Al ritmo actual, duraran ~2 dias.
      ¿Quieres que te recuerde hacer pedido?"
```

### Modificar Precio
```
Dueno: "Sube las Sabritas a 20 pesos"
Bot: "Actualizo precio de Sabritas Original
      de $18 a $20. ¿Confirmas?"
Dueno: "Si"
Bot: "Listo, precio actualizado ✓"
```

### Consulta de Fiados
```
Dueno: "¿Quien me debe mas?"
Bot: "Tus clientes con mayor adeudo:
      1. Juan Perez: $850 (15 dias)
      2. Maria Lopez: $420 (7 dias)
      3. Pedro Garcia: $380 (3 dias)
      ¿Quieres enviar recordatorio?"
```

### Reporte Semanal
```
Dueno: "Dame el reporte de la semana"
Bot: "📊 Reporte Semanal (Ene 1-7)

      💰 Ventas: $24,350 (+8% vs anterior)
      📦 Transacciones: 156
      🎫 Ticket promedio: $156

      Top 5 productos:
      1. Coca-Cola 600ml - 89 unidades
      2. Sabritas - 67 unidades
      ...

      ⚠️ 3 productos con stock bajo
      💳 Cartera por cobrar: $2,150"
```

## Flujo Tecnico

```
1. Dueno envia mensaje (app o WhatsApp)
2. WhatsApp Service recibe
3. Identifica como chat de dueno
4. Envia a MCP Server con contexto:
   - tenant_id
   - user_role: "owner"
   - tools: todos disponibles
5. MCP procesa con LLM
6. LLM decide tool calls necesarios
7. Ejecuta tools (consultas/acciones)
8. Genera respuesta natural
9. Envia respuesta al dueno
```

## Tools Especificos

```typescript
// Tools habilitados para dueno
const ownerTools = [
  'search_products',
  'get_product_stock',
  'update_product_price',
  'get_daily_sales',
  'get_sales_report',
  'get_low_stock_products',
  'search_customers',
  'get_customer_balance',
  'send_payment_reminder',
  'get_top_products',
  'get_business_metrics'
];
```

## Alertas Proactivas

### Stock Bajo
```
Enviado: 9:00 AM
"🔔 Alerta de inventario
 3 productos estan por agotarse:
 - Coca-Cola 600ml (5 unidades)
 - Pan Bimbo (3 unidades)
 - Leche (4 unidades)

 ¿Quieres ver sugerencia de pedido?"
```

### Recordatorio de Cobro
```
Enviado: 10:00 AM Lunes
"💰 Tienes $2,150 en fiados pendientes.
 5 clientes deben desde hace +7 dias.
 ¿Envio recordatorios automaticos?"
```

## Historias de Usuario

### MCH-US-110: Consultar ventas del dia en chat
**Story Points:** 3

**Como** dueño de negocio
**Quiero** preguntar al chat cuanto he vendido hoy
**Para** monitorear mis ventas en tiempo real sin acceder al dashboard

#### Criterios de Aceptación
- [CA-110-1] El chat responde con monto total de ventas del dia actual
- [CA-110-2] La respuesta incluye cantidad de transacciones
- [CA-110-3] Se muestran los 3 productos mas vendidos
- [CA-110-4] Se incluye comparacion con el dia anterior (variacion %)

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-110-01 | Implementar endpoint `get_daily_sales` en backend | 3h |
| MCH-TT-110-02 | Integrar tool en MCP Server | 2h |
| MCH-TT-110-03 | Agregar casos de prueba | 2h |

---

### MCH-US-111: Consultar inventario de producto especifico
**Story Points:** 3

**Como** dueño de negocio
**Quiero** preguntar que cantidad tengo de un producto especifico
**Para** saber si tengo stock disponible sin revisar fisicamente

#### Criterios de Aceptación
- [CA-111-1] El chat identifica el producto por nombre o codigo
- [CA-111-2] Responde con cantidad actual en stock
- [CA-111-3] Estima dias hasta agotamiento basado en velocidad de venta
- [CA-111-4] Sugiere hacer pedido si stock es critico (< 5 unidades)

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-111-01 | Implementar endpoint `get_product_stock` | 3h |
| MCH-TT-111-02 | Crear prediccion de velocidad de venta | 4h |
| MCH-TT-111-03 | Integrar en MCP Server | 2h |

---

### MCH-US-112: Modificar precio de producto via chat
**Story Points:** 5

**Como** dueño de negocio
**Quiero** cambiar el precio de un producto directamente en el chat
**Para** reaccionar rapidamente a cambios de mercado o promociones

#### Criterios de Aceptación
- [CA-112-1] El usuario proporciona producto y nuevo precio
- [CA-112-2] El chat confirma el cambio actual antes de aplicar
- [CA-112-3] Se registra quién y cuando cambió el precio (auditoria)
- [CA-112-4] Se invalida cache de precios tras el cambio
- [CA-112-5] Se notifica a puntos de venta de los cambios

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-112-01 | Endpoint `update_product_price` con validacion | 4h |
| MCH-TT-112-02 | Sistema de confirmacion en chat | 3h |
| MCH-TT-112-03 | Registro de auditoria | 2h |
| MCH-TT-112-04 | Invalidar cache y notificar POS | 3h |

---

### MCH-US-113: Consultar quien debe dinero (fiados)
**Story Points:** 5

**Como** dueño de negocio
**Quiero** saber cuales clientes me deben dinero y desde cuando
**Para** cobrar efectivamente y tomar decisiones de credito

#### Criterios de Aceptación
- [CA-113-1] Lista clientes ordenados por monto adeudado (mayor a menor)
- [CA-113-2] Muestra dias desde ultima compra a credito
- [CA-113-3] Identifica clientes con atrasos de +7 dias
- [CA-113-4] Permite enviar recordatorio de pago directamente

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-113-01 | Endpoint `get_customer_balance` con detalles | 3h |
| MCH-TT-113-02 | Implementar `send_payment_reminder` | 3h |
| MCH-TT-113-03 | Identificar atrasos y alertas | 2h |
| MCH-TT-113-04 | Pruebas de integracion | 2h |

---

### MCH-US-114: Generar reporte semanal por chat
**Story Points:** 8

**Como** dueño de negocio
**Quiero** pedir al chat un reporte completo de mis ventas en la semana
**Para** analizar el desempeño sin acceder a reportes complejos

#### Criterios de Aceptación
- [CA-114-1] Reporte incluye: total ventas, transacciones, ticket promedio
- [CA-114-2] Muestra top 5 productos mas vendidos
- [CA-114-3] Identifica productos con stock bajo
- [CA-114-4] Suma total de cartera por cobrar (fiados)
- [CA-114-5] Compara con semana anterior (variacion %)
- [CA-114-6] Reporte se exporta a PDF o imagen

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-114-01 | Crear logica de agregacion de datos semanal | 5h |
| MCH-TT-114-02 | Template de reporte visualmente atractivo | 4h |
| MCH-TT-114-03 | Endpoint `get_sales_report` | 3h |
| MCH-TT-114-04 | Exportacion a PDF/imagen | 4h |
| MCH-TT-114-05 | Pruebas y refinamiento | 3h |

---

### MCH-US-115: Alertas proactivas de stock bajo
**Story Points:** 8

**Como** dueño de negocio
**Quiero** recibir alertas automaticas cuando el stock de productos criticos es bajo
**Para** no quedarme sin inventario en momentos de alta demanda

#### Criterios de Aceptación
- [CA-115-1] Sistema monitorea productos configurados como criticos
- [CA-115-2] Alerta se envia cuando stock < 5 unidades
- [CA-115-3] Se envia en app y/o WhatsApp segun preferencias
- [CA-115-4] Alerta incluye: producto, cantidad actual, dias para agotarse
- [CA-115-5] No duplica alertas en corto tiempo (cooldown de 4 horas)
- [CA-115-6] Usuario puede confirmar "ya pedi" para silenciar alerta

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-115-01 | Scheduler de monitoreo de stock | 4h |
| MCH-TT-115-02 | Reglas de disparo de alertas | 3h |
| MCH-TT-115-03 | Sistema de cooldown y silenciamiento | 3h |
| MCH-TT-115-04 | Notificacion multicanal (app + WhatsApp) | 3h |
| MCH-TT-115-05 | Testing de scheduler | 3h |

---

### MCH-US-116: Alertas de pagos pendientes
**Story Points:** 5

**Como** dueño de negocio
**Quiero** recibir alertas cuando tengo clientes con pagos muy atrasados
**Para** actuar a tiempo y mejorar cobranza

#### Criterios de Aceptación
- [CA-116-1] Sistema identifica deudas con atrasos > 7 dias
- [CA-116-2] Alerta se envia diariamente a las 10:00 AM
- [CA-116-3] Muestra monto total y cantidad de clientes en atrazo
- [CA-116-4] Permite enviar recordatorio de cobro con un click
- [CA-116-5] Puede personalizarse el umbral de dias (defecto 7)

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-116-01 | Logica de deteccion de atrasos | 3h |
| MCH-TT-116-02 | Scheduler de alertas diarias | 2h |
| MCH-TT-116-03 | Integracion con recordatorios de cobro | 2h |
| MCH-TT-116-04 | Configuracion personalizable | 2h |

---

### MCH-US-117: Mensajes de voz para consultas
**Story Points:** 8

**Como** dueño de negocio
**Quiero** hacer preguntas al chat por voz en lugar de escribir
**Para** interactuar mas rapidamente mientras estoy ocupado

#### Criterios de Aceptación
- [CA-117-1] Acepta audio en app y WhatsApp
- [CA-117-2] Convierte voz a texto con precision > 95%
- [CA-117-3] Procesa la consulta como si fuera texto escrito
- [CA-117-4] Respuesta se puede reproducir como audio (TTS)
- [CA-117-5] Soporte para espanol latinoamericano

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-117-01 | Integracion de Speech-to-Text (Google/Azure) | 4h |
| MCH-TT-117-02 | Integracion de Text-to-Speech | 4h |
| MCH-TT-117-03 | Pipeline de procesamiento de audio | 3h |
| MCH-TT-117-04 | Testing de precision y latencia | 3h |

---

### MCH-US-118: Obtener metricas del negocio
**Story Points:** 5

**Como** dueño de negocio
**Quiero** preguntar metricas clave como "¿Cual es mi margen promedio?" o "¿Quien es mi cliente top?"
**Para** entender la salud del negocio en tiempo real

#### Criterios de Aceptación
- [CA-118-1] Calcula y responde: margen promedio, cliente top, producto top
- [CA-118-2] Responde preguntas como "¿Cuanto gane este mes?"
- [CA-118-3] Identifica tendencias (subida/bajada de ventas)
- [CA-118-4] Respuestas incluyen contexto (comparacion con periodos anteriores)

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-118-01 | Endpoint `get_business_metrics` | 4h |
| MCH-TT-118-02 | Calculos de margen y tendencias | 3h |
| MCH-TT-118-03 | Formateo de respuestas con contexto | 2h |

---

### MCH-US-119: Sugerencias inteligentes de acciones
**Story Points:** 5

**Como** dueño de negocio
**Quiero** que el chat me sugiera acciones basadas en los datos (ej: "Podrias subir el precio de las Sabritas, es tu producto mas vendido")
**Para** tomar decisiones de negocio sin analizar yo mismo

#### Criterios de Aceptación
- [CA-119-1] Chat identifica productos top y sugiere promocion o aumento de precio
- [CA-119-2] Sugiere hacer pedido cuando stock baja
- [CA-119-3] Sugiere cobrar a clientes con atrasos
- [CA-119-4] Las sugerencias son accionables (puedo confirmar directamente)
- [CA-119-5] No spam: maximo 2-3 sugerencias por dia

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-119-01 | Motor de reglas para sugerencias | 4h |
| MCH-TT-119-02 | Integracion de contexto historico | 3h |
| MCH-TT-119-03 | Sistema de frecuencia y cooldown | 2h |
| MCH-TT-119-04 | Testing de relevancia | 2h |

---

### Resumen de Story Points
| Historia | Descripción | SP |
|----------|-------------|-----|
| MCH-US-110 | Consultar ventas del dia | 3 |
| MCH-US-111 | Consultar inventario | 3 |
| MCH-US-112 | Modificar precio via chat | 5 |
| MCH-US-113 | Consultar fiados | 5 |
| MCH-US-114 | Generar reporte semanal | 8 |
| MCH-US-115 | Alertas de stock bajo | 8 |
| MCH-US-116 | Alertas de pagos pendientes | 5 |
| MCH-US-117 | Mensajes de voz | 8 |
| MCH-US-118 | Metricas del negocio | 5 |
| MCH-US-119 | Sugerencias inteligentes | 5 |
| **Total** | | **55** |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| Owner chat flow | Pendiente | `whatsapp-service/flows/owner.flow.ts` |
| MCP tools completos | Pendiente | `mcp-server/tools/` |
| Alert scheduler | Pendiente | `backend/jobs/alerts.job.ts` |
| App chat UI | Pendiente | `mobile/screens/Chat.tsx` |

## Dependencias

### Depende de
- MCH-010 (MCP Server)
- MCH-011 (WhatsApp Service)
- MCH-003, 004, 008, 009 (datos)

### Bloquea a
- Ninguno (mejora de UX)

## Criterios de Aceptacion

- [x] Consultas de venta funcionan
- [x] Consultas de inventario funcionan
- [x] Modificacion de precios funciona
- [x] Consultas de fiados funcionan
- [x] Alertas proactivas se envian
- [x] Reportes se generan correctamente

## Limites de Tokens

| Plan | Tokens/mes | Interacciones aprox |
|------|------------|---------------------|
| Changarrito | 500 | ~100 conversaciones |
| Tiendita | 2000 | ~400 conversaciones |

---

**Ultima actualizacion:** 2026-01-17