michangarrito/docs/01-epicas/MCH-015-pedidos-whatsapp.md

id	type	title	code	status	status_real	status_nota	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-015	Epic	MCH-015: Pedidos via WhatsApp	MCH-015	Completado	Completado	Integración WhatsApp-Backend para pedidos, BackendApiService creado	4	P1	2026-01-07	2026-01-18	4.0.1	55	blocks depends_on

MCH-015: Pedidos via WhatsApp

Metadata

• Codigo: MCH-015
• Fase: 4 - Pedidos y Clientes
• Prioridad: P1
• Estado: Completado
• Story Points: 55
• Fecha completado: 2026-01-18

Descripcion

Sistema completo de pedidos via WhatsApp: clientes pueden hacer pedidos conversando con el bot, el negocio recibe notificaciones, procesa el pedido, y confirma al cliente.

Objetivos

1. Recepcion de pedidos via chat
2. Confirmacion automatica o manual
3. Notificacion al negocio
4. Estado del pedido en tiempo real
5. Historial de pedidos por cliente

Alcance

Incluido

• Pedidos via chat natural (NLU)
• Carrito conversacional
• Confirmacion de pedido
• Notificacion push/WhatsApp al dueno
• Estados: recibido, preparando, listo, entregado
• Cancelacion de pedido

Excluido

• Pagos en linea dentro de WhatsApp
• Integracion con delivery apps (Rappi, Uber)
• Pedidos programados

Flujo de Pedido

Cliente Hace Pedido

Cliente: "Quiero pedir 2 Cocas y unas Sabritas"
Bot: "Perfecto! Tu pedido:
      - 2x Coca-Cola 600ml = $36
      - 1x Sabritas Original = $18
      Total: $54

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

Cliente: [Confirmar]

Bot: "¡Pedido #456 confirmado! 🎉
      Te avisamos cuando este listo.
      Tiempo estimado: 10-15 min"

Negocio Recibe Notificacion

[Push + WhatsApp al dueno]
"🛒 Nuevo Pedido #456

Cliente: Juan Perez (5512345678)
- 2x Coca-Cola 600ml
- 1x Sabritas Original
Total: $54

[Ver pedido] [Aceptar] [Rechazar]"

Actualizacion de Estado

[Dueno marca como "Listo"]

Bot -> Cliente:
"Tu pedido #456 esta listo! 📦
Puedes pasar a recogerlo.

Direccion: Calle Principal #123
Horario: Abierto hasta 10pm"

Modelo de Datos

Tablas (schema: orders)

orders

• id, tenant_id, customer_id, channel
• status (pending/confirmed/preparing/ready/delivered/cancelled)
• subtotal, delivery_fee, total
• delivery_type (pickup/delivery)
• delivery_address, scheduled_at
• notes, created_at, updated_at

order_items

• id, order_id, product_id
• quantity, unit_price, notes, total

order_status_history

• id, order_id, status, changed_by
• notes, created_at

Endpoints API

Metodo	Endpoint	Descripcion
GET	/orders	Listar pedidos
GET	/orders/:id	Obtener pedido
POST	/orders	Crear pedido
PUT	/orders/:id/status	Cambiar estado
POST	/orders/:id/cancel	Cancelar pedido
GET	/orders/pending	Pedidos pendientes
GET	/customers/:id/orders	Pedidos de cliente

Estados del Pedido

pending ──► confirmed ──► preparing ──► ready ──► delivered
    │           │             │           │
    └───────────┴─────────────┴───────────┴──► cancelled

Estado	Descripcion	Notifica Cliente
pending	Pedido recibido	Si
confirmed	Aceptado por negocio	Si
preparing	En preparacion	No
ready	Listo para recoger/enviar	Si
delivered	Entregado	Si
cancelled	Cancelado	Si

UI Components

OrderList (Dashboard)

• Tabla de pedidos del dia
• Filtros por estado
• Acciones rapidas

OrderDetail

• Info del cliente
• Items del pedido
• Cambio de estado
• Historial de estados

OrderNotification (Mobile)

• Push notification
• 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
orders.module	Completado	modules/orders/
WhatsApp order flow	Pendiente	whatsapp-service/flows/order.flow.ts
Order notifications	Pendiente	services/order-notification.service.ts
Orders dashboard	Pendiente	pages/Orders.tsx

Dependencias

Depende de

• MCH-011 (WhatsApp Service)
• MCH-013 (Chat cliente)
• MCH-014 (Gestion clientes)

Bloquea a

• MCH-016 (Entregas a domicilio)

Criterios de Aceptacion

• Pedidos se crean via WhatsApp
• Dueno recibe notificacion inmediata
• Estados se actualizan correctamente
• Cliente recibe confirmaciones
• Historial de pedidos funciona

Configuracion por Tenant

{
  orders: {
    enabled: true,
    auto_confirm: false, // o true para confirmar automaticamente
    estimated_time_minutes: 15,
    channels: ['whatsapp', 'web'],
    notifications: {
      push: true,
      whatsapp: true,
      sound: 'order_received'
    }
  }
}

---

Ultima actualizacion: 2026-01-17