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-006: Consultar detalle de un paquete¶

Caso de uso detallado para visualizar el detalle completo de un paquete físico, incluyendo timeline de eventos, estado de almacenaje y servicios contratados.

Metadatos¶

Campo	Valor
ID	CU-006
Nombre	Consultar detalle de un paquete
Actor primario	Usuario Final
Módulo	Paquetes y envíos
Prioridad	Alta (MVP)
Frecuencia esperada	Media
Trazabilidad SRS	RF-021, RF-022, RF-023

Descripción¶

El usuario accede al detalle de un paquete físico (proveniente del dashboard, listado de "En almacén" o desde una prealerta vinculada). Puede ver toda la información del paquete, su timeline de eventos, estado de almacenaje, y las acciones disponibles según el estado actual.

Precondiciones¶

El usuario tiene una sesión activa.
El usuario está autenticado como propietario del paquete (o el operador).

Postcondiciones¶

El usuario visualiza la información del paquete.
Si solicita una acción, se registra la intención (servicio adicional, etc.).

Flujo principal¶

El usuario accede al detalle de un paquete desde:
El dashboard (tarjeta de resumen)
El listado de "En almacén"
Una prealerta vinculada a un paquete
El sistema muestra la pantalla Detalle de Paquete con:

Información del paquete - Tienda - Número de orden - Tracking - Fecha de recepción - Peso - Dimensiones - Estado del embalaje (Bien / Dañado / Reparado) - Fotos del paquete recibido (galería)

Almacenaje - Fecha de recepción - Días en almacén (calculado) - Días gratis disponibles: 15 (resuelto en preguntas.md, configurable desde admin) - Días restantes (gratis) - Días restantes (gratis) - Costo por día extra: $0.50 USD (resuelto en mismo doc) - Total acumulado por almacenaje

Timeline de eventos - Lista cronológica de eventos con fecha, estado y descripción

Servicios contratados (si hay) - Inspección visual, prueba funcional, reempaque, devolución - Estado y costo de cada uno

Acciones disponibles (según estado) - Solicitar inspección - Solicitar prueba funcional - Solicitar reempaque - Solicitar devolución - Agregar a consolidación - Ver envío (si ya está despachado) - Pagar (si hay saldo pendiente)

El usuario puede hacer scroll para ver toda la información.
El usuario puede tocar cualquier acción disponible.

Flujos alternativos¶

FA-1: Paquete en `incidencia`¶

Si el estado es retenido_por_incidencia:
Se muestra un banner amarillo arriba: "Este paquete está retenido. Motivo: {razón}."
Si la incidencia es customs_hold, se muestran instrucciones.

FA-2: Paquete próximo a vencer¶

Si los días restantes son ≤ 3:
Banner amarillo: "Este paquete vence en {n} días. Confirma qué hacer: enviar, consolidar o devolver."

FA-3: Paquete ya en envío¶

Si el paquete está consolidado o despachado:
No se muestran acciones de servicios.
Se muestra un botón Ver envío que navega al detalle del envío.

FA-4: Usuario intenta acción no permitida por estado¶

El sistema valida las transiciones de estado antes de permitir la acción.
Ejemplo: no se puede consolidar un paquete en en_transito.

FA-5: Fotos no disponibles¶

Si el operador aún no subió fotos:
La galería muestra placeholder con texto "Las fotos se subirán cuando el paquete sea procesado."

Excepciones¶

Excepción	Causa	Manejo
`PACKAGE_NOT_FOUND`	ID inválido	Pantalla de error 404
`PACKAGE_NOT_OWNED`	Intentar ver paquete de otro usuario	"No tienes permiso"
`INVALID_STATE_TRANSITION`	Acción no permitida	Mensaje específico

Reglas de negocio aplicables¶

RN-15 (Almacenaje): el tiempo en almacén se muestra en el detalle del paquete, no en el dashboard general. Ver reglas-negocio.md.
RN-16 (Días gratis): configurables globalmente. Ver preguntas.md.
RN-17 (Cargos): se aplican automáticamente por día extra. Ver riesgos.md.

Criterios de aceptación¶

El detalle se carga en < 1 segundo.
El cálculo de días en almacén se actualiza en tiempo real cada vez que se abre la pantalla.
Las acciones disponibles cambian según el estado del paquete.
Un usuario no puede ver paquetes de otro usuario.
Las fotos se muestran con thumbnail y fullscreen al tocar.
El timeline es cronológico inverso (más reciente arriba).

Diagrama de actividad¶

flowchart TD
    A["Accede al detalle"] --> B["Carga PhysicalPackage"]
    B --> C["Carga PackageEvents"]
    C --> D["Calcula días en almacén"]
    D --> E["Renderiza pantalla"]
    E --> F{"¿Acción?"}
    F -- "Ver envío" --> G["Detalle del envío"]
    F -- "Solicitar servicio" --> H["Sheet de solicitud"]
    F -- "Agregar a consolidación" --> I["Pantalla de consolidación"]
    F -- "Pagar" --> J["Pantalla de pago"]

Diagrama de estados (paquete)¶

Ver estado-paquete.md.

Pruebas asociadas¶

PT-070: Ver detalle de paquete en almacén
PT-071: Ver detalle de paquete en tránsito
PT-072: Ver detalle de paquete entregado
PT-073: Ver detalle de paquete en incidencia
PT-074: Cálculo correcto de días en almacén
PT-075: Banner de almacenaje por vencer
PT-076: Acciones disponibles según estado
PT-077: Intentar ver paquete ajeno (debe fallar)
PT-078: Visualización de fotos del paquete
PT-079: Visualización del timeline