---
id: EPIC-MCH-013
type: Epic
title: "MCH-013: Chat LLM Cliente"
code: MCH-013
status: Pendiente
phase: 3
priority: P1
created_at: 2026-01-07
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 34
dependencies:
  blocks: []
  depends_on: []
---

# MCH-013: Chat LLM Cliente

## Metadata
- **Codigo:** MCH-013
- **Fase:** 3 - Asistente IA
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 8-9
- **Story Points:** 34

## Descripcion

Asistente IA para clientes del negocio via WhatsApp: consulta de precios, disponibilidad de productos, hacer pedidos, consultar saldo de fiado, y recibir promociones.

## Objetivos

1. Consulta de precios y disponibilidad
2. Hacer pedidos via chat
3. Consultar saldo de fiado
4. Recibir catalogo de productos
5. Atender preguntas frecuentes

## Alcance

### Incluido
- "¿Tienen Coca de 2 litros?"
- "¿Cuanto cuesta el pan Bimbo?"
- "Quiero pedir 2 Cocas y unas Sabritas"
- "¿Cuanto debo?"
- "¿A que hora cierran?"
- Catalogo de productos (imagen)

### Excluido
- Pagos en linea (fase posterior)
- Tracking de entrega en tiempo real
- Cambios/devoluciones via chat

## Casos de Uso

### Consulta de Precio
```
Cliente: "¿Cuanto cuesta la Coca?"
Bot: "Tenemos Coca-Cola en varios tamaños:
      - 355ml (lata): $15
      - 600ml: $18
      - 2L: $35
      - 3L: $48
      ¿Cual te gustaria?"
```

### Consulta de Disponibilidad
```
Cliente: "¿Tienen pan Bimbo?"
Bot: "Si, tenemos:
      ✓ Pan Blanco Grande - $48
      ✓ Pan Integral - $52
      ✗ Pan Tostado - Agotado
      ¿Quieres agregar alguno a tu pedido?"
```

### Hacer Pedido
```
Cliente: "Quiero 2 Cocas de 600 y unas Sabritas"
Bot: "Tu pedido:
      - 2x Coca-Cola 600ml = $36
      - 1x Sabritas Original = $18

      Total: $54

      ¿Lo confirmas?
      [Confirmar] [Agregar mas] [Cancelar]"

Cliente: [Confirmar]
Bot: "¡Pedido confirmado! 🎉
      Numero: #123
      Estara listo en 10 minutos.
      Te avisamos cuando puedas pasar."
```

### Consulta de Fiado
```
Cliente: "¿Cuanto debo?"
Bot: "Hola Juan, tu saldo actual es de $180.
      Ultimo movimiento: $45 el 5 de enero.
      Puedes pasar a abonar cuando gustes."
```

### Horarios y Ubicacion
```
Cliente: "¿A que hora abren?"
Bot: "Tiendita Don Jose 🏪
      📍 Calle Principal #123

      Horario:
      Lun-Sab: 7am - 10pm
      Dom: 8am - 8pm

      ¿Te puedo ayudar en algo mas?"
```

## Flujo Tecnico

```
1. Cliente envia mensaje a numero del negocio
2. WhatsApp Service recibe
3. Identifica como cliente (no dueno)
4. Envia a MCP Server con contexto:
   - tenant_id
   - customer_phone
   - customer_id (si existe)
   - tools: limitados para cliente
5. MCP procesa con LLM
6. Ejecuta tools (consultas/pedido)
7. Genera respuesta amigable
8. Envia respuesta al cliente
```

## Tools Limitados para Cliente

```typescript
// Tools habilitados para clientes
const customerTools = [
  'search_products',
  'get_product_price',
  'check_availability',
  'create_order',
  'get_my_balance',
  'get_business_info',
  'get_promotions'
];

// Tools NO disponibles para clientes
// - update_product_price
// - get_sales_report
// - send_payment_reminder
// - etc.
```

## Intents del Cliente

| Intent | Ejemplo | Accion |
|--------|---------|--------|
| CONSULTA_PRECIO | "Cuanto cuesta..." | search_products |
| CONSULTA_DISPONIBILIDAD | "Tienen..." | check_availability |
| HACER_PEDIDO | "Quiero pedir..." | create_order |
| CONSULTA_SALDO | "Cuanto debo" | get_my_balance |
| HORARIOS | "A que hora..." | get_business_info |
| UBICACION | "Donde estan" | get_business_info |
| PROMOCIONES | "Que ofertas tienen" | get_promotions |

