Saltar a contenido

Documento histórico

Este documento se conserva solo para trazabilidad. Consulte el índice maestro para la fuente vigente.

Documento histórico — no usar como fuente de decisiones actuales

Reemplazado por la versión canónica del 2026-07-11. Conservar solo como trazabilidad histórica.

CU-007: Consolidar paquetes para envío

Caso de uso detallado para agrupar varios paquetes físicos del usuario en un único envío hacia Cuba.

Metadatos

Campo Valor
ID CU-007
Nombre Consolidar paquetes para envío
Actor primario Usuario Final
Actores secundarios Operador (en modo manual)
Módulo Paquetes y envíos
Prioridad Alta (MVP)
Frecuencia esperada Media
Trazabilidad SRS RF-024, RF-025

Descripción

El usuario selecciona 2 o más paquetes en estado en_almacen o listo_para_consolidar, los agrupa en una consolidación, define el destinatario final, la vía de envío (barco/avión) y recibe una cotización.

Precondiciones

  • El usuario tiene una sesión activa.
  • El usuario tiene al menos 2 paquetes en estado en_almacen o listo_para_consolidar.
  • El usuario tiene KYC aprobado (consolidación para envío lo requiere).

Postcondiciones

Éxito: - Se crea una Consolidation con estado borrador (o completa si se confirma). - Se crean ConsolidationPackage asociando cada paquete a la consolidación. - Si se cotiza, se crea un Quote con vigencia 7 días. - Los paquetes cambian a estado reservado_para_consolidacion.

Flujo principal

  1. El usuario accede a la pantalla Consolidar desde:
  2. El detalle de un paquete (botón "Agregar a consolidación")
  3. El listado de "En almacén" con selección múltiple
  4. El sistema muestra la lista de paquetes disponibles con checkbox por cada uno.
  5. El usuario selecciona 2+ paquetes.
  6. El sistema habilita el botón Continuar.
  7. El usuario toca Continuar.
  8. El sistema muestra la pantalla Resumen de consolidación con:
  9. Lista de paquetes seleccionados (tienda, tracking, peso)
  10. Peso total calculado
  11. Selector de vía de envío: Barco ($2.40/lb) o Avión ($3.35/lb)
  12. Selector de destinatario (de sus destinatarios guardados)
  13. Costo estimado: peso_total × tarifa_vía
  14. Servicios adicionales aplicables (si hay)
  15. El usuario confirma vía y destinatario.
  16. El usuario toca Crear consolidación.
  17. El sistema valida:
  18. Mismo destinatario
  19. Mismo usuario
  20. KYC aprobado
  21. Todos los paquetes en estado permitido
  22. Vía válida
  23. El sistema adquiere un lock distribuido en Redis sobre consolidation:{user_id} para evitar race conditions.
  24. El sistema crea la Consolidation con status = completa (transición directa al confirmar).
  25. El sistema crea los ConsolidationPackage para cada paquete.
  26. El sistema actualiza cada PhysicalPackage.status = reservado_para_consolidacion.
  27. El sistema calcula el total_weight y crea un Quote con:
    • total_amount = total_weight × shipping_rate + additional_services
    • expires_at = now + 7 días
    • status = pendiente_pago
  28. El sistema crea un Shipment en estado cotizado.
  29. Libera el lock.
  30. El sistema navega a la pantalla Cotización y Pago (ver CU-008).

Flujos alternativos

FA-1: Solo 1 paquete seleccionado

  • En el paso 3, si el usuario selecciona solo 1 paquete:
  • El sistema deshabilita el botón Continuar y muestra "Necesitas al menos 2 paquetes para consolidar."
  • Excepción: si el paquete ya está marcado para consolidar individualmente, permite envío individual.

FA-2: Paquete ya reservado

  • Si un paquete ya está en otra consolidación:
  • El checkbox aparece deshabilitado.
  • Al pasar el cursor: "Este paquete ya está reservado en otra consolidación."

FA-3: KYC no aprobado

  • Si el usuario no tiene KYC aprobado al llegar al paso 9:
  • El sistema muestra pantalla de bloqueo: "Necesitas completar tu verificación de identidad para consolidar."
  • Ofrece CTA Iniciar KYC (navega a CU-010).

FA-4: Cambio de vía

  • El usuario puede cambiar entre barco y avión antes de confirmar.
  • El costo se recalcula en tiempo real.

