Skip to content
OMS Documentation

Shipping Index

Se describe de forma ágil y simplificada del módulo de ShippingIndex, abordando cuestiones generales de su funcionamiento, como así también aspectos de las pruebas del mismo.

 Vale aclarar que se añaden cuestiones técnicas de la reciente migración a MongoDB.

Descripción general

 El ShippingIndex, es un “índice”, como lo denominamos internamente, pero podría definirse mas claramente como un esquema desnormalizado, con el propósito de optimizar la proyección de información en las distintas salidas del sistema (API o BackOffice) de los envios (Shippings).

 El esquema posee toda la información relevante a los envíos considerando:

  • Cabecera de un envío: fecha y hora por los cual transitó su ciclo de logística (registrado a entregado, por ejemplo).

  • Perspectivas:

    • Backoffice:

      • Ultimo estado de tracking

      • Estado Interno

  • Cliente: ultimo estado visible por este

  • Información general acerca del:

    • Comprador y Vendedor: Nombre completo, Direcciones,etc..

    • Orden: Modos de Entrega, cotización, etc…

    • Items del Envío.

    • Tiempos Estimados de entrega

 Toda esta información está actualmente contenida en mas de 120 atributos.

 La información del Indice se actualiza al ocurrir algún evento de los siguientes:

  • Creación de Ordenes

  • Procesamiento de Aviso de Estados (StepStates) que hayan impactado satisfactoriamente.

  • Modificaciones en Envío o a la orden en la que pertenecen, que alcancen alguno de sus atributos que han sido representados, como por ejemplo:

    • Calculo estimado de fechas de entrega

    • Cotización de Orden

    • Estado de Orden

 Cuando alguno de estos eventos ocurre, se recurre a convertir el Shipping en un DTO (ShippingDTO) y proceder a encolarlo, serializando la totalidad de los atributos, en una cola especial llamada if_shipping_index_add. Existen muy pocos casos, donde el serializado este acotado a solo los datos “involucrados” (que ameritan una actualización del envio), pero se aclara que no es de interés para este documento detallarlo profundamente.

 Por último un consumer se encargara de la persistencia de la información

$ app/console swarrot:consume:shipping_index_add if_shipping_index_add -vv

Comandos

 En esta sección se describen los comandos principales del ShippingIndex

Comando de Inicialización / Reindexado

 Se ha elaborado un comando el cual permite realizar la carga del ShippingIndex o bien la actualización de instancias del mismo.

 El comando en cuestion es el siguiente, el cual puede operar bajo la modalidad de listamiento (de Id) o bien actualización a partir de un Id especifico:

# Lista los ids de los Shippings comprendidos por el criterio de busqueda
app/console app1:api:shippings:index list --desde='2023-10-30 09:00' --limit 1000 -vv
# Carga o actualiza un shipping en particular
app/console app1:api:shippings:index execute --id=123456 -vv

 Vale aclarar que el comando, al actualizar no realiza directamente la acción, sino que encola en la cola principal del ShippingINdex (if_shipping_index_add). 

Pruebas de rigor

  • Información listada se corresponda con los envíos vistos

  • El impacto debe generar una instancia válida: se puede verificar con clientes de BD o bien utilizando las pantallas principales del Back Office descriptas en la sección Usos.

Migración de Entities a Documents

 Para el caso puntual de la reciente migración se hizo un comando que se encarga de convertir las entities de ShippingIndex (tabla) a documents de la collection equivalente en MongoDB, que se encuentren comprendidas entre un rango de fechas.

 El comando en cuestión es el siguiente:

$ app/console app:shippingindex:migration "2023-09-30 00:00:00" "2023-10-30 23:59:59"

 Solo tras realizar una validación trivial de fechas (espera que el rango no sea mayor a 30 días), recupera todas las entidades y las convierte masivamente a Documents.

Pruebas de rigor

•          Verificar la consistencia tras la conversión

•          Verificar que los documents provenientes de la “conversión” posean el mismo Schema, con respecto a aquellos que se hayan originados con el nuevo flujo.

Usos

 En esta sección se describen los módulos que utilizan al ShippingIndex como fuente de información y/o se relacionan de alguna manera con el.

BackOffice

Envíos Facturación

 En el path /shipping_index/ se puede acceder al principal punto de exposición del ShippingIndex. En el se plasma un listado de envíos, con la perspectiva muy similar al listado de Envíos (/shipping/), osea con el último StepState que haya impactado de forma interna.

 Se ofrece la posibilitad de exportar en CSV y realizar un filtrado especial, en particular al proyectar información sobre envíos que cumplan con la condición que pasaron por determinado Estado entre un rango de fechas posibles. Este filtro aparece en la interfaz haciendo referencia a “Movimiento”: «Estado Movimiento» , «Movimiento Desde» y «Movimiento Hasta».

