Guía de Operaciones - Pre-Ventas (Pre-Sale)

📋 Índice

1. ¿Qué es Pre-Venta?
2. ¿Cómo Funciona?
3. Configuración de Pre-Venta
4. Subida de Stock
5. Procesamiento de Pre-Órdenes

🎯 ¿Qué es Pre-Venta?

La Pre-Venta es una funcionalidad que permite a los usuarios hacer pedidos antes de que el stock esté disponible. Esto es especialmente útil para tiendas como Krispy Kreme que reciben stock fresco diariamente.

Beneficios

• ✅ Para el Usuario: Asegura su pedido antes de que se agote el stock
• ✅ Para la Tienda: Conoce la demanda antes de preparar el stock
• ✅ Para Cheaf: Mejora la experiencia del usuario y reduce cancelaciones

🔄 ¿Cómo Funciona?

Flujo General

1. Se configura las tiendas con la cantidad de stock que se subirá en preventa
   ↓
2. Cron job ejecuta comando "upload_presale_stock"
   ↓
3. Sistema sube stock SOLO a tiendas con configuración de pre-venta
   ↓
4. Usuario ve tienda con "Pre-Venta Disponible" y stock disponible
   ↓
5. Usuario hace pedido (stock > 0)
   ↓
6. Si es dentro de ventana de pre-venta, se crea como "Pre-Orden"
   ↓
7. Pre-orden queda PENDIENTE (sin cobro, sin delivery, sin Deliverect)
   → Orden con status "Requested" (3)
   ↓
8. Krispy Kreme sube stock REAL mediante su sistema
   ↓
9. Sistema procesa pre-órdenes automáticamente (FIFO):
   - Cobra al usuario
   - Configura delivery (si aplica)
   - Envía a Deliverect (si aplica)
   → Orden permanece en status "Requested" (3)
   ↓
10. Tienda cambia manualmente el status a "Booked" cuando está lista

Notas Importantes:

• El cobro NO es inmediato. Se cobra cuando Krispy Kreme sube el stock real.
• El delivery y Deliverect se procesan cuando se sube el stock real, no al crear la pre-orden.
• Los cupones y créditos se aplican de manera normal al crear la pre-orden (no se difieren).
• Las órdenes en pre-venta se marcan con la bandera is_presale = True para identificarlas fácilmente en queries y reportes.

Ventana de Pre-Venta

La ventana de pre-venta se cierra automáticamente cuando la tienda llega a su hora de apertura (collect_after).

• Ventana Abierta: Los usuarios pueden hacer pre-órdenes

  • Desde: presale_opening_time (ej: 4:00 PM)
  • Hasta: collect_after (hora de apertura de la tienda, ej: 10:00 AM del día siguiente)

• Ventana Cerrada: Los usuarios NO pueden hacer pre-órdenes

  • Cuando: current_time >= collect_after (la tienda ya abrió)
  • Las órdenes normales siguen procesándose sin problema
  • Solo la opción de pre-venta aparece cerrada en el frontend

Ejemplo de Timeline:

16:00 (4 PM)  → Pre-venta ABIERTA ✅
22:00 (10 PM) → Pre-venta ABIERTA ✅
09:59 AM      → Pre-venta ABIERTA ✅ (tienda aún no abre)
10:00 AM      → Pre-venta CERRADA ❌ (tienda abrió - collect_after)
11:00 AM      → Pre-venta CERRADA ❌ (órdenes normales disponibles)

⚙️ Configuración de Pre-Venta

Paso 1: Habilitar Pre-Venta en una Tienda

1. Ir al Admin de Django → Restaurants → Stores

2. Buscar y seleccionar la tienda que deseas configurar

3. Dentro de la pantalla de la tienda, ir a la sección "Pre Sale Configurations"

4. Configurar los campos:

   • Presale Opening Time: Hora de apertura (formato 24h, ej: 16:00:00)
   • Enabled: ✅ Marcar para activar

5. Guardar

Paso 2: Configurar Stock por Menú

1. Ir al Admin de Django → Restaurants → Menus

2. Buscar el menú de la tienda

3. Editar el menú:

   • Presale Stock Amount: Cantidad de stock que se subirá (ej: 50)
   • Si es 0, ese menú NO participará en pre-venta

4. Guardar

Ejemplo de Configuración

Tienda: Krispy Kreme Centro

