michangarrito/docs/01-epicas/MCH-013-chat-llm-cliente.md

id	type	title	code	status	status_real	status_nota	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-013	Epic	MCH-013: Chat LLM Cliente	MCH-013	Completado	Completado	Implementado en Sprint 2 - Role-based chat con funciones limitadas para clientes	3	P1	2026-01-07	2026-01-18	4.0.1	34	blocks depends_on

MCH-013: Chat LLM Cliente

Metadata

• Codigo: MCH-013
• Fase: 3 - Asistente IA
• Prioridad: P1
• Estado: Completado
• Sprint Asignado: Sprint 2
• Fecha completado: 2026-01-18
• 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

// 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

// 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

// 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