michangarrito/docs/01-epicas/MCH-016-entregas-domicilio.md

---
id: EPIC-MCH-016
type: Epic
title: "MCH-016: Entregas a Domicilio"
code: MCH-016
status: Completado
status_real: "Completado"
status_nota: "Backend delivery module con zonas, tracking, WhatsApp integration"
phase: 4
priority: P2
created_at: 2026-01-07
updated_at: 2026-01-18
simco_version: "4.0.1"
story_points: 34
dependencies:
  blocks: []
  depends_on: []
---

# MCH-016: Entregas a Domicilio

## Metadata
- **Codigo:** MCH-016
- **Fase:** 4 - Pedidos y Clientes
- **Prioridad:** P2
- **Estado:** Completado
- **Fecha completado:** 2026-01-18
- **Story Points:** 34

## Descripcion

Sistema de entregas a domicilio para micro-negocios: definicion de zonas de cobertura, costos de envio, asignacion de repartidores, y tracking basico del pedido.

## Objetivos

1. Definir zonas de cobertura
2. Configurar costos de envio
3. Asignar repartidores
4. Tracking basico de entrega
5. Confirmacion de entrega

## Alcance

### Incluido
- Zonas de cobertura (radio o colonias)
- Costo de envio fijo o por zona
- Asignacion manual de repartidor
- Estados: asignado, en camino, entregado
- Confirmacion con foto/firma

### Excluido
- GPS tracking en tiempo real
- Optimizacion de rutas
- Integracion con apps de delivery
- Repartidores externos (Rappi, Uber)

## Modelo de Datos

### Tablas Adicionales

**delivery_zones**
- id, tenant_id, name, type (radius/polygon)
- coordinates (JSONB), delivery_fee
- min_order, estimated_time, active

**deliveries**
- id, order_id, assigned_to (user_id)
- status, pickup_at, delivered_at
- delivery_address, notes
- proof_photo_url, signature_url

## Flujo de Entrega

### Cliente Solicita Delivery
```
Bot: "¿Como quieres recibir tu pedido?
      [Paso a recoger] [Enviar a domicilio]"

Cliente: [Enviar a domicilio]

Bot: "¿A que direccion lo enviamos?"

Cliente: "Calle Hidalgo 45, Col. Centro"

Bot: "Perfecto! Envio a Col. Centro = $25
      Total con envio: $79
      Tiempo estimado: 30-45 min

      ¿Confirmas?
      [Confirmar] [Cambiar direccion]"
```

### Asignacion de Repartidor
```
1. Pedido confirmado con delivery
2. Dueno ve pedido en dashboard
3. Asigna a repartidor (empleado)
4. Repartidor recibe notificacion
5. Cliente notificado: "Tu pedido va en camino"
```

### Confirmacion de Entrega
```
1. Repartidor llega a direccion
2. Entrega pedido
3. Toma foto de entrega (opcional)
4. Marca como entregado en app
5. Cliente recibe: "Pedido entregado!"
```

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /delivery/zones | Zonas de cobertura |
| POST | /delivery/zones | Crear zona |
| PUT | /delivery/zones/:id | Editar zona |
| DELETE | /delivery/zones/:id | Eliminar zona |
| POST | /delivery/check-coverage | Verificar cobertura |
| POST | /orders/:id/assign-delivery | Asignar repartidor |
| PUT | /deliveries/:id/status | Actualizar estado |
| POST | /deliveries/:id/confirm | Confirmar entrega |

## Configuracion de Zonas

### Por Radio
```typescript
{
  type: 'radius',
  center: { lat: 19.4326, lng: -99.1332 },
  radius_km: 3,
  delivery_fee: 25,
  estimated_time: 30
}
```

### Por Colonias
```typescript
{
  type: 'polygon',
  name: 'Centro',
  colonias: ['Centro', 'Roma Norte', 'Condesa'],
  delivery_fee: 30,
  estimated_time: 45
}
```

## UI Components

### DeliveryZonesMap
- Mapa con zonas definidas
- Edicion visual de poligonos
- Configuracion de tarifas

### DeliveryAssignment
- Lista de pedidos pendientes de asignar
- Dropdown de repartidores disponibles
- Boton asignar