• Presale Opening Time: 16:00:00 (4:00 PM)
• Enabled: ✅ Sí

Menús:

• Docena Original Glazed → Presale Stock Amount: 50
• Media Docena Surtida → Presale Stock Amount: 30
• Café Americano → Presale Stock Amount: 0 (no participa)

📦 Subida de Stock

Proceso de Subida de Stock

Importante: Krispy Kreme sube sus paquetes mediante su propio sistema interno. El comando upload_presale_stock NO crea los paquetes, solo:

• ✅ Toma el stock configurado en presale_stock_amount
• ✅ Lo agrega al stock actual del menú
• ✅ Solo afecta tiendas con configuración de pre-venta activa

Opción 1: Subida Automática (Recomendado)

El comando se ejecuta automáticamente cada 15 minutos mediante un cron job. Esto permite detectar la ventana de apertura de pre-venta de cada tienda.

Configuración en Cron:

# Ejecuta cada 15 minutos para detectar ventanas de apertura
*/15 * * * * /path/to/command upload_presale_stock

¿Cómo funciona?

• El cron se ejecuta cada 15 minutos
• Verifica qué tiendas tienen su ventana de pre-venta abierta
• Solo procesa tiendas con PreSaleConfiguration activa (enabled = True)
• Solo afecta menús con presale_stock_amount > 0

Opción 2: Subida Manual

Usar el comando manual cuando sea necesario:

# Subir stock para todas las tiendas configuradas
make manage cmd="upload_presale_stock --force"

# Subir stock para una tienda específica
make manage cmd="upload_presale_stock --force --store-id 123"

# Modo prueba (no hace cambios reales)
make manage cmd="upload_presale_stock --force --dry-run"

# Sin enviar notificaciones a favoritos
make manage cmd="upload_presale_stock --force --skip-favorites"

¿Qué Hace la Subida de Stock?

1. ✅ Identifica tiendas elegibles: Solo tiendas con PreSaleConfiguration activa
2. ✅ Agrega stock: Suma el presale_stock_amount al stock actual de cada menú
3. ✅ Registra cambios: Crea entrada en historial (RestaurantMenuLog)
4. ✅ Actualiza Firestore: Sincroniza con la app móvil
5. ✅ Envía notificaciones: Push a usuarios con la tienda en favoritos

Ejemplo:

• Stock actual: 10 unidades
• Presale Stock Amount: 50 unidades
• Resultado: Stock nuevo = 60 unidades

🔄 Procesamiento de Pre-Órdenes

¿Cuándo se Procesan?

Las pre-órdenes se procesan automáticamente cuando Krispy Kreme sube stock real mediante su sistema interno.

¿Qué Sucede al Procesar?

Cuando se procesa una pre-orden, el sistema ejecuta:

1. ✅ Cobra al usuario con el token de pago guardado
2. ✅ Configura delivery si el pedido es para entrega
3. ✅ Envía a Deliverect si la tienda tiene integración activa

Importante:

• El usuario NO recibe notificación cuando se procesa la pre-orden.
• Las órdenes se crean con status "Requested" (3) y permanecen en ese status después de procesarse.

Orden de Procesamiento

Las pre-órdenes se procesan en orden FIFO (First In, First Out):

• La primera pre-orden creada se procesa primero
• La segunda pre-orden se procesa después, y así sucesivamente
• Esto garantiza equidad para todos los usuarios

Estados de Pre-Orden

Nota: Todas las pre-órdenes mantienen el status "Requested" (3) independientemente de su estado de procesamiento. La tienda debe cambiar manualmente el status a "Booked" cuando el pedido esté listo para recoger.

📊 Monitoreo y Reportes

Ver Pre-Órdenes en el Admin

1. Ir al Admin de Django → Orders → Pre orders
2. Filtrar por:
   • Status: Estado de la pre-orden (Pending, Completed, Failed, etc.)
   • Payment provider: Proveedor de pago (Conekta, MercadoPago, Stripe)
   • Created at: Fecha de creación
3. Buscar por:
   • ID de pre-orden
   • ID de orden
   • ID del usuario

Información Importante

Cada pre-orden muestra:

• Order: Número de orden asociada
• Status: Estado actual
• Created At: Cuándo se creó
• Processed At: Cuándo se procesó (si aplica)
• Payment Provider: Proveedor de pago (Conekta, MercadoPago, etc.)