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-009: Recibir paquete físico en almacén

Caso de uso detallado para el operador que registra la llegada de un paquete físico al casillero de Miami.

Metadatos

Campo Valor
ID CU-009
Nombre Recibir paquete físico en almacén
Actor primario Operador
Módulo Operación de almacén
Prioridad Alta (MVP)
Frecuencia esperada Muy alta (todos los días)
Trazabilidad SRS RF-018, RF-019, RF-020

Descripción

El operador recibe físicamente un paquete en el casillero de Miami. Lo registra en el sistema escaneando o escribiendo el identificador del usuario, sube fotos, registra peso, dimensiones y estado del embalaje. Si el identificador es válido, el sistema asocia automáticamente el paquete a una prealerta (si existe) o al usuario; si no, va a la cola de conciliación.

Precondiciones

  • El operador tiene una sesión activa en el backoffice.
  • El operador tiene permiso para registrar recepciones.
  • El casillero físico está operativo.

Postcondiciones

Éxito con identificador válido: - Se crea un PhysicalPackage con estado recibido_sin_identificar (luego recibido_identificado). - Se asocia al User (por identificador). - Si existe una prealerta con ese tracking, se vincula. - Se sube al menos 1 foto a MinIO. - Se crea un package_event de recepción. - Se notifica al usuario.

Éxito con identificador inválido: - El paquete queda en received_sin_identificar y va a la cola de conciliación.

Flujo principal

  1. El operador accede a la pantalla Recepción del backoffice.
  2. El operador escanea (o escribe) el identificador del casillero de la etiqueta (CP-NNNNNN-D).
  3. El sistema valida el identificador con el algoritmo Mod-10.
  4. Si es válido:
  5. El sistema busca al usuario por locker_codes.full_code.
  6. Si el usuario existe y está activo: muestra sus datos (nombre, email) y prealertas abiertas con tracking similar.
  7. Si no hay match: va al paso 5b.
  8. El operador:
  9. (a) Confirma el usuario identificado
  10. (b) Va a flujo de identificación (conciliación, ver FA-1)
  11. El operador toma al menos 1 foto del paquete (obligatorio) y la sube a MinIO.
  12. El sistema valida que la foto se subió (URL firmada con TTL 5 min).
  13. El operador registra:
  14. Tracking (si está visible)
  15. Tienda (si se puede inferir)
  16. Peso (usando la báscula, en libras)
  17. Dimensiones (alto x ancho x largo, en pulgadas o cm)
  18. Estado del embalaje: Bien / Dañado / Reparado
  19. Ubicación física (estante, zona)
  20. El operador toca Confirmar recepción.
  21. El sistema:
    • Crea el PhysicalPackage con status = recibido_identificado
    • Lo asocia al User
    • Si hay prealerta con ese tracking, la vincula (purchase_status = vinculada_a_paquete)
    • Crea un package_event con tipo "received" y timestamp
    • Sube los metadatos a file_attachments (referencias a las fotos en MinIO)
  22. El sistema envía push al usuario: "Tu paquete de {tienda} {orden} ha llegado al almacén."

Flujos alternativos

FA-1: Identificador no legible (conciliación)

Si el operador no puede leer el identificador: 1. Toca Identificar más tarde. 2. El sistema crea el PhysicalPackage con status = recibido_sin_identificar y user_id = null. 3. El paquete va a la cola Conciliación. 4. El operador, después, puede buscar por tracking, nombre, descripción para identificarlo.

FA-2: Tracking coincide con prealerta pero identificador no

  1. El operador escanea el tracking.
  2. El sistema busca prealertas con ese tracking.
  3. Si encuentra, muestra: "Esto coincide con un reporte de {usuario}. ¿Confirmar?"
  4. Si el operador confirma, asocia al usuario (sin necesidad de identificador válido).
  5. Esto es válido según reglas-negocio.md (la regla 15 dice que el tracking es criterio secundario).

FA-3: Identificador con dígito verificador inválido

  • El sistema muestra error: "Identificador inválido: dígito verificador no coincide."
  • Sugiere: "Verifica que copiaste bien el código. Si es correcto, contacta a soporte."

FA-4: Usuario bloqueado

  • Si el User tiene is_active = false o está bloqueado_manual:
  • El sistema muestra: "Usuario bloqueado. Retener paquete y crear incidencia user_blocked."
  • El paquete queda con status = retenido_por_incidencia.

