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.

Diagrama de estados — Paquete físico¶

Diagrama UML de máquina de estados que muestra todos los estados posibles de un PhysicalPackage y las transiciones válidas entre ellos. Fuente de verdad: estados.md.

Limpieza 2026-06-08

Se eliminó el estado listo_para_enviar del diagrama porque no existe en el documento canónico estados.md. El envío individual se modela como una consolidación de un solo paquete: en_almacen → listo_para_consolidar → reservado_para_consolidacion → consolidado → en_transito.

Diagrama¶

stateDiagram-v2
    [*] --> prealertado: crear prealerta

    prealertado --> en_camino_al_almacen: transportista actualiza
    prealertado --> recibido_sin_identificar: llega al almacén sin identificador
    prealertado --> recibido_identificado: llega al almacén con identificador

    en_camino_al_almacen --> recibido_sin_identificar
    en_camino_al_almacen --> recibido_identificado

    recibido_sin_identificar --> recibido_identificado: operador identifica
    recibido_sin_identificar --> pendiente_conciliacion: requiere revisión
    recibido_sin_identificar --> retenido_por_incidencia: no se puede identificar

    pendiente_conciliacion --> recibido_identificado: conciliado
    pendiente_conciliacion --> retenido_por_incidencia: cerrado sin conciliar

    recibido_identificado --> en_almacen: almacenado
    recibido_identificado --> retenido_por_incidencia: problema al recibir

    en_almacen --> esperando_instrucciones: usuario aún no decide
    en_almacen --> en_servicio_adicional: solicita servicio
    en_almacen --> listo_para_consolidar: marcado para consolidar
    en_almacen --> devuelto_a_tienda: solicita devolución
    en_almacen --> retenido_por_incidencia: problema

    esperando_instrucciones --> en_servicio_adicional
    esperando_instrucciones --> listo_para_consolidar
    esperando_instrucciones --> devuelto_a_tienda
    esperando_instrucciones --> en_almacen: usuario decide esperar
    esperando_instrucciones --> retenido_por_incidencia

    en_servicio_adicional --> listo_para_consolidar: servicio completado
    en_servicio_adicional --> en_almacen: servicio cancelado
    en_servicio_adicional --> retenido_por_incidencia: problema con servicio

    listo_para_consolidar --> reservado_para_consolidacion: agregado a consolidación (incluso si es de 1 paquete)
    listo_para_consolidar --> en_almacen: cancela consolidación

    reservado_para_consolidacion --> consolidado: consolidación confirmada
    reservado_para_consolidacion --> listo_para_consolidar: sale de consolidación

    consolidado --> en_transito: envío despachado
    consolidado --> en_almacen: consolidación cancelada

    en_transito --> entregado: confirmación de entrega
    en_transito --> retenido_por_incidencia: problema en tránsito
    en_transito --> devuelto_a_tienda: retorno

    entregado --> [*]
    retenido_por_incidencia --> en_almacen: incidencia resuelta
    retenido_por_incidencia --> devuelto_a_tienda: se decide devolver
    retenido_por_incidencia --> descartado_o_cerrado: cierre operativo

    devuelto_a_tienda --> descartado_o_cerrado: devolución cerrada
    descartado_o_cerrado --> [*]

Estados (16 oficiales)¶

#	Estado	Descripción
1	`prealertado`	Hay una prealerta asociada y el paquete está en camino
2	`en_camino_al_almacen`	El transportista está transportando hacia el almacén
3	`recibido_sin_identificar`	Llegó al almacén, no se pudo identificar aún
4	`recibido_identificado`	Llegó y se asoció a un usuario
5	`pendiente_conciliacion`	Llegó pero no coincide con ninguna prealerta
6	`en_almacen`	Almacenado, esperando instrucciones del usuario
7	`esperando_instrucciones`	El usuario aún no decidió qué hacer
8	`en_servicio_adicional`	Tiene un servicio activo (inspección, prueba, reempaque)
9	`listo_para_consolidar`	Puede ser incluido en una consolidación
10	`reservado_para_consolidacion`	Ya fue seleccionado para una consolidación
11	`consolidado`	Ya agrupado dentro de una consolidación
12	`en_transito`	Enviado hacia Cuba
13	`entregado`	Entregado al destinatario final
14	`retenido_por_incidencia`	Retenido por algún problema que requiere resolución
15	`devuelto_a_tienda`	En proceso de devolución al vendedor
16	`descartado_o_cerrado`	Cerrado por cierre de caso, abandono o decisión operativa

Transiciones válidas (resumen)¶

Desde	Hacia	Quién	Disparador
`prealertado`	`en_camino_al_almacen`	Operador	Confirmación del transportista
`prealertado`	`recibido_*`	Operador	Recepción física
`recibido_sin_identificar`	`recibido_identificado`	Operador	Identificación por identificador/tracking
`recibido_sin_identificar`	`pendiente_conciliacion`	Operador	No se pudo identificar
`recibido_identificado`	`en_almacen`	Sistema	Almacenamiento físico
`en_almacen`	`esperando_instrucciones`	Sistema	Default si no hay acción
`en_almacen`	`en_servicio_adicional`	Usuario	Solicita servicio
`en_almacen`	`listo_para_consolidar`	Usuario	Decide consolidar
`en_almacen`	`listo_para_consolidar`	Usuario	Decide consolidar (incluso 1 paquete)
`listo_para_consolidar`	`reservado_para_consolidacion`	Sistema	Se agrega a consolidación
`reservado_para_consolidacion`	`consolidado`	Sistema	Consolidación confirmada
`consolidado`	`en_transito`	Operador	Despacho
`en_transito`	`entregado`	Operador	Confirmación de entrega
cualquier estado activo	`retenido_por_incidencia`	Operador/Sistema	Detección de problema
`retenido_por_incidencia`	estado anterior	Operador	Resolución

Transiciones inválidas (rechazadas)¶

El sistema rechaza cualquier transición que no esté en la lista anterior. Ejemplos:

❌ en_transito → en_almacen (no se puede "des-despachar")
❌ entregado → cualquier otro estado (es terminal)
❌ prealertado → en_transito (sin pasar por recibido)
❌ en_almacen → consolidado (sin pasar por reservado)

Eventos asociados¶

Cada transición genera un package_event:

@dataclass
class PackageEvent:
    id: int
    physical_package_id: int
    previous_status: PackageStatus
    new_status: PackageStatus
    description: str
    operator_id: int | None
    user_id: int | None
    created_at: datetime

Los eventos son inmutables (append-only) y forman el timeline que ve el usuario.

Visibilidad por actor¶

Estado	Usuario Final	Operador
`prealertado`	✅	✅
`en_camino_al_almacen`	✅	✅
`recibido_sin_identificar`	❌	✅
`recibido_identificado`	✅	✅
`pendiente_conciliacion`	❌	✅
`en_almacen`	✅	✅
`esperando_instrucciones`	✅	✅
`en_servicio_adicional`	✅	✅
`listo_para_consolidar`	✅	✅
`reservado_para_consolidacion`	✅	✅
`consolidado`	✅	✅
`listo_para_enviar`	~~Eliminado en 2026-06-08~~	~~Eliminado~~
`en_transito`	✅	✅
`entregado`	✅	✅
`retenido_por_incidencia`	✅ (con motivo)	✅
`devuelto_a_tienda`	✅	✅
`descartado_o_cerrado`	✅	✅

Notificaciones por transición¶

Transición	Push	Email
→ `recibido_identificado`	✅	❌
→ `en_almacen`	❌	❌
→ `en_servicio_adicional`	✅	❌
→ `consolidado`	✅	❌
→ `en_transito`	✅	❌
→ `entregado`	✅	✅
→ `retenido_por_incidencia`	✅	✅
→ `devuelto_a_tienda`	✅	❌

Códigos de error para transiciones inválidas¶

Código	Significado
`INVALID_TRANSITION`	Transición no permitida
`PACKAGE_NOT_FOUND`	Paquete no existe
`PACKAGE_NOT_OWNED`	Usuario no es propietario
`STATUS_LOCKED`	Cambio de estado bloqueado por otro proceso
`MISSING_INCIDENT_REASON`	Cambio a `retenido_por_incidencia` sin motivo