PIT Coffee · Roadmap de backend

Qué necesita el servidor para que funcione cada pantalla, botón y función del lienzo PIT Coffee · App web. Los códigos (M04, E03, P05, A15) son los nombres de las pantallas en Doop. Las pantallas de escritorio del cliente (E01 a E13) usan las mismas llamadas que las de móvil, así que aparecen junto a su equivalente.

0. Cómo leer este documento

• Es una propuesta. Sale de las pantallas dibujadas, no de código existente. Las rutas y los nombres de campos son sugeridos.
• Los números son de muestra. 5 % de cashback, 8 sellos, 400 m de reparto, $15 de entrega, 12 pedidos por franja y los demás valores vienen de las pantallas. Todos deben ser configurables y los define el negocio.
• No elige tecnología. Falta decidir el procesador de pagos, el proveedor de SMS y WhatsApp, y el de facturas (sección 10).
• Regla general: el servidor nunca confía en lo que calcula la página. Precios, totales, cashback, distancia, cupo y permisos se vuelven a calcular en el servidor.

1. Piezas del backend

2. Datos principales

3. Estados de un pedido

stateDiagram-v2
    [*] --> PorPagar
    PorPagar --> Pagado: cobro aprobado
    PorPagar --> Vencido: pasó el apartado
    Pagado --> EnPreparacion: Empezar (P04)
    Pagado --> Cancelado: cliente cancela (M32)
    EnPreparacion --> Listo: Marcar listo (P04)
    Listo --> Entregado: código en ventanilla (P05)
    Listo --> EnCamino: Lo llevo yo (P07)
    EnCamino --> Entregado: Entregado a (P09)
    EnCamino --> NoEntregado: no salió (P09)
    NoEntregado --> Entregado: pasa a recoger
    NoEntregado --> Reembolsado: decide admin (A02)
    Listo --> Guardado: no alcanza a pasar (M16)
    Guardado --> Entregado
    Pagado --> Reembolsado: parada cancelada (P03)
    Entregado --> [*]

Reglas que el servidor hace cumplir:

• Cancelar sin costo solo mientras el pedido está en «Pagado». En cuanto alguien toca «Empezar», la cancelación del cliente se rechaza con el motivo.
• Cashback y sellos se acreditan al pasar a «Entregado», no al pagar.
• Cada cambio de estado guarda un evento, avisa por tiempo real y dispara su aviso al cliente.
• Dos personas a la vez: si dos dispositivos cambian el mismo pedido, gana el primero y el segundo recibe el estado actual.

4. Flujos completos

4.1 Pedir y recoger en el camión

1. La página pide la ruta del día y el menú de la parada elegida (M01, M07).
2. El cliente arma el carrito. Cada cambio pide una cotización al servidor (M09).
3. Al tocar «Ir a pagar», el servidor valida todo otra vez y aparta un lugar en la franja por 5 minutos (M35).
4. Al tocar «Pagar», el servidor crea el pedido «Por pagar», aparta el cashback y cobra con una llave de idempotencia (M13).
5. El procesador confirma por webhook. El pedido pasa a «Pagado», recibe folio y código de 3 dígitos, y entra a la cola de preparación (P04).
6. Preparación toca «Empezar» y luego «Marcar listo». El cliente ve cada paso en vivo (M15, M16) y recibe el aviso de «listo».
7. En ventanilla, el personal teclea el código y toca «Entregar» (P05).
8. Al entregar: se acredita el cashback, se suman sellos, se desbloquea la recompensa si toca y se descuenta el inventario (M18).

4.2 Entrega cercana

Igual que 4.1, con estos cambios:

