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-012: Abrir y gestionar una incidencia

Caso de uso detallado para que un usuario u operador abra, siga y cierre una incidencia. Cubre el flujo de incidencias de la app y del backoffice.

Metadatos

Campo Valor
ID CU-012
Nombre Abrir y gestionar una incidencia
Actor primario Usuario Final u Operador
Actores secundarios Sistema de Notificaciones, opcionalmente Agencia
Módulo Incidencias y reclamos
Prioridad Alta (MVP)
Frecuencia esperada Media
Trazabilidad SRS RF-035, RF-036, RF-037, RF-038, RF-046, RF-049

Descripción

Una incidencia es cualquier evento que afecta negativamente la operación normal de un paquete, un envío, un pago o la cuenta de un usuario, y que requiere intervención del equipo de IslaBox para resolverse.

Este caso de uso cubre el ciclo de vida completo: apertura, mensajes, evidencia, cambio de estado, resolución, cierre, escalación y reembolso cuando aplica.

Para la lista de tipos, estados y reglas, ver flujos/incidencias-reclamos.md (documento normativo).

Precondiciones

  • El actor está autenticado.
  • Si es un usuario: tiene al menos un paquete, envío o pago registrado.
  • Si es un operador: tiene rol operator, admin o sysadmin.
  • El recurso afectado existe y pertenece al usuario (o es visible para el operador).

Postcondiciones

Éxito: - Se crea un registro en incidents. - Se notifica al actor opuesto (operador recibe push si la abre el usuario; usuario recibe email si la escala el operador). - Se registra en audit_logs.

Fallo: - Mensaje de error específico al actor.

Flujo principal — apertura por el usuario

  1. El usuario abre el detalle del paquete o envío afectado.
  2. El usuario toca "Reportar problema".
  3. El sistema muestra el formulario de incidencia con:
  4. Selector de tipo (los 11 tipos de incidencias-reclamos §2)
  5. Campo de descripción (mín. 30 caracteres)
  6. Selector de archivos adjuntos (fotos, video, PDF)
  7. El usuario completa y adjunta al menos 1 evidencia.
  8. El sistema valida y crea incident con estado abierta.
  9. El sistema asigna automáticamente a la cola del operador con menos carga.
  10. El sistema notifica al operador.
  11. El usuario ve la confirmación: "Tu reporte #1234 fue creado. Te avisaremos cuando haya movimiento."

Flujo principal — gestión por el operador

  1. El operador abre la cola de incidencias (/backoffice/incidencias).
  2. Selecciona una incidencia.
  3. La ve en estado abierta.
  4. Cambia a en_revision y agrega un mensaje interno (visible para el usuario).
  5. Si requiere más evidencia: pasa a requiere_evidencia y notifica al usuario.
  6. Si la información es suficiente: investiga, contacta al usuario vía mensajes o escala.
  7. Decide:
  8. Resolver: pasa a resuelta con texto de resolución + opcional reembolso.
  9. Rechazar: pasa a rechazada con motivo obligatorio.
  10. La incidencia queda en cerrada automáticamente tras 30 días sin movimiento.

Flujos alternativos

FA-1: Escalar a agencia

  • Si el problema es atribuible a la agencia (retraso, pérdida en última milla):
  • Operador pasa a en_espera_de_agencia y notifica vía webhook a la agencia.
  • La agencia responde → operador recibe notificación y continúa.

FA-2: Generar reembolso

  • Si la resolución incluye devolución de dinero:
  • Operador marca "Generar reembolso" + monto.
  • Sistema crea payment con estado reembolsado (vinculado al original).
  • Se notifica al usuario.

FA-3: Escalación a administrador

  • Si el operador no puede resolver en 5 días hábiles:
  • Sistema escala automáticamente al administrador.
  • Notificación al admin vía email + push.

FA-4: Cierre por inactividad

  • Si en 30 días no hay movimiento, sistema cierra la incidencia automáticamente.
  • Notificación final al usuario y operador.

FA-5: Reapertura (no permitida en MVP)

  • En MVP, una incidencia cerrada no se puede reabrir. El usuario debe abrir una nueva referenciando la anterior.

Reglas de negocio

  • RN-046: Plazo máximo del usuario para abrir incidencia: 7 días desde la entrega o el evento.
  • RN-047: Plazo de investigación: 5 días hábiles.
  • RN-048: Plazo de resolución: 10 días hábiles.
  • RN-049: Toda incidencia queda registrada en audit_logs con hash para inmutabilidad.
  • RN-RBAC-005: Solo admin o sysadmin puede iniciar reembolso.

Endpoints API

  • POST /api/v1/incidents — abre
  • GET /api/v1/incidents — lista
  • GET /api/v1/incidents/{id} — detalle
  • POST /api/v1/incidents/{id}/messages — mensaje (usuario u operador)
  • POST /api/v1/incidents/{id}/evidence — evidencia
  • PATCH /api/v1/incidents/{id}/status — cambia estado (operador)
  • POST /api/v1/incidents/{id}/close — cierra con resolución
  • POST /api/v1/incidents/{id}/escalate — escala a admin o agencia
  • POST /api/v1/incidents/{id}/refund — inicia reembolso (admin)

Pantallas

  • IncidentCreateScreen (app)
  • IncidentsListScreen (app)
  • IncidentDetailScreen (app y backoffice)
  • Backoffice: IncidentQueueScreen, IncidentAssignScreen

Eventos generados

  • INCIDENT_OPENED
  • INCIDENT_MESSAGE_ADDED
  • INCIDENT_EVIDENCE_ADDED
  • INCIDENT_STATUS_CHANGED
  • INCIDENT_ESCALATED
  • INCIDENT_CLOSED
  • INCIDENT_REFUND_INITIATED

Notificaciones generadas

  • Al abrir: email al usuario + push al operador.
  • Al cambiar estado: push al usuario + email.
  • Al agregar mensaje: push al actor opuesto.
  • Al escalar: email al admin.
  • Al cerrar: email al usuario con resumen.