MCH-015: Estandarizar épica Pedidos via WhatsApp según SIMCO 4.0.1

2026-01-17 04:31:01 -06:00 · 2026-01-17 04:31:01 -06:00 · adab7aea24
commit adab7aea24
parent 184d21d6ce
5 changed files with 870 additions and 14 deletions
--- a/docs/01-epicas/MCH-011-whatsapp-service.md
+++ b/docs/01-epicas/MCH-011-whatsapp-service.md
@ -7,11 +7,15 @@ status: Completado
 phase: 3
 priority: P0
 created_at: 2026-01-10
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
+story_points: 55
 dependencies:
  blocks: []
-  depends_on: []
+  depends_on:
+    - MCH-001
+    - MCH-002
+    - MCH-010
 ---

 # MCH-011: WhatsApp Service
@ -22,6 +26,8 @@ dependencies:
 - **Prioridad:** P0
 - **Estado:** Completado
 - **Fecha completado:** 2026-01-10
+- **Story Points:** 55
+- **SIMCO Version:** 4.0.1

 ## Descripcion

@ -44,12 +50,16 @@ Servicio de integracion con WhatsApp Business API de Meta. Permite a los negocio
 - Procesamiento via MCP Server
 - Webhooks verificados
 - Cola de mensajes (Redis)
+- Multi-tenant con routing por numero
+- Manejo de diferentes tipos de mensaje
+- Procesamiento asincrono con workers

 ### Excluido
 - WhatsApp Web (no oficial)
 - Grupos de WhatsApp
 - Estados/historias
 - Llamadas de voz/video
+- Integracion con redes sociales adicionales

 ## Arquitectura

--- a/docs/01-epicas/MCH-012-chat-llm-dueno.md
+++ b/docs/01-epicas/MCH-012-chat-llm-dueno.md
@ -7,8 +7,9 @@ status: Pendiente
 phase: 3
 priority: P1
 created_at: 2026-01-07
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
+story_points: 47
 dependencies:
  blocks: []
  depends_on: []
@ -22,6 +23,7 @@ dependencies:
 - **Prioridad:** P1
 - **Estado:** Pendiente
 - **Fecha estimada:** Sprint 7-8
+- **Story Points:** 47

 ## Descripcion

@ -163,6 +165,260 @@ Enviado: 10:00 AM Lunes
 ¿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 |
--- a/docs/01-epicas/MCH-013-chat-llm-cliente.md
+++ b/docs/01-epicas/MCH-013-chat-llm-cliente.md
@ -7,8 +7,9 @@ status: Pendiente
 phase: 3
 priority: P1
 created_at: 2026-01-07
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
+story_points: 34
 dependencies:
  blocks: []
  depends_on: []
@ -22,6 +23,7 @@ dependencies:
 - **Prioridad:** P1
 - **Estado:** Pendiente
 - **Fecha estimada:** Sprint 8-9
+- **Story Points:** 34

 ## Descripcion

