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-005: Reportar una compra (prealerta)

Caso de uso detallado para crear, editar, listar y ver el detalle de una prealerta (reporte de compra).

Metadatos

Campo Valor
ID CU-005
Nombre Reportar una compra (prealerta)
Actor primario Usuario Final
Módulo Prealerta
Prioridad Alta (MVP)
Frecuencia esperada Alta (cada compra)
Trazabilidad SRS RF-013, RF-014, RF-015, RF-016, RF-017

Descripción

El usuario reporta una compra que hizo en una tienda online, antes de que el paquete llegue al casillero de Miami. Este reporte anticipado (prealerta) facilita la identificación y el procesamiento del paquete cuando llegue.

Precondiciones

  • El usuario tiene una sesión activa.
  • El usuario ya tiene su identificador CP-NNNNNN-D asignado.
  • El usuario accedió a ReporteForm desde el dashboard, la FAB o el listado de reportes.

Postcondiciones

Éxito: - Se crea un PurchaseReport con estado reportada (si tiene tracking) o reportada_sin_tracking (si no). - El reporte queda asociado al User. - Se muestra en la lista de prealertas. - El operador podrá identificar el paquete cuando llegue al almacén.

Flujo principal

  1. El usuario toca Reportar compra (banner del dashboard, FAB o tab Reportes).
  2. El sistema muestra la pantalla ReporteForm con los campos:
  3. Tienda (texto libre: Amazon, SHEIN, Temu, otro)
  4. Número de orden
  5. Fecha de compra (campo con placeholder DD/MM/AAAA)
  6. Tracking (opcional)
  7. Categoría (dropdown con 15 opciones)
  8. Descripción del producto
  9. Cantidad
  10. Valor pagado (USD)
  11. Enlace del producto (opcional)
  12. Instrucciones especiales (opcional, multilínea)
  13. ¿Desea consolidar? (Sí / No, radio buttons)
  14. Servicios adicionales (3 checkboxes: Inspección, Prueba funcional, Reempaque)
  15. Foto/captura de la orden (opcional)
  16. Remitente (selector — por defecto el usuario registrado)
  17. Destinatario (selector con lista + opción "Agregar nuevo")
  18. El usuario completa los campos requeridos (marcados con asterisco rojo).
  19. El sistema valida en tiempo real:
  20. Tienda, número de orden, fecha, categoría, descripción, cantidad, valor, destinatario son obligatorios
  21. Cantidad > 0
  22. Valor > 0
  23. Fecha con formato DD/MM/AAAA válida
  24. Tracking (si presente): alfanumérico, mínimo 5 caracteres
  25. Enlace (si presente): formato URL válido
  26. El usuario toca Reportar.
  27. El sistema crea el PurchaseReport con purchase_status = reportada o reportada_sin_tracking según si tiene tracking.
  28. El sistema crea los PurchaseItem asociados.
  29. Si marcó consolidar = Sí, marca consolidation_preference = true.
  30. Si marcó servicios adicionales, crea los ServiceRequest correspondientes en estado solicitado.
  31. Si subió foto, sube a MinIO (bucket order-evidence) y guarda la referencia.
  32. El sistema navega a ReporteDetalle con el reporte recién creado.
  33. Se muestra toast "Reporte enviado con éxito" y notificación push de confirmación.

Flujos alternativos

FA-1: Editar prealerta

  • El usuario accede a un reporte en estado borrador o requiere_correccion desde el detalle.
  • Toca Editar y el sistema abre el mismo formulario con valores pre-rellenados.
  • El usuario modifica y guarda.
  • Si el estado era requiere_correccion, al guardar vuelve a reportada.

FA-2: Cancelar prealerta

  • El usuario accede a un reporte en estado borrador o reportada_sin_tracking.
  • Toca Cancelar reporte.
  • El sistema muestra confirmación: "¿Cancelar el reporte de {tienda} {orden}? Esta acción no se puede deshacer."
  • Si confirma, el sistema marca purchase_status = cancelada_por_usuario.
  • Si el reporte ya tiene un PhysicalPackage asociado, no se puede cancelar (debe contactar soporte).

FA-3: Actualizar tracking

  • El usuario accede a un reporte en estado reportada_sin_tracking.
  • En el detalle, ve un campo Agregar tracking y un botón Actualizar.
  • Ingresa el tracking y toca Actualizar.
  • El sistema valida formato.
  • El sistema actualiza tracking_number y purchase_status = tracking_actualizado.
  • Se crea un package_event con la actualización.

FA-4: Listar prealertas

  • El usuario toca el tab Reportes en la bottom nav.
  • El sistema muestra la lista de prealertas con: tienda, estado (badge), tracking, número de orden, fecha de compra.
  • Cada ítem es tappable → abre el detalle.
  • Hay un FAB (+) para nuevo reporte.

FA-5: Ver detalle de prealerta

  • El usuario toca un ítem de la lista.
  • El sistema navega a ReporteDetalle mostrando:
  • Todos los campos del reporte
  • Timeline de eventos
  • Acciones disponibles según el estado

FA-6: Foto no se pudo subir

  • Si la conexión falla al subir la foto:
  • La foto se guarda en cola local y se reintenta cuando haya red.
  • El reporte se crea igual, sin la foto (campo capture_uri = null).
  • Se notifica al usuario: "Reporte creado, pero la foto se subirá cuando haya conexión."