1. La cotización revisa que el lugar esté dentro del radio de reparto de la parada, suma la tarifa y exige el pedido mínimo. Si queda fuera, responde con las alternativas de M11.
2. Al quedar «Listo», el pedido aparece en la lista del repartidor (P07). «Lo llevo yo» lo asigna. «Llevarlo en el mismo viaje» lo suma al viaje abierto.
3. El teléfono del repartidor manda su posición mientras el viaje está abierto. El cliente la ve en M17.
4. «Ya llegué, avisarle» manda el aviso y arranca un reloj de 5 minutos (P08, P09).
5. «Entregado a…» cierra el pedido. Si el cliente no sale, «Regresar al camión» se activa al terminar el reloj, pide motivo y deja el pedido «No entregado» 20 minutos en la repisa. El reembolso lo decide la administradora (A02).

4.3 El pago falla

• Rechazado por el banco (M14): el pedido sigue «Por pagar», el lugar y el cashback siguen apartados 10 minutos, y el cliente puede pagar con otra tarjeta. Al vencer, se libera todo.
• Se corta la conexión al pagar: la página reintenta con la misma llave de idempotencia y el servidor contesta con el resultado del primer intento, sin cobrar dos veces.
• Cargo duplicado (M42): la conciliación detecta dos cobros para un pedido, reembolsa el segundo sola y avisa al cliente.
• Cobrado sin pedido (A15): la conciliación lo detecta y lo deja en «Pagos con problema» para que la administradora elija crear el pedido, reembolsar, o reembolsar con cashback de disculpa.

4.4 Retraso o cancelación de una parada

• Retraso (P03): cambia la hora de llegada, recalcula las horas prometidas de los pedidos anticipados y avisa a quienes tienen pedido y a quienes siguen la parada.
• Cancelación (P03, con PIN para el operador): cierra la parada, reembolsa cada pedido a su tarjeta, regresa el cashback usado, quita el cashback aún no acreditado y avisa a todos (M19). El cliente recibe la siguiente parada cercana para «Pedir lo mismo para mañana».

4.5 Sin conexión

• Cliente (M31): la página guarda la última respuesta de su pedido activo y su código. Para pedir o pagar exige conexión.
• Personal (P10): el dispositivo guarda los pedidos ya pagados y una cola de acciones («Empezar», «Marcar listo», «Entregar») con hora local. Al volver la señal las manda en orden. El servidor las acepta si el cambio de estado sigue siendo válido y contesta con el estado real si no.
• Camión sin señal: si el servidor deja de recibir latidos del camión, pone la parada «en pausa» sola y, pasados 10 minutos, avisa a la administradora por SMS (A17).

5. Pantalla por pantalla

Cada fila: qué toca la persona, qué llamada hace, qué manda, qué espera de vuelta y qué puede salir mal.

5.1 Cliente · entrar y cuenta

5.2 Cliente · ruta, menú y avisos

5.3 Cliente · carrito, pago y pedido

5.4 Cliente · lealtad y facturas

5.5 Personal

Toda llamada del personal lleva la sesión del PIN y revisa el permiso del puesto.

5.6 Administración

6. Tareas que corren solas

7. Avisos: qué los dispara y por dónde salen

Cada envío respeta las preferencias del cliente (M25), se guarda en la bandeja (M06) y registra si llegó o falló. En iPhone, la notificación de la página solo funciona si la persona agregó PIT Coffee a su pantalla de inicio, así que WhatsApp es el respaldo.

8. Tiempo real

Si el canal se cae, la página vuelve a pedir el estado completo al reconectar. Ninguna pantalla depende solo de mensajes en vivo.

9. Roadmap por fases

Cada fase deja algo que se puede usar y probar. El orden sigue las dependencias: no se puede cobrar sin pedido, ni pedir sin menú y parada.

Lo mínimo para operar un día real es de la fase 0 a la 6: entrar, pedir, pagar, preparar, entregar en ventanilla, avisar y poder reembolsar. Las fases 7 a 11 se pueden lanzar después sin rehacer lo anterior, siempre que desde la fase 3 el pedido ya guarde los campos de entrega, cashback y factura aunque vayan vacíos.

10. Decisiones que faltan (bloquean la fase 0)