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

MCH-016: Entregas a Domicilio

Metadata

• Codigo: MCH-016
• Fase: 4 - Pedidos y Clientes
• Prioridad: P2
• Estado: Pendiente
• Fecha estimada: Sprint 10-11

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

{
  type: 'radius',
  center: { lat: 19.4326, lng: -99.1332 },
  radius_km: 3,
  delivery_fee: 25,
  estimated_time: 30
}

Por Colonias

{
  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

Entregables

Entregable	Estado	Archivo
delivery.module	Pendiente	modules/delivery/
delivery_zones tabla	Pendiente	DDL
DeliveryZonesMap	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

• Zonas de cobertura se configuran
• Costo de envio se calcula correctamente
• Repartidor recibe notificacion
• Estados de entrega funcionan
• Confirmacion con foto funciona

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