FA-7: Categoría restringida o prohibida

  • Si el usuario selecciona una categoría con accepted = No (prohibida):
  • Muestra mensaje: "Este artículo no puede ser enviado por {categoría}."
  • Sugiere categorías alternativas.
  • No permite enviar el reporte.

FA-8: Categoría condicional con factura requerida

  • Si selecciona una categoría con requires_invoice = true (ej. Medicamentos):
  • Muestra mensaje: "Esta categoría requiere comprobante de compra."
  • El campo "Factura" se vuelve obligatorio (en lugar de opcional).

Excepciones

Excepción Causa Manejo
INVALID_DATE_FORMAT Fecha mal escrita Mensaje inline
INVALID_TRACKING_FORMAT Tracking < 5 chars o con caracteres inválidos Mensaje inline
INVALID_URL Enlace mal formado Mensaje inline
INVALID_AMOUNT Valor ≤ 0 Mensaje inline
RESTRICTED_CATEGORY Categoría prohibida Mensaje + sugerencia
MISSING_INVOICE Categoría requiere factura Bloquea envío
PHOTO_UPLOAD_FAILED Error de red Encolar + notificar
RECIPIENT_NOT_FOUND Destinatario eliminado entre medio Recargar selector

Reglas de negocio aplicables

  • RN-11 (Tracking opcional): la prealerta puede existir sin tracking. Ver estados.md.
  • RN-12 (Prealerta no bloquea por KYC): el usuario puede reportar sin KYC aprobado. Ver kyc.md.
  • RN-13 (Categorías): 15 categorías con flags regulatorios. Ver aduana.md.
  • RN-14 (Sin diversidad): si todos los productos son iguales, puede activar revisión. Ver aduana-normativa-cuba.md.

Criterios de aceptación

  • El formulario valida todos los campos requeridos antes de enviar.
  • El usuario puede crear un reporte sin tracking (estado reportada_sin_tracking).
  • El usuario puede agregar el tracking después (estado cambia a tracking_actualizado).
  • Un reporte con paquete físico asociado no se puede cancelar.
  • Las 15 categorías aparecen en el dropdown.
  • Categorías con requires_invoice = true obligan a subir factura.
  • Categorías con accepted = No bloquean el envío.
  • El destinatario es seleccionable de la lista del usuario o se puede agregar uno nuevo desde el sheet.
  • El reporte aparece en la lista con el badge de estado correcto.

Diagrama de actividad

flowchart TD
    A["Toca 'Reportar compra'"] --> B["Pantalla ReporteForm"]
    B --> C["Completa campos"]
    C --> D{"¿Válidos?"}
    D -- No --> E["Errores inline"]
    E --> C
    D -- Sí --> F["Toca 'Reportar'"]
    F --> G{"¿Tiene tracking?"}
    G -- Sí --> H["Estado: reportada"]
    G -- No --> I["Estado: reportada_sin_tracking"]
    H --> J["Sube foto (si hay)"]
    I --> J
    J --> K["Crea PurchaseReport + PurchaseItems"]
    K --> L["Crea ServiceRequests (si marcó)"]
    L --> M["Pantalla ReporteDetalle"]
    M --> N["Toast + push de confirmación"]

Diagrama de estados (prealerta)

stateDiagram-v2
    [*] --> borrador
    borrador --> reportada: enviar
    borrador --> cancelada_por_usuario: cancelar
    reportada --> tracking_actualizado: agregar tracking
    reportada --> vinculada_a_paquete: operador asocia paquete
    reportada --> requiere_correccion: operador marca
    reportada --> cancelada_por_usuario: usuario cancela
    reportada --> cancelada_por_operador: operador cancela
    reportada_sin_tracking --> tracking_actualizado: agregar tracking
    reportada_sin_tracking --> vinculada_a_paquete: operador asocia paquete
    reportada_sin_tracking --> requiere_correccion
    reportada_sin_tracking --> cancelada_por_usuario
    reportada_sin_tracking --> cancelada_por_operador
    tracking_actualizado --> vinculada_a_paquete
    tracking_actualizado --> requiere_correccion
    tracking_actualizado --> cancelada_por_usuario
    tracking_actualizado --> cancelada_por_operador
    requiere_correccion --> reportada: usuario corrige
    requiere_correccion --> cancelada_por_usuario
    requiere_correccion --> cancelada_por_operador
    vinculada_a_paquete --> [*]
    cancelada_por_usuario --> [*]
    cancelada_por_operador --> [*]

Pruebas asociadas

  • PT-050: Crear prealerta con todos los campos
  • PT-051: Crear prealerta sin tracking
  • PT-052: Crear prealerta con categoría prohibida (debe fallar)
  • PT-053: Crear prealerta con categoría que requiere factura (sin factura debe fallar)
  • PT-054: Validación de fecha de compra
  • PT-055: Validación de tracking
  • PT-056: Editar prealerta en estado requiere_correccion
  • PT-057: Cancelar prealerta sin paquete asociado
  • PT-058: Cancelar prealerta con paquete asociado (debe fallar)
  • PT-059: Actualizar tracking de prealerta
  • PT-060: Listar prealertas con estados
  • PT-061: Ver detalle de prealerta con timeline
  • PT-062: Subida de foto (caso normal y caso de fallo de red)
  • PT-063: Agregar destinatario nuevo desde el formulario