Pruebas de rigor

Tras corroborar que se haya actualizado el Indice:

  • Verificación de consistencia con respecto al listado de un envió (/shipping/).

  • Exportación a CSV deberá proyectar lo mismo que el listado (ShippingIndex).

  • Filtros:

    • Probar de manera general los filtros

    • Prestar atención a que el filtro de “Movimiento” proyecte envíos que efectivamente pasaron por dicho estado en rango de fechas indicado.

Envíos Customer Indice

 En el path /shipping_customer_index/, se ofrece un listado de envíos, junto a su detalle (/shipping_customer/id/show) correspondiente, con la perspectiva del Customer Service. Este siempre visualiza el ultimo estado (StepState) que haya impactado.

 Se ofrece la posibilidad de exportar dicho listado a CSV y realizar la búsqueda por parámetros habituales, y se emula el filtro similar al de Envios Facturacion, de movimientos, nada mas que en este caso es indicado como «Estado Tracking» .

Pruebas de rigor

Tras corroborar que se haya actualizado el Indice:

  • Verificación de consistencia del listado con respecto al ultimo StepState que haya impactado.

  • El detalle de un envío del Customer Indice, debería indicar información equivalente (puede haber omisiones de datos triviales) que el detalle de un Envio, pero con la diferencia que en la solapa Tracking, solo figura el ultimo estado en que se encuentra.

  • Filtros:

    • Probar de manera general los filtros

    • Prestar atención al filtro especial de Tracking.

APIs

Client

 Para este usuario en particular solo se utiliza en el endpoint destinado a la exportación en CSV de los envíos: /api/v1/client/shipping/export/csv.

 Este respeta la perspectiva del usuario, por lo tanto proyecta como estado el ultimo visible por este.

Pruebas de rigor

  • Realizar variaciones con la visibilidad de los StepState, por ejemplo, creandolos manualmente y verificar que efectivamente se respete la perspectiva del mismo.
    Es recomendable correr las variaciones de 1 a la vez: ya sea verificando el impacto de cada una en un entorno con el proceso corriendo o bien ejecutando manualmente el consumer de a 1 mensaje por vez.

  • Comparar el CSV exportado con el listado de envios, ambos deberían ser equivalentes (misma consistencia, cantidad de datos, etc..) .

  • Probar los filtros del endpoint, comparándolos con los del listado.

Customer Care

 Para este usuario, se consume el ShippingIndex para nutrir:

  • Listado de Envios -> /api/v1/cs/shipping_index.

  • Detalles de un Envío -> /api/v1/cs/shipping_index.

  • Exportación a CSV del Listado -> /api/v1/cs/shipping_index/export/csv.

  • Listado de Traslados asociados al Envío -> /api/v1/cs/shipping_index/:id /steps.

 Vale aclarar que para los endpoints de detalle y traslados asociados al envio, la utilización del ShippingIndex resulta “parcial”: se verifica la existencia y recupera el Shipping del indice, pero se nutre con datos de su instancia original (osea la real).

Pruebas de rigor

•          La información expuesta en los endpoints deberá seguir el criterio del último estado de tracking (StepState que haya impactado). Se puede usar el listado y detalles del Backoffice como referencia. Aunque puede haber pequeñas diferencias, dado que la API es mas reciente que las pantallas del Backoffice.

•          Comprar el endpoint de listado con el de exportación, verificando que la información sea consistente y presente la misma cantidad de elementos.

Flujos y/o módulos particulares

Estadísticas de Cliente

 Ocurre que cuando una instancia del ShippingIndex es creada o actualizada, se determina a que Cliente y dia corresponde (basado en la fecha de la orden), y es ahí donde se verifica si existen estadísticas calculadas, considernadno ambos valores (client_id y date):

  • En caso de que exista -> Se marca las estadísticas de ese cliente, para actualizar (atributo must_update = true), para que luego un comando (app/console app1:api:client:statics ) encole un mensaje en if_client_statics_update, para dar la directiva de calcular las estadísticas

  • Caso contrario: se encola directamente

 El consumidor involucrado en este flujo, utilizará esos parámetros y hara uso del ShippingIndex para recuperar información que necesita para realizar el cálculo. Dicho consumidor es:

$ app/console swarrot:consume:client_statics_update if_client_statics_update -vv

Pruebas de rigor

  • Todo impacto de ShippingIndex, debería forzar el calculo estadístico, por lo tanto bastará al menos verificar el encolado del mensaje o bien la actualización de las estadisticas del cliente involucrado.

  • La ejecución del consumidor resulte satisfactoria, osea sin errores y con estadísticas actualizadas.