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

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

```typescript
{
  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