### DeliveryTracking (Mobile - Repartidor)
- Lista de entregas asignadas
- Boton "En camino"
- Boton "Entregado" + foto

## Historias de Usuario

### MCH-US-150: Gestion de Zonas de Cobertura
**Story Points:** 8

**Como** dueno de negocio
**Quiero** definir zonas de cobertura por radio o poligono
**Para** controlar las areas donde ofrezco servicio de entrega a domicilio

#### Criterios de Aceptacion
- [CA-150-1] El sistema permite crear zonas por radio (km desde punto central)
- [CA-150-2] El sistema permite crear zonas por poligono (lista de colonias)
- [CA-150-3] Cada zona tiene nombre, tipo, coordenadas y estado activo/inactivo
- [CA-150-4] Las zonas se visualizan en un mapa interactivo
- [CA-150-5] Se pueden editar y eliminar zonas existentes
- [CA-150-6] El sistema valida que no existan zonas con el mismo nombre

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-150-01 | Crear tabla delivery_zones con campos requeridos | 2h |
| MCH-TT-150-02 | Implementar DeliveryZonesService con CRUD | 4h |
| MCH-TT-150-03 | Crear endpoints REST para zonas | 3h |
| MCH-TT-150-04 | Desarrollar componente DeliveryZonesMap | 6h |
| MCH-TT-150-05 | Implementar edicion visual de poligonos | 4h |
| MCH-TT-150-06 | Agregar validaciones y tests | 3h |

---

### MCH-US-151: Configuracion de Costos de Envio
**Story Points:** 5

**Como** dueno de negocio
**Quiero** configurar tarifas de envio por zona
**Para** cobrar el costo adecuado segun la distancia de entrega

#### Criterios de Aceptacion
- [CA-151-1] Cada zona tiene un costo de envio configurable
- [CA-151-2] Se puede definir un pedido minimo por zona
- [CA-151-3] Se puede configurar tiempo estimado de entrega por zona
- [CA-151-4] El bot muestra el costo de envio al cliente antes de confirmar
- [CA-151-5] El costo de envio se suma correctamente al total del pedido
- [CA-151-6] Se valida que la direccion este dentro de una zona activa

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-151-01 | Agregar campos delivery_fee, min_order, estimated_time a zonas | 1h |
| MCH-TT-151-02 | Implementar endpoint check-coverage | 3h |
| MCH-TT-151-03 | Integrar calculo de costo en flujo de pedido | 4h |
| MCH-TT-151-04 | Actualizar UI para configurar tarifas | 3h |
| MCH-TT-151-05 | Agregar validacion de pedido minimo | 2h |

---

### MCH-US-152: Asignacion de Repartidores
**Story Points:** 8

**Como** dueno o empleado del negocio
**Quiero** asignar pedidos a repartidores disponibles
**Para** gestionar las entregas de manera organizada

#### Criterios de Aceptacion
- [CA-152-1] Se pueden ver pedidos pendientes de asignar en dashboard
- [CA-152-2] Se muestra lista de repartidores disponibles (rol delivery)
- [CA-152-3] Al asignar, el sistema crea registro en tabla deliveries
- [CA-152-4] El repartidor recibe notificacion de asignacion
- [CA-152-5] El cliente recibe notificacion de que su pedido fue asignado
- [CA-152-6] Se puede reasignar un pedido a otro repartidor

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-152-01 | Crear tabla deliveries con campos requeridos | 2h |
| MCH-TT-152-02 | Implementar DeliveriesService | 4h |
| MCH-TT-152-03 | Crear endpoint assign-delivery | 3h |
| MCH-TT-152-04 | Desarrollar componente DeliveryAssignment | 5h |
| MCH-TT-152-05 | Implementar notificaciones a repartidor | 3h |
| MCH-TT-152-06 | Implementar notificaciones a cliente | 2h |
| MCH-TT-152-07 | Agregar logica de reasignacion | 2h |

---

### MCH-US-153: Tracking de Estado de Entrega
**Story Points:** 8

**Como** repartidor
**Quiero** actualizar el estado de mis entregas asignadas
**Para** mantener informados al negocio y al cliente sobre el progreso

