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-013: Escanear código de barras/QR en almacén

Caso de uso detallado para que un operador use el lector físico (tablet con cámara o lector USB) para identificar paquetes en almacén.

Metadatos

Campo Valor
ID CU-013
Nombre Escanear código de barras/QR en almacén
Actor primario Operador de almacén
Actores secundarios Sistema de Notificaciones
Módulo Operación de almacén
Prioridad Alta (MVP)
Frecuencia esperada Muy alta (decenas por turno)
Trazabilidad SRS RF-051, RN-015, RN-018

Descripción

El operador escanea un código de barras o QR presente en un paquete físico para:

  • Identificar al destinatario (matching con CP-XXXXXX-D o con tracking de prealerta).
  • Ver el detalle del paquete en pantalla.
  • Iniciar la recepción del paquete (llena el formulario con datos previos).
  • Marcar como conciliado si estaba pendiente.

Este CU reemplaza la búsqueda manual y reduce drásticamente los errores de identificación.

Precondiciones

  • Operador autenticado con rol operator, admin o sysadmin.
  • Dispositivo con cámara o lector USB compatible (ver sección de hardware).
  • App backoffice abierta en la pantalla de escaneo o como overlay.

Postcondiciones

Éxito: - El paquete queda identificado y visible en el sistema. - Se registra el evento en audit_logs con method: barcode_scan.

Fallo: - Mensaje "No se pudo identificar el código" + opción de captura manual.

Flujo principal

  1. El operador abre la app backoffice en la pantalla Escanear.
  2. Apunta la cámara o lector al código del paquete.
  3. El sistema decodifica el código y extrae:
  4. Si es CP-XXXXXX-D → busca el casillero del usuario.
  5. Si es un tracking de UPS/USPS/FedEx → busca prealertas con ese tracking.
  6. Si es un código QR propio de IslaBox → busca el paquete por package_id.
  7. El sistema muestra un toast o vibración de éxito.
  8. Según el contexto:
  9. Si hay match exacto: abre la pantalla de detalle del paquete.
  10. Si hay match parcial: muestra candidatos para seleccionar.
  11. Si no hay match: ofrece crear nuevo paquete o marcar como pendiente_conciliacion.
  12. El operador selecciona la acción y continúa.

Códigos soportados

Tipo Formato Uso
CP-IslaBox CP-NNNNNN-D Identificador del casillero del usuario
Tracking UPS 1Z[0-9A-Z]{16} Tracking de paquete UPS
Tracking USPS 94[0-9]{20} o EA[0-9]{9}US Tracking de USPS
Tracking FedEx [0-9]{12,15} o [0-9]{4} [0-9]{4} [0-9]{4} Tracking FedEx
QR personalizado Formato ISLABOX:PKG:<package_id> QR pegado al recibir
EAN-13 / UPC Estándar retail Productos dentro del paquete
Code 128 Variable Etiquetas de envío de la tienda

Hardware soportado

  • Cámara del dispositivo (tablet Android con autofocus).
  • Lector USB HID (Honeywell, Zebra, Datalogic).
  • Lector Bluetooth (Socket Mobile, Zebra Bluetooth scanners).
  • Cámara del teléfono del operador (modo webcam USB).

Flujos alternativos

FA-1: Código no legible

  • Si el código está dañado o sucio:
  • El sistema pide captura manual.
  • El operador puede digitar el identificador o el tracking.

FA-2: Múltiples matches

  • Si el tracking coincide con varias prealertas:
  • El sistema muestra lista de candidatos con foto, fecha y valor.
  • El operador selecciona la correcta.

FA-3: Sin match

  • Si ningún código matchea:
  • El operador puede:
    • Crear un paquete nuevo (asociar a usuario por búsqueda manual).
    • Marcar como pendiente_conciliacion.
    • Escalar a supervisor.

FA-4: Hardware no disponible

  • Si la cámara o lector falla:
  • El sistema sugiere modo texto (digitar manualmente).
  • Se registra method: manual_entry en audit_logs.

Reglas de negocio

  • RN-015: Un tracking puede estar asociado a múltiples prealertas (caso normal: mismo tracking para 2 paquetes).
  • RN-018: El identificador CP-XXXXXX-D tiene dígito verificador; el sistema lo valida al escanear.
  • RN-019: Todo escaneo queda registrado en audit_logs con timestamp, operador, código leído, resultado y dispositivo.
  • RN-020: El escaneo solo es válido si el operador tiene rol autorizado.

Endpoints API

  • POST /api/v1/scan/identify — recibe código + tipo → devuelve match
  • GET /api/v1/scan/candidates/{tracking} — devuelve candidatos
  • POST /api/v1/scan/manual-lookup — búsqueda manual de texto

Pantallas

  • Backoffice: ScanScreen (overlay sobre cualquier pantalla)
  • Backoffice: ScanResultScreen
  • Backoffice: ManualLookupScreen

Eventos generados

  • PACKAGE_SCANNED — con metadata: code_type, match_result, operator_id

Notificaciones generadas

  • Solo si el match es exacto y el paquete estaba pendiente: notificación al usuario "Tu paquete ha sido recibido".