michangarrito/docs/01-epicas/MCH-012-chat-llm-dueno.md

id	type	title	code	status	status_real	status_nota	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-012	Epic	MCH-012: Chat LLM Dueno	MCH-012	Completado	Completado	Implementado en Sprint 2 - Role-based chat con funciones de dueño	3	P1	2026-01-07	2026-01-18	4.0.1	55	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

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

• Consultas de venta funcionan
• Consultas de inventario funcionan
• Modificacion de precios funciona
• Consultas de fiados funcionan
• Alertas proactivas se envian
• 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