@ -183,6 +185,171 @@ const customerTools = [
 - 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 |
@ -228,4 +395,4 @@ const customerTools = [

 ---

-**Ultima actualizacion:** 2026-01-07
+**Ultima actualizacion:** 2026-01-17
--- a/docs/01-epicas/MCH-014-gestion-clientes.md
+++ b/docs/01-epicas/MCH-014-gestion-clientes.md
@ -7,8 +7,9 @@ status: Completado
 phase: 4
 priority: P1
 created_at: 2026-01-06
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
+story_points: 21
 dependencies:
  blocks: []
  depends_on: []
@ -21,6 +22,7 @@ dependencies:
 - **Fase:** 4 - Pedidos y Clientes
 - **Prioridad:** P1
 - **Estado:** Completado
+- **Story Points:** 21
 - **Fecha inicio:** 2026-01-06
 - **Fecha fin:** 2026-01-07

@ -165,6 +167,187 @@ Sistema completo de gestion de clientes: registro, historial de compras, saldo d
 ### Tags Personalizados
 - Ejemplos: "vecino", "oficina", "escuela", "mayoreo"

+## Historias de Usuario
+
+### MCH-US-130: Registrar cliente nuevo
+**Story Points:** 3
+
+**Como** empleado de ventas
+**Quiero** crear un cliente rapidamente durante una venta
+**Para** registrar contactos y poder consultar su historial en futuras transacciones
+
+#### Criterios de Aceptación
+- [CA-130-1] El formulario solicita nombre (requerido) y telefono (requerido)
+- [CA-130-2] Email y direccion son opcionales
+- [CA-130-3] El cliente se crea exitosamente y se muestra en el listado
+- [CA-130-4] Se valida que no exista otro cliente con el mismo telefono
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-130-01 | Crear modelo Customer en backend | 2h |
+| MCH-TT-130-02 | Implementar endpoint POST /customers | 3h |
+| MCH-TT-130-03 | Crear componente CustomerForm.tsx | 4h |
+| MCH-TT-130-04 | Validar duplicados por telefono | 2h |
+
+---
+
+### MCH-US-131: Ver historial de compras de cliente
+**Story Points:** 3
+
+**Como** dueno de tienda
+**Quiero** consultar todas las compras historicas de un cliente
+**Para** entender su comportamiento de compra y patrones
+
+#### Criterios de Aceptación
+- [CA-131-1] El historial muestra todas las compras del cliente
+- [CA-131-2] Se muestran fecha, monto, productos y metodo de pago
+- [CA-131-3] El historial esta ordenado por fecha descendente
+- [CA-131-4] Se muestra total historico y cantidad de compras
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-131-01 | Crear vista customer_purchases en BD | 2h |
+| MCH-TT-131-02 | Implementar endpoint GET /customers/:id/purchases | 3h |
+| MCH-TT-131-03 | Crear componente CustomerPurchaseHistory.tsx | 4h |
+| MCH-TT-131-04 | Agregar metricas: total, promedio, frecuencia | 2h |
+
+---
+
+### MCH-US-132: Gestionar saldo de fiado
+**Story Points:** 4
+
+**Como** dueno de tienda
+**Quiero** ver y actualizar el saldo de fiado de un cliente
+**Para** controlar credito y cobros pendientes
+
+#### Criterios de Aceptación
+- [CA-132-1] Se muestra el limite de credito y saldo actual
+- [CA-132-2] Se puede registrar un abono manualmente
+- [CA-132-3] Se muestra historial de movimientos de fiado
+- [CA-132-4] Se previene exceder el limite de credito en ventas
+- [CA-132-5] Se calcula saldo automaticamente desde sales
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-132-01 | Extender tabla customers con campos credit | 2h |
+| MCH-TT-132-02 | Crear tabla credit_movements | 2h |
+| MCH-TT-132-03 | Implementar logica de validacion de credito | 4h |
+| MCH-TT-132-04 | Crear componente CreditHistory.tsx | 4h |
+| MCH-TT-132-05 | Endpoint para registrar abono | 3h |
+
+---
+
+### MCH-US-133: Enviar mensaje WhatsApp a cliente
+**Story Points:** 3
+
+**Como** dueno de tienda
+**Quiero** enviar mensajes WhatsApp a mis clientes
+**Para** comunicarme sobre pedidos, recordatorios y cobros
+
+#### Criterios de Aceptación
+- [CA-133-1] Existe boton "Enviar WhatsApp" en ficha de cliente
+- [CA-133-2] Se puede escribir un mensaje personalizado
+- [CA-133-3] Se puede seleccionar un template predefinido
+- [CA-133-4] El mensaje se envia al numero de cliente almacenado
+- [CA-133-5] Se registra el envio en el historial del cliente
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-133-01 | Configurar servicio WhatsApp API | 3h |
+| MCH-TT-133-02 | Crear tabla message_log para audit | 2h |
+| MCH-TT-133-03 | Implementar endpoint POST /customers/:id/message | 3h |
+| MCH-TT-133-04 | Crear componente WhatsAppSender.tsx | 4h |
+| MCH-TT-133-05 | Crear templates predefinidos | 2h |
+
+---
+
+### MCH-US-134: Segmentar clientes por frecuencia
+**Story Points:** 4
+
+**Como** dueno de tienda
+**Quiero** segmentar mis clientes por frecuencia de compra
+**Para** identificar clientes frecuentes e inactivos
+
+#### Criterios de Aceptación
+- [CA-134-1] Se calculan 4 segmentos: Frecuente (>=4/mes), Regular (2-3/mes), Ocasional (1/mes), Inactivo (0/30d)
+- [CA-134-2] Se puede filtrar el listado de clientes por segmento
+- [CA-134-3] El calculo se actualiza diariamente
+- [CA-134-4] Se muestra el segmento en la ficha del cliente
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-134-01 | Crear función de calculo de frecuencia | 2h |
+| MCH-TT-134-02 | Agregar columnas frequency_segment a customers | 1h |
+| MCH-TT-134-03 | Crear job batch para actualizar diariamente | 3h |
+| MCH-TT-134-04 | Implementar filtro en GET /customers | 2h |
+| MCH-TT-134-05 | Mostrar segmento en UI | 2h |
+
+---
+
+### MCH-US-135: Asignar tags y notas a cliente
+**Story Points:** 2
+
+**Como** dueno de tienda
+**Quiero** agregar tags personalizados (vecino, oficina, mayoreo) y notas a clientes
+**Para** categorizar y recordar detalles importantes
+
+#### Criterios de Aceptación
+- [CA-135-1] Se puede asignar multiples tags a un cliente
+- [CA-135-2] Se pueden crear tags personalizados
+- [CA-135-3] Se puede escribir y editar notas
+- [CA-135-4] Los tags aparecen en el listado y detalle del cliente
+- [CA-135-5] Se puede filtrar por tags
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-135-01 | Agregar columnas tags (JSONB) y notes a customers | 1h |
+| MCH-TT-135-02 | Crear CRUD para tags | 2h |
+| MCH-TT-135-03 | Agregar inputs de tags/notas en CustomerForm | 2h |
+| MCH-TT-135-04 | Implementar filtro por tags | 2h |
+
+---
+
+### MCH-US-136: Segmentar clientes por valor de compra
+**Story Points:** 2
+
+**Como** dueno de tienda
+**Quiero** segmentar mis clientes por valor total de compra
+**Para** identificar clientes de alto valor e inactivos
+
+#### Criterios de Aceptación
+- [CA-136-1] Se calculan 3 segmentos: Alto (>=2000/mes), Medio (500-2000/mes), Bajo (<500/mes)
+- [CA-136-2] Se puede filtrar el listado por segmento de valor
+- [CA-136-3] El calculo se actualiza diariamente
+- [CA-136-4] Se muestra el segmento en la ficha del cliente
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-136-01 | Crear función de calculo de valor | 2h |
+| MCH-TT-136-02 | Agregar columna value_segment a customers | 1h |
+| MCH-TT-136-03 | Actualizar job batch | 1h |
+| MCH-TT-136-04 | Mostrar en UI y filtro | 2h |
+
+---
+
+### Resumen de Story Points
+| Historia | Descripción | SP |
+|----------|-------------|-----|
+| MCH-US-130 | Registrar cliente nuevo | 3 |
+| MCH-US-131 | Ver historial de compras | 3 |
+| MCH-US-132 | Gestionar saldo de fiado | 4 |
+| MCH-US-133 | Enviar mensaje WhatsApp | 3 |
+| MCH-US-134 | Segmentar por frecuencia | 4 |
+| MCH-US-135 | Asignar tags y notas | 2 |
+| MCH-US-136 | Segmentar por valor | 2 |
+| **Total** | | **21** |
+
 ## Entregables

 | Entregable | Estado | Archivo |
@ -210,4 +393,4 @@ customer.value_segment = calculateValue(customer)

 ---

-**Ultima actualizacion:** 2026-01-07
+**Ultima actualizacion:** 2026-01-17
--- a/docs/01-epicas/MCH-015-pedidos-whatsapp.md
+++ b/docs/01-epicas/MCH-015-pedidos-whatsapp.md
@ -7,8 +7,9 @@ status: Pendiente
 phase: 4
 priority: P1
 created_at: 2026-01-07
-updated_at: 2026-01-10
-simco_version: "3.8.0"
+updated_at: 2026-01-17
+simco_version: "4.0.1"
+story_points: 55
 dependencies:
  blocks: []
  depends_on: []
@ -21,6 +22,7 @@ dependencies:
 - **Fase:** 4 - Pedidos y Clientes
 - **Prioridad:** P1
 - **Estado:** Pendiente
+- **Story Points:** 55
 - **Fecha estimada:** Sprint 9-10

 ## Descripcion
@ -162,6 +164,244 @@ pending ──► confirmed ──► preparing ──► ready ──► delive
 - Sonido distintivo
 - Accion rapida: Aceptar/Rechazar

+## Historias de Usuario
+
+### MCH-US-140: Cliente solicita pedido via WhatsApp
+**Story Points:** 8
+
+**Como** cliente
+**Quiero** hacer un pedido conversando naturalmente con el bot
+**Para** comprar productos sin usar una interfaz tradicional
+
+#### Criterios de Aceptación
+- [CA-140-1] El bot entiende solicitudes de compra en lenguaje natural
+- [CA-140-2] El bot construye un carrito conversacional
+- [CA-140-3] El cliente puede agregar/quitar items
+- [CA-140-4] Se muestra el total antes de confirmar
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-140-01 | Implementar NLU para interpretación de pedidos | 5h |
+| MCH-TT-140-02 | Crear carrito conversacional | 5h |
+| MCH-TT-140-03 | Integrar con inventario de productos | 3h |
+
+---
+
+### MCH-US-141: Cliente confirma pedido
+**Story Points:** 5
+
+**Como** cliente
+**Quiero** confirmar mi pedido con un clic
+**Para** asegurar que mi compra se procese
+
+#### Criterios de Aceptación
+- [CA-141-1] Botón de confirmación claramente visible
+- [CA-141-2] Resumen final antes de confirmar
+- [CA-141-3] Opción para cancelar/modificar
+- [CA-141-4] Mensaje de éxito con número de pedido
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-141-01 | UI de confirmación de pedido | 4h |
+| MCH-TT-141-02 | Validación y persistencia en BD | 3h |
+
+---
+
+### MCH-US-142: Negocio recibe notificación de nuevo pedido
+**Story Points:** 8
+
+**Como** dueño del negocio
+**Quiero** recibir notificación inmediata cuando llega un pedido
+**Para** comenzar a prepararlo rápidamente
+
+#### Criterios de Aceptación
+- [CA-142-1] Notificación push instantánea
+- [CA-142-2] También envía WhatsApp al dueño
+- [CA-142-3] Incluye detalles del cliente y items
+- [CA-142-4] Sonido distintivo para alertar
+- [CA-142-5] Enlace directo para ver pedido completo
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-142-01 | Servicio de notificaciones push | 5h |
+| MCH-TT-142-02 | Integración de envío WhatsApp | 4h |
+| MCH-TT-142-03 | Configuración de sonidos | 2h |
+
+---
+
+### MCH-US-143: Negocio acepta o rechaza pedido
+**Story Points:** 5
+
+**Como** dueño del negocio
+**Quiero** aceptar o rechazar un pedido rápidamente
+**Para** confirmar si puedo prepararlo o si hay algún problema
+
+#### Criterios de Aceptación
+- [CA-143-1] Botones de Aceptar/Rechazar en notificación
+- [CA-143-2] Campo opcional de motivo de rechazo
+- [CA-143-3] Cliente recibe confirmación inmediata
+- [CA-143-4] Pedido se marca como confirmado o cancelado
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-143-01 | Endpoints de aceptación/rechazo | 3h |
+| MCH-TT-143-02 | Lógica de cambio de estado | 3h |
+| MCH-TT-143-03 | Notificación al cliente | 2h |
+
+---
+
+### MCH-US-144: Cliente ve estado de su pedido en tiempo real
+**Story Points:** 8
+
+**Como** cliente
+**Quiero** ver el estado actual de mi pedido
+**Para** saber cuándo estará listo
+
+#### Criterios de Aceptación
+- [CA-144-1] Estado visible en el chat
+- [CA-144-2] Actualizaciones en tiempo real (WebSocket)
+- [CA-144-3] Muestra tiempo estimado de entrega
+- [CA-144-4] Estados: recibido, preparando, listo, entregado
+- [CA-144-5] Notificación cada vez que cambia el estado
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-144-01 | Máquina de estados para pedidos | 4h |
+| MCH-TT-144-02 | WebSocket para actualizaciones en vivo | 5h |
+| MCH-TT-144-03 | Interfaz visual de timeline | 4h |
+
+---
+
+### MCH-US-145: Negocio actualiza estado del pedido
+**Story Points:** 5
+
+**Como** dueño del negocio
+**Quiero** marcar el estado del pedido (preparando, listo, entregado)
+**Para** mantener al cliente informado
+
+#### Criterios de Aceptación
+- [CA-145-1] Cambio de estado desde dashboard o WhatsApp
+- [CA-145-2] Transiciones válidas según máquina de estados
+- [CA-145-3] Historial de cambios guardado
+- [CA-145-4] Cliente notificado automáticamente
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-145-01 | UI en dashboard para cambiar estado | 3h |
+| MCH-TT-145-02 | Servicio de auditoría de cambios | 3h |
+| MCH-TT-145-03 | Validación de transiciones | 2h |
+
+---
+
+### MCH-US-146: Historial de pedidos del cliente
+**Story Points:** 5
+
+**Como** cliente
+**Quiero** ver mis pedidos anteriores
+**Para** reordenar fácilmente los mismos productos
+
+#### Criterios de Aceptación
+- [CA-146-1] Lista de todos los pedidos históricos
+- [CA-146-2] Filtros por fecha/estado
+- [CA-146-3] Opción para repetir un pedido anterior
+- [CA-146-4] Detalles de cada pedido disponibles
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-146-01 | API de historial de pedidos | 3h |
+| MCH-TT-146-02 | Interfaz de cliente en chat | 3h |
+| MCH-TT-146-03 | Función de "repetir pedido" | 2h |
+
+---
+
+### MCH-US-147: Cliente cancela pedido
+**Story Points:** 3
+
+**Como** cliente
+**Quiero** cancelar mi pedido si cambio de opinión
+**Para** no pagar por algo que no quiero
+
+#### Criterios de Aceptación
+- [CA-147-1] Opción de cancelación disponible antes de "listo"
+- [CA-147-2] Confirmación antes de cancelar
+- [CA-147-3] Dueño notificado de la cancelación
+- [CA-147-4] Pedido marcado como cancelado en historial
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-147-01 | Endpoint de cancelación | 2h |
+| MCH-TT-147-02 | Validaciones de estado | 1h |
+| MCH-TT-147-03 | Notificación al negocio | 1h |
+
+---
+
+### MCH-US-148: Dashboard de pedidos del negocio
+**Story Points:** 8
+
+**Como** dueño del negocio
+**Quiero** un dashboard con todos mis pedidos
+**Para** gestionar el flujo de trabajo eficientemente
+
+#### Criterios de Aceptación
+- [CA-148-1] Vista de tabla con pedidos del día
+- [CA-148-2] Filtros por estado (pendiente, preparando, listo)
+- [CA-148-3] Acciones rápidas: aceptar, marcar listo, cancelar
+- [CA-148-4] Sonido/alert para nuevos pedidos
+- [CA-148-5] Información del cliente con teléfono
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-148-01 | Componente OrderList | 4h |
+| MCH-TT-148-02 | Filtros y búsqueda | 3h |
+| MCH-TT-148-03 | Acciones rápidas en UI | 3h |
+
+---
+
+### MCH-US-149: Historial de estados del pedido
+**Story Points:** 3
+
+**Como** usuario (cliente o dueño)
+**Quiero** ver el historial completo de cambios en un pedido
+**Para** verificar cuándo se hizo cada acción
+
+#### Criterios de Aceptación
+- [CA-149-1] Timeline de cambios de estado
+- [CA-149-2] Muestra quién hizo el cambio y cuándo
+- [CA-149-3] Notas adicionales si existen
+- [CA-149-4] Accesible desde detalles del pedido
+
+#### Tareas
+| ID | Tarea | Estimación |
+|----|-------|------------|
+| MCH-TT-149-01 | API de historial de estados | 2h |
+| MCH-TT-149-02 | Componente visual de timeline | 2h |
+
+---
+
+### Resumen de Story Points
+| Historia | Descripción | SP |
+|----------|-------------|-----|
+| MCH-US-140 | Cliente solicita pedido via WhatsApp | 8 |
+| MCH-US-141 | Cliente confirma pedido | 5 |
+| MCH-US-142 | Negocio recibe notificación | 8 |
+| MCH-US-143 | Negocio acepta o rechaza | 5 |
+| MCH-US-144 | Cliente ve estado en tiempo real | 8 |
+| MCH-US-145 | Negocio actualiza estado | 5 |
+| MCH-US-146 | Historial de pedidos cliente | 5 |
+| MCH-US-147 | Cliente cancela pedido | 3 |
+| MCH-US-148 | Dashboard de pedidos negocio | 8 |
+| MCH-US-149 | Historial de estados pedido | 3 |
+| **Total** | | **55** |
+
 ## Entregables

 | Entregable | Estado | Archivo |
@ -209,4 +449,4 @@ pending ──► confirmed ──► preparing ──► ready ──► delive

 ---

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