FA-5: Prealerta ya tiene paquete vinculado

  • Si el sistema detecta que esa prealerta ya tiene un PhysicalPackage:
  • Muestra: "Esta prealerta ya tiene un paquete asociado. ¿Es un duplicado?"
  • Si el operador confirma que es duplicado, crea el paquete pero con status = retenido_por_incidencia y motivo duplicate_package.

FA-6: Foto no se pudo subir

  • Si la conexión a MinIO falla:
  • La foto se guarda en el dispositivo del operador.
  • Se sube automáticamente cuando haya red.
  • El paquete se crea igual, pero con flag pending_photos = true.
  • El operador es notificado cuando las fotos se suban exitosamente.

FA-7: Cambio de estado posterior

  • El operador puede volver a un paquete y cambiar su estado (ej. de recibido_sin_identificar a identificado).
  • Cada cambio crea un package_event.

Excepciones

Excepción Causa Manejo
INVALID_LOCKER_CODE Mod-10 no coincide Error de validación
USER_NOT_FOUND Identificador válido pero sin usuario en BD Va a conciliación
USER_BLOCKED Usuario bloqueado/suspendido Retener + incidencia
DUPLICATE_PACKAGE Mismo tracking + mismo usuario en el día Marca como incidencia
PHOTO_UPLOAD_FAILED Error de MinIO Encolar localmente
TRACKING_ALREADY_EXISTS Mismo tracking en otro paquete del día Confirmar o marcar duplicado

Reglas de negocio aplicables

  • RN-25 (Identificador Mod-10): debe pasar validación antes de asociar. Ver identificador.md.
  • RN-26 (Foto obligatoria): al recibir, debe haber al menos 1 foto. Ver modulos/modulos.md.
  • RN-27 (Conciliación): paquetes sin identificador van a la cola. Ver backoffice.md.
  • RN-28 (Identificación secundaria): tracking es segundo criterio después del identificador. Ver reglas-negocio.md.

Criterios de aceptación

  • El identificador se valida con Mod-10 antes de aceptar.
  • La foto es obligatoria (no se puede confirmar sin foto).
  • El sistema asocia automáticamente a prealerta con mismo tracking.
  • Un paquete sin identificador va a conciliación.
  • Un usuario bloqueado genera retención automática.
  • El operador recibe push de "Recibido" en su dispositivo.
  • Cada cambio de estado queda registrado en package_events.
  • El sistema procesa al menos 50 recepciones/hora sin degradación.

Diagrama de actividad

flowchart TD
    A["Operador accede a Recepción"] --> B["Escanea identificador"]
    B --> C{"¿Mod-10 válido?"}
    C -- No --> D["Error: identificador inválido"]
    C -- Sí --> E["Busca usuario"]
    E --> F{"¿Existe?"}
    F -- No --> G["Va a conciliación"]
    F -- Sí --> H{"¿Activo?"}
    H -- No --> I["Retener + incidencia"]
    H -- Sí --> J["Muestra prealertas con mismo tracking"]
    J --> K{"¿Confirma?"}
    K -- No --> L["Va a conciliación"]
    K -- Sí --> M["Operador sube foto obligatoria"]
    M --> N["Registra tracking, peso, dimensiones, estado"]
    N --> O["Operador confirma recepción"]
    O --> P["Crea PhysicalPackage"]
    P --> Q["Vincula con prealerta (si hay)"]
    Q --> R["Crea package_event"]
    R --> S["Push al usuario"]

Diagrama de estados (paquete) — flujo recepción

stateDiagram-v2
    [*] --> recibido_sin_identificar: llega al almacén
    recibido_sin_identificar --> recibido_identificado: operador identifica
    recibido_sin_identificar --> pendiente_conciliacion: requiere revisión manual
    recibido_identificado --> en_almacen: almacenado
    pendiente_conciliacion --> recibido_identificado: conciliado
    pendiente_conciliacion --> retenido_por_incidencia: no se pudo identificar
    recibido_identificado --> retenido_por_incidencia: problema detectado

Pruebas asociadas

  • PT-120: Recepción con identificador válido y prealerta coincidente
  • PT-121: Recepción con identificador válido sin prealerta
  • PT-122: Recepción con identificador inválido (Mod-10 falla)
  • PT-123: Recepción sin foto (debe fallar)
  • PT-124: Recepción de usuario bloqueado
  • PT-125: Recepción de paquete duplicado
  • PT-126: Recepción sin identificador (conciliación)
  • PT-127: Conciliación posterior por tracking
  • PT-128: Cambio de estado posterior
  • PT-129: 50 recepciones por hora sin degradación
  • PT-130: Push de notificación al usuario