399 lines
11 KiB
Markdown
399 lines
11 KiB
Markdown
---
|
|
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
|