FA-5: Agregar más paquetes después

  • Una vez creada la consolidación (estado completa), el usuario puede:
  • Volver al paso de selección
  • Agregar más paquetes (si están disponibles y no vencidos)
  • Esto invalida la cotización anterior y genera una nueva.

FA-6: Eliminar paquete de la consolidación

  • Antes del pago, el usuario puede quitar un paquete de la consolidación.
  • Esto recalcula el costo y actualiza el Shipment.total_weight.

FA-7: Cancelar consolidación

  • El usuario puede cancelar una consolidación en estado borrador o completa (antes del pago).
  • Los paquetes vuelven a estado en_almacen.
  • La cotización se marca como cancelada.

Excepciones

Excepción Causa Manejo
INSUFFICIENT_PACKAGES < 2 paquetes seleccionados Mensaje en pantalla
KYC_NOT_APPROVED Sin KYC aprobado Pantalla de bloqueo
PACKAGE_NOT_AVAILABLE Estado no permite consolidar Filtrar de la lista
LOCK_NOT_ACQUIRED Race condition con otro proceso Reintentar 3 veces
INVALID_DESTINEE Destinatario no pertenece al usuario Mensaje

Reglas de negocio aplicables

  • RN-6 (Consolidación mínima): 2+ paquetes del mismo usuario, mismo KYC aprobado, mismo destinatario final. Ver reglas-negocio.md.
  • RN-18 (Estados): los paquetes deben estar en en_almacen o listo_para_consolidar. Ver estados.md.
  • RN-19 (Cotización): vigencia 7 días, se invalida al cambiar paquetes o vía. Ver modulos/servicios-cargos.md.
  • RN-20 (Lock distribuido): previene race conditions al consolidar concurrentemente. Ver arquitectura-backend.md.

Criterios de aceptación

  • El usuario puede seleccionar 2+ paquetes.
  • El costo se calcula correctamente: peso × tarifa_vía + servicios_adicionales.
  • El cambio de vía recalcula el costo en tiempo real.
  • No se puede consolidar con KYC no aprobado.
  • La consolidación usa lock distribuido (test concurrente con 2 requests simultáneos debe crear solo 1).
  • Los paquetes cambian a reservado_para_consolidacion.
  • La cotización tiene vigencia 7 días.
  • Agregar/quitar paquetes invalida la cotización anterior.

Diagrama de actividad

flowchart TD
    A["Accede a Consolidar"] --> B["Lista paquetes disponibles"]
    B --> C["Selecciona 2+"]
    C --> D{"¿Tiene KYC aprobado?"}
    D -- No --> E["Pantalla bloqueo KYC"]
    D -- Sí --> F["Pantalla resumen"]
    F --> G["Selecciona vía"]
    G --> H["Selecciona destinatario"]
    H --> I["Costo estimado"]
    I --> J["Toca 'Crear'"]
    J --> K["Lock Redis"]
    K --> L["Crea Consolidation"]
    L --> M["Crea ConsolidationPackages"]
    M --> N["Paquetes → reservado_para_consolidacion"]
    N --> O["Calcula Quote"]
    O --> P["Crea Shipment cotizado"]
    P --> Q["Libera lock"]
    Q --> R["Pantalla Cotización y Pago"]

Diagrama de estados (consolidación)

stateDiagram-v2
    [*] --> borrador
    borrador --> completa: confirmar paquetes
    borrador --> cancelada: cancelar
    completa --> cotizada: cotizar
    completa --> cancelada: cancelar
    cotizada --> pendiente_pago: aceptar cotización
    cotizada --> cancelada: cancelar
    pendiente_pago --> pagada: pagar
    pendiente_pago --> cancelada: cancelar / expirar
    pagada --> en_preparacion: operador prepara
    en_preparacion --> despachada: operador despacha
    despachada --> [*]
    cancelada --> [*]

Pruebas asociadas

  • PT-090: Consolidar 2 paquetes (caso normal)
  • PT-091: Consolidar con KYC no aprobado (debe fallar)
  • PT-092: Intentar consolidar 1 solo paquete (debe fallar)
  • PT-093: Cambio de vía recalcula costo
  • PT-094: Consolidación concurrente (test de stress)
  • PT-095: Agregar paquete a consolidación existente
  • PT-096: Quitar paquete de consolidación
  • PT-097: Cancelar consolidación antes del pago
  • PT-098: Cotización generada con vigencia correcta
  • PT-099: Lock distribuido funciona bajo carga