Glosario

Referencia alfabetica de terminos usados en la plataforma PROXIMITI, la documentacion SCOR v12.0 y el dominio logistico.

---

Terminos de la Plataforma PROXIMITI

ALINA

Sistema ERP externo que recibe datos de paquetes caducados a traves del patron de outbox transaccional. Simulado (stub) en el entorno local v2.0.

Codigo de barras

Identificador unico del paquete asignado en la creacion de la expedicion (ej., PROX-20240315-001). Usado a lo largo del ciclo de vida para escaneo, seguimiento y llamadas API.

BFF (Backend for Frontend)

Servicio de gateway API (ws-pprx-bff, puerto 8090) que agrega microservicios downstream, gestiona autenticacion, inyecta cabeceras de contexto de centro y expone la API REST unificada consumida por todas las aplicaciones cliente.

Codigo de Centro

Identificador alfanumerico de un centro PUDO (ej., PUDO-MAD-001). Mapeado desde el atributo de usuario center_code de Keycloak a la cabecera X-Center-Code por el BFF.

Intercambio Dual-QR

Verificacion de identidad en dos fases basada en codigos QR entre un transportista y un operador PUDO. El transportista inicia una sesion y muestra un codigo QR; el operador PUDO lo escanea para validar el intercambio. Ver Intercambio con Transportista.

Clave de Idempotencia

UUID generado por el cliente enviado como cabecera HTTP X-Idempotency-Key durante la creacion de expediciones. Garantiza semantica de exactamente-una-vez — claves duplicadas devuelven 409 Conflict.

NOVA

Sistema externo de despacho de notificaciones. Recibe eventos de notificacion via llamadas fire-and-forget (timeout de 500ms). Simulado (stub) en el entorno local v2.0.

POD (Prueba de Entrega)

Registro digital compuesto por tres elementos capturados durante la entrega del paquete: (1) firma del destinatario, (2) foto del documento de identidad del destinatario, y (3) el numero de documento. Almacenado en MinIO via URLs de subida prefirmadas.

PUDO (Pick-Up & Drop-Off)

Ubicacion fisica donde los paquetes son depositados por transportistas y recogidos por destinatarios. Cada centro PUDO tiene un codigo de centro unico, capacidad fisica y uno o mas operadores asignados.

Periodo de Retencion

Numero maximo de dias que un paquete puede permanecer en un centro PUDO antes de la caducidad automatica. Cuando se excede, el paquete transiciona de RECEPCIONADO a CADUCADO.

Outbox Transaccional

Patron de base de datos usado por ws-pprx-expired para garantizar que los mensajes de exportacion a ALINA se escriban en la misma transaccion que el cambio de estado de la expedicion. Las entregas fallidas van a una Cola de Mensajes Muertos (DLQ).

X-Center-Id

Cabecera HTTP inyectada por el BFF en las llamadas a servicios downstream. Contiene el ID de base de datos del centro PUDO del operador, obtenido del claim sub del JWT de Keycloak via el servicio de usuarios (cacheado con Caffeine durante 5 minutos).

---

Terminos SCOR v12.0

Proceso L1

Categoria de nivel superior de SCOR. PROXIMITI mapea tres de seis procesos L1: Deliver (sD), Return (sR) y Enable (sE). Plan, Source y Make se excluyen ya que no aplican a operaciones PUDO de ultima milla.

Proceso L2

Subcategoria SCOR de segundo nivel dentro de un proceso L1. PROXIMITI mapea 9 procesos L2 en Deliver, Return y Enable. Ver Vista General de SCOR.

SCOR (Supply Chain Operations Reference)

Marco de gestion de cadena de suministro de ASCM (Association for Supply Chain Management). PROXIMITI usa SCOR v12.0 para mapear sus capacidades a categorias estandarizadas de procesos logisticos.

sD (Deliver)

Proceso L1 de SCOR que cubre la entrega de productos al cliente final. En PROXIMITI: todo el ciclo de vida del paquete desde la creacion de la expedicion hasta la captura de POD.

sD1 (Deliver Stocked Product)

Proceso L2 de SCOR bajo Deliver. Se mapea a la entrega de paquetes de ultima milla de PROXIMITI — creacion de expedicion, seguimiento, recepcion, entrega con POD.

sE (Enable)

Proceso L1 de SCOR que cubre operaciones transversales que soportan Deliver y Return. En PROXIMITI: administracion, precios, seguridad, integraciones, gestion de red y cumplimiento.

sE1 / sE3 / sE5 / sE6 / sE7 / sE8

Sub-procesos L2 de Enable: Administracion de Plataforma (sE1), Precios y Niveles de Servicio (sE3), Seguridad e Identidad (sE5), Integraciones con Proveedores (sE6), Gestion de Red PUDO (sE7), Cumplimiento de Prueba de Entrega (sE8).

sR (Return)

Proceso L1 de SCOR que cubre logistica inversa y devoluciones. En PROXIMITI: gestion de reclamaciones/incidencias y recogida de paquetes caducados.

sR1 (Return Defective Product)

Proceso L2 de SCOR bajo Return. Se mapea a la gestion de reclamaciones e incidencias de PROXIMITI (ws-pprx-issues).

sR2 (Return Excess Product)

Proceso L2 de SCOR bajo Return. Se mapea a la recogida de paquetes caducados de PROXIMITI (ws-pprx-expired).

---

Terminos del Dominio Logistico

Capacidad

Numero de espacios fisicos disponibles en un centro PUDO para almacenamiento de paquetes. Actualizada atomicamente usando el patron de bloqueo optimista ETag/If-Match cuando los paquetes son recibidos o entregados.

Estado

El campo de estado de la expedicion en la base de datos (estado) y respuestas API. Valores: PENDIENTE, RECEPCIONADO, ENTREGADO, CADUCADO, LOCKED_FOR_RETRIEVAL, RECOGIDO, RETIRADO.

ETag

Cabecera HTTP de control de concurrencia usada para bloqueo optimista en actualizaciones de capacidad. El servicio de centros devuelve un ETag con cada respuesta de capacidad; las actualizaciones subsiguientes deben incluir If-Match con el mismo valor o reciben 412 Precondition Failed.

Expedicion

Envio o paquete. El termino usado en las etiquetas de la UI de la app Flutter (ej., "Expedicion Recibida!", "Entregar Expedicion").

Ultima Milla

El segmento final de entrega desde un centro de distribucion al destinatario final. PROXIMITI opera en este segmento, conectando transportistas con centros PUDO y destinatarios.

Lote

Usado en el flujo de entrega multiple de la app del transportista donde multiples paquetes se entregan en un centro PUDO en una sola operacion ("Entrega Multiple").

Bloqueo Optimista

Patron de concurrencia que detecta conflictos en el momento de la actualizacion usando tokens de version (ETags). Si otra solicitud modifico el recurso desde la ultima lectura, la actualizacion falla con 412 Precondition Failed y el cliente debe reintentar con un ETag actualizado.