#### Criterios de Aceptacion
- [CA-153-1] El repartidor ve lista de entregas asignadas en app movil
- [CA-153-2] Puede marcar entrega como "En camino" con timestamp
- [CA-153-3] Puede marcar entrega como "Entregado" con timestamp
- [CA-153-4] Los estados validos son: asignado, en_camino, entregado
- [CA-153-5] El cliente recibe notificacion en cada cambio de estado
- [CA-153-6] El dashboard muestra estado actual de todas las entregas

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-153-01 | Implementar endpoint update-status | 3h |
| MCH-TT-153-02 | Desarrollar pantalla mobile DeliveryTracking | 6h |
| MCH-TT-153-03 | Implementar logica de transicion de estados | 2h |
| MCH-TT-153-04 | Agregar timestamps pickup_at y delivered_at | 1h |
| MCH-TT-153-05 | Implementar notificaciones push al cliente | 4h |
| MCH-TT-153-06 | Actualizar dashboard con estados en tiempo real | 3h |

---

### MCH-US-154: Confirmacion de Entrega con Evidencia
**Story Points:** 5

**Como** repartidor
**Quiero** confirmar la entrega con foto o firma opcional
**Para** tener evidencia de que el pedido fue entregado correctamente

#### Criterios de Aceptacion
- [CA-154-1] El repartidor puede tomar foto de la entrega
- [CA-154-2] El repartidor puede capturar firma del cliente (opcional)
- [CA-154-3] La foto/firma se almacena y vincula a la entrega
- [CA-154-4] El dueno puede ver la evidencia en el historial
- [CA-154-5] El cliente recibe mensaje de confirmacion con resumen
- [CA-154-6] El sistema registra hora exacta de confirmacion

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-154-01 | Implementar endpoint confirm-delivery | 2h |
| MCH-TT-154-02 | Agregar upload de foto a storage | 3h |
| MCH-TT-154-03 | Implementar captura de firma en mobile | 4h |
| MCH-TT-154-04 | Guardar URLs de evidencia en deliveries | 1h |
| MCH-TT-154-05 | Mostrar evidencia en historial del dashboard | 3h |
| MCH-TT-154-06 | Enviar confirmacion al cliente via WhatsApp | 2h |

---

### Resumen de Story Points

| Historia | Descripcion | SP |
|----------|-------------|---:|
| MCH-US-150 | Gestion de Zonas de Cobertura | 8 |
| MCH-US-151 | Configuracion de Costos de Envio | 5 |
| MCH-US-152 | Asignacion de Repartidores | 8 |
| MCH-US-153 | Tracking de Estado de Entrega | 8 |
| MCH-US-154 | Confirmacion de Entrega con Evidencia | 5 |
| **TOTAL** | | **34** |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| delivery.module | Completado | `backend/src/modules/delivery/` |
| Delivery entities | Completado | `entities/delivery.entity.ts`, `delivery-zone.entity.ts` |
| DeliveryService | Completado | `delivery.service.ts` |
| DeliveryController | Completado | `delivery.controller.ts` |
| DTOs | Completado | `dto/delivery.dto.ts` |
| DDL schema | Completado | `database/schemas/delivery.sql` |
| WhatsApp integration | Completado | `whatsapp-service/common/backend-api.service.ts` |
| DeliveryZonesMap UI | Pendiente | `components/delivery/` |
| Mobile delivery screen | Pendiente | `mobile/screens/Delivery.tsx` |

## Dependencias

### Depende de
- MCH-015 (Pedidos WhatsApp)
- MCH-002 (Auth - para repartidores)

### Bloquea a
- Ninguno

## Criterios de Aceptacion

- [x] Zonas de cobertura se configuran (backend API)
- [x] Costo de envio se calcula correctamente
- [x] Estados de entrega funcionan (state machine)
- [x] API endpoints implementados
- [x] WhatsApp service integration
- [ ] UI DeliveryZonesMap (futuro sprint)
- [ ] Mobile delivery screen (futuro sprint)

## Roles

| Rol | Permisos |
|-----|----------|
| owner | Configurar zonas, ver todas las entregas |
| employee | Asignar entregas, ver entregas |
| delivery | Ver entregas asignadas, actualizar estado |

---

**Ultima actualizacion:** 2026-01-18