## Modelo de Datos

### Asociacion Cliente-Telefono

```typescript
// Al recibir mensaje de numero nuevo
1. Buscar en customers por phone
2. Si existe: asociar conversacion
3. Si no existe: crear customer temporal
4. Si hace pedido: pedir nombre
```

## Limites y Seguridad

- Clientes NO pueden ver info de otros clientes
- Clientes NO pueden modificar precios
- Clientes NO pueden ver reportes
- Rate limit: 20 mensajes/hora por cliente
- Tokens: descontados de cuota del tenant

## Historias de Usuario

### MCH-US-120: Consultar Precios de Productos

**Story Points:** 5

**Como** cliente del negocio
**Quiero** consultar el precio de un producto específico via chat
**Para** conocer cuánto cuesta antes de hacer mi pedido

#### Criterios de Aceptación
- [CA-120-1] El cliente puede enviar mensaje como "¿Cuánto cuesta la Coca?"
- [CA-120-2] El bot responde con todos los tamaños disponibles y sus precios
- [CA-120-3] La información mostrada coincide con la base de datos actual
- [CA-120-4] Solo se muestran productos disponibles en el catálogo

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-120-01 | Crear endpoint `get_product_price` en MCP Server | 3h |
| MCH-TT-120-02 | Implementar intent recognition para CONSULTA_PRECIO | 2h |
| MCH-TT-120-03 | Diseñar prompt para formatear respuesta de precios | 2h |
| MCH-TT-120-04 | Testing de consultas de precio comunes | 2h |

---

### MCH-US-121: Consultar Disponibilidad de Productos

**Story Points:** 5

**Como** cliente del negocio
**Quiero** verificar si un producto está disponible en el inventario
**Para** saber si puedo pedirlo en este momento

#### Criterios de Aceptación
- [CA-121-1] El cliente puede preguntar "¿Tienen pan Bimbo?"
- [CA-121-2] El bot responde con estado de disponibilidad (✓ disponible / ✗ agotado)
- [CA-121-3] Se muestran opciones alternativas si el producto no está disponible
- [CA-121-4] La información se obtiene en tiempo real del inventario

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-121-01 | Crear endpoint `check_availability` en MCP Server | 3h |
| MCH-TT-121-02 | Conectar con servicio de inventario | 3h |
| MCH-TT-121-03 | Implementar lógica de sugerencias de productos similares | 3h |
| MCH-TT-121-04 | Testing de disponibilidad en tiempo real | 2h |

---

### MCH-US-122: Crear Pedido Via Chat

**Story Points:** 8

**Como** cliente del negocio
**Quiero** hacer un pedido directamente desde el chat
**Para** obtener mis productos sin necesidad de ir personalmente

#### Criterios de Aceptación
- [CA-122-1] El cliente puede decir "Quiero 2 Cocas de 600 y unas Sabritas"
- [CA-122-2] El bot resume el pedido con total a pagar
- [CA-122-3] El cliente puede confirmar, agregar más o cancelar
- [CA-122-4] El pedido se guarda en la base de datos con estado "confirmado_por_chat"
- [CA-122-5] El cliente recibe número de pedido y hora estimada de entrega

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-122-01 | Crear flujo de carrito en memoria durante chat | 4h |
| MCH-TT-122-02 | Implementar endpoint `create_order` con validación | 5h |
| MCH-TT-122-03 | Crear intent recognition para HACER_PEDIDO | 3h |
| MCH-TT-122-04 | Integrar con servicio de órdenes del backend | 4h |
| MCH-TT-122-05 | Testing end-to-end de flujo completo de pedido | 3h |

---

### MCH-US-123: Consultar Saldo de Fiado

**Story Points:** 5

**Como** cliente con crédito en el negocio
**Quiero** verificar mi saldo de deuda actual
**Para** saber cuánto debo y poder organizar mi pago

#### Criterios de Aceptación
- [CA-123-1] El cliente puede preguntar "¿Cuánto debo?"
- [CA-123-2] El bot responde con saldo actual y último movimiento
- [CA-123-3] Solo se muestra el saldo del cliente autenticado
- [CA-123-4] Se protege la privacidad: no se muestra info de otros clientes

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-123-01 | Crear endpoint `get_my_balance` con autenticación | 3h |
| MCH-TT-123-02 | Implementar reconocimiento de intent CONSULTA_SALDO | 2h |
| MCH-TT-123-03 | Formatear respuesta con movimientos recientes | 2h |
| MCH-TT-123-04 | Testing de seguridad (aislamiento por cliente) | 2h |

---

### MCH-US-124: Consultar Información del Negocio

**Story Points:** 4

**Como** cliente potencial o existente
**Quiero** obtener información del negocio (horarios, ubicación, promociones)
**Para** saber cuándo puedo ir, dónde está y qué ofertas tienen

#### Criterios de Aceptación
- [CA-124-1] El cliente puede preguntar "¿A qué hora abren?"
- [CA-124-2] El cliente puede preguntar "¿Dónde están?"
- [CA-124-3] El cliente puede preguntar "¿Qué promociones tienen?"
- [CA-124-4] El bot responde con información del negocio desde configuración tenant
- [CA-124-5] Se muestran horarios, ubicación, contacto y promociones activas

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-124-01 | Crear endpoint `get_business_info` | 2h |
| MCH-TT-124-02 | Crear endpoint `get_promotions` | 2h |
| MCH-TT-124-03 | Implementar intents HORARIOS, UBICACION, PROMOCIONES | 2h |
| MCH-TT-124-04 | Testing de información personalizada por tenant | 1h |

---

### MCH-US-125: Limitación de Permisos por Rol (Cliente vs Dueño)

**Story Points:** 7

**Como** arquitecto del sistema
**Quiero** que los clientes solo accedan a tools permitidas en el MCP Server
**Para** proteger información sensible del negocio y evitar acceso no autorizado

#### Criterios de Aceptación
- [CA-125-1] Los clientes pueden usar: search_products, get_product_price, check_availability, create_order, get_my_balance, get_business_info, get_promotions
- [CA-125-2] Los clientes NO pueden usar: update_product_price, get_sales_report, send_payment_reminder, delete_products, modify_business_settings
- [CA-125-3] El sistema valida el rol del usuario en cada llamada a tool
- [CA-125-4] Se registran intentos de acceso no autorizado en logs
- [CA-125-5] Los dueños mantienen acceso a todas las tools

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-125-01 | Implementar sistema de permisos por rol en MCP Server | 5h |
| MCH-TT-125-02 | Crear lista blanca de tools para clientes | 2h |
| MCH-TT-125-03 | Implementar validación de permisos antes de ejecutar tool | 4h |
| MCH-TT-125-04 | Agregar logging de intentos de acceso no autorizado | 2h |
| MCH-TT-125-05 | Testing de seguridad (intentos de escalación de privilegios) | 3h |

---

### Resumen de Story Points

| Historia | Descripción | SP |
|----------|-------------|-----|
| MCH-US-120 | Consultar Precios de Productos | 5 |
| MCH-US-121 | Consultar Disponibilidad de Productos | 5 |
| MCH-US-122 | Crear Pedido Via Chat | 8 |
| MCH-US-123 | Consultar Saldo de Fiado | 5 |
| MCH-US-124 | Consultar Información del Negocio | 4 |
| MCH-US-125 | Limitación de Permisos por Rol | 7 |
| **Total** | | **34** |

---

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| Customer chat flow | Pendiente | `whatsapp-service/flows/customer.flow.ts` |
| MCP tools (limited) | Pendiente | `mcp-server/tools/customer/` |
| Order creation | Pendiente | `backend/modules/orders/` |
| FAQ responses | Pendiente | `whatsapp-service/faq/` |

## Dependencias

### Depende de
- MCH-010 (MCP Server)
- MCH-011 (WhatsApp Service)
- MCH-014 (Gestion Clientes)

### Bloquea a
- MCH-015 (Pedidos via WhatsApp)

## Criterios de Aceptacion

- [ ] Consultas de precio funcionan
- [ ] Consultas de disponibilidad funcionan
- [ ] Pedidos se crean correctamente
- [ ] Saldo de fiado se muestra
- [ ] Info del negocio se muestra
- [ ] No hay fuga de informacion

## Personalizacion por Tenant

```typescript
// tenant_settings
{
  whatsapp_bot: {
    greeting: "¡Hola! Bienvenido a {{business_name}}",
    farewell: "¡Gracias por tu preferencia!",
    tone: "friendly", // formal, friendly, casual
    auto_suggest_products: true,
    show_promotions: true
  }
}
```

---

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