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

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-016	Epic	MCH-016: Entregas a Domicilio	MCH-016	Pendiente	4	P2	2026-01-07	2026-01-17	4.0.1	34	blocks depends_on

MCH-016: Entregas a Domicilio

Metadata

• Codigo: MCH-016
• Fase: 4 - Pedidos y Clientes
• Prioridad: P2
• Estado: Pendiente
• Fecha estimada: Sprint 10-11
• 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

{
  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

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