Portal de Cliente (WEB)
Manual técnico
Portal de Cliente (WEB)
Fecha: 13 de agosto de 2024
Versión: Ver. 1.0
Proyecto: GM-Paquetería
Elaborado por:
Certuit Software S. de R.L de C.V.
Cerro de las Campanas No. 384, Insurgentes Oeste, CP. 21280
Mexicali, BC. México
Historial de Cambios
| Fecha | Secciones | Razón de Cambios | Autor(es) | Revisor(es) |
|---|---|---|---|---|
| 13 de agosto de 2022 | TODAS | Creación del documento | Esteban Valencia | Adrian Renteria |
| 2 de septiembre del 2024 | TODAS | Actualización de contenido y formato | Jocelyn Martinez |
GM Paquetería Portal de Cliente Sistema Web
1 Introducción
1.1 Descripción del Proyecto
GM Paquetería Portal de Cliente Sistema Web es una aplicación web diseñada para ser utilizada por los clientes de las empresas de logística con el propósito de agilizar el proceso de creación de embarques y recolecciones.
1.2 Tecnologías y Librerías Utilizadas
Se presenta el listado de tecnologías y sus versiones.
-
NodeJS: v14.17.3
-
ReactJS: v17.0.1
-
React Router: v5.2.0
-
npm: v6.14.13
-
JavaScript
1.2.1 Librerías destacadas
Here API
Se utiliza para obtener las coordenadas del remitente o destinatario dependiendo del caso..
Material UI v4 y v5
Se utiliza para componentes de vista. Inicialmente se desarrolló en la versión 4, posteriormente se migró a versión 5, sin embargo es posible encontrar ambas versiones.
Bootstrap
El proyecto se inició utilizando Bootstrap para componentes de vista pero se fue migrando a Material UI, sin embargo, aún hay código de bootstrap.
2 Arquitectura del Proyecto
2.1 Navegación
La navegación dentro del proyecto se hace usando React Router. Se puede observar la configuración en el archivo App.js ubicado en la carpeta src en la raíz del proyecto.
Visualmente se accede a los procesos por medio de una barra lateral.
3 Configuración Inicial del Proyecto
Seguir los pasos descritos para configurar el proyecto en un ambiente de desarrollo (local):
- Clonar el Repositorio:
| git clone http://190.9.53.4:3000/GM-Transport/paqueteria-portal.git |
|---|
- Descargar librerías: Ejecutar el comando
| npm install |
|---|
- Ejecutar el Proyecto:
| npm start |
|---|
Esto abrirá la aplicación en http://localhost:3000/portal y se verá la pantalla en blanco.
La Url debe ser ajustada para que se pueda ver la primera pantalla, a la siguiente: localhost:3000/portal/Portal/SOPO110101PQ1
Al final se puede ver que se tiene el RFC de la empresa de logística, eso servirá para la conexión a la base de datos de esa empresa.
3.1 Conexión con servicios
Rutas de servicios
El proyecto se divide en cuatro ramas principales: master, release, develop, y calidad. Las ramas calidad y develop están conectadas al ambiente de pruebas, mientras que la rama release a preproducción y master a producción.
Las URLs de cada ambiente se encuentran en el archivo .env que se ubica en la raíz del proyecto.
- Ambiente de Pruebas:
- Backend Paquetería Webdev (REACT_APP_API_URL):
- Backend Paquetería Spring Boot (REACT_APP_REPORT_URL):
- Ambiente de Pre-producción:
- Backend Paquetería Webdev (REACT_APP_API_URL):
- Backend Paquetería Spring Boot (REACT_APP_REPORT_URL):
- Ambiente de Producción:
- Backend Paquetería Webdev (REACT_APP_API_URL):
- Backend Paquetería Spring Boot (REACT_APP_REPORT_URL):
Es importante mencionar que la forma de identificar qué base de datos se va consultar es a través del RFC del cliente. Para esto se manda el RFC como header en todas las peticiones de backend.
El backend de WEBDEV es en su mayoría solo utilizado para tema de reportes. Ahí se almacenan los formatos de impresión y se consultan. También se realizan las acciones relacionadas con el SAT como timbrado, cancelaciones de timbrado, entre otras. El resto de flujos se hacen con el backend de Spring Boot.
3.2 Organización de Directorios
La estructura de directorios del proyecto está organizada de la siguiente manera:
Proyecto
-
scr: contiene los archivos del proyecto tal cual, componentes, paginas, etc.
- Constants/index: contiene encabezados para peticiones http, plantillas para la impresión de etiquetas y otras configuraciones.
- iconos: directorio con las imágenes usadas en el sistema, desde logos, hasta iconos.
- Util/Context: directorio con los archivos context que contienen las urls de los servicios.
- Views: directorio que contiene todas los los archivos que corresponden a las vistas.
- index.js: aplicación principal
- routes.js: archivo que contiene las rutas de la barra lateral de navegación.
-
.env: archivo que contiene las url de los diferentes ambientes. Cambia dependiendo la rama en la que se encuentre.
-
package.json: archivo que contiene las librerías necesarias para el proyecto.
4 Procesos
4.1 Inicio de sesión
Descripción general
Este flujo se desarrolla iniciando en el archivo Login.js. El flujo de login se encarga de autenticar al cliente y redirigirlo a la pantalla principal.
Inicialización de la vista
Al ingresar a cualquier página del sistema se valida una sesión activa. Si hay sesión activa se permitirá entrar a la página. Si no hay sesión se redirigirá a la pantalla de inicio de sesión
Acciones del usuario
Iniciar sesión
Los datos necesarios para el login son el correo del cliente y el RFC del cliente. Al presionar el botón para iniciar sesión se realiza la siguiente petición al backend:
- URL:
- /api/Clientes/ValidarLogin/{correo}/{RFC}
- Variables:
- correo electrónico
- RFC del cliente
- Headers:
- RFC de la empresa de logística
Después de un inicio de sesión exitoso, el usuario es redirigido a Embarques, en el archivo Embarques.js.
4.2 Seguimiento (Tracking)
Descripción general
Este proceso se desarrolla iniciando en el archivo PropuestaLogin.js.
Este módulo es para poder dar ver el estado de una guía por medio del folio de tracking. Esta página es accesible para los clientes de la empresa de logística. Esta será la primera pantalla que verá el usuario al entrar al Portal de Cliente.
Acciones del usuario
Rastrear envío
Para usarlo solo es necesario escribir el folio de tracking del registro que se quiere buscar. Al presionar Buscar se redirigirá a una nueva pantalla y se obtendrá la información del registro para ser mostrada. Se usa el siguiente endpoint:
- URL:
- /api/UltimaMilla/GetParadasEsRecoleccion/{esRecoleccion}/{folio}
- Variables:
- folio tracking del registro
- es recolección: indicador para distinguir si la búsqueda es de una guía o una recolección. Se manda 0 para guía y 1 para recolección.
4.3 Embarques
Descripción general
Este proceso se desarrolla iniciando en el archivo Embarque.js. Un embarque es un registro donde se especifica la mercancía que se quiere mover, el cliente, el remitente, destinatario entre otros datos necesarios para llevar a cabo un envío.
Inicialización de la vista
El proceso inicia en la pestaña Listado, se obtiene el listado de embarques usando el endpoint (este endpoint también es usado para la funcionalidad de filtrar):
- URL:
- /Embarque/GetByFiltro/{fechaInicial}/{fechaFinal}/{sucursal}/{estatus}/{folio}/{origen}/{destino}/{cliente}
- Variables:
- fechaInicial: la fecha de la que se me empezarán a tomar registros
- fechaFinal: la fecha de la que se me terminarán a tomar registros
- sucursal: sucursal en la que se creó el embarque
- estatus: estatus en el que se encuentra el embarque
- folio: folio del embarque
- origen: origen del embarque
- destino: destino del embarque
- cliente: se usará por defecto el que está usando el sistema
Al obtener la respuesta se muestra en un listado.
Acciones del usuario
Agregar
A continuación se explican los datos necesarios para crear un embarque:
Sucursal : se precarga tomando el valor de los datos de inicio de sesión del usuario.
Folio Recolección, Embarque, Guía: el folio de recolección se tomará automáticamente si el embarque está siendo creado a partir de una recolección. El folio de embarque se generará automáticamente al crear el embarque, por lo que desde el frontend no se manda. El resto de los folios funcionan de la misma manera al crear su respectivo registro.
Fecha: se obtiene por código, es la fecha actual de creación.
Estatus del embarque: se precarga del valor seleccionado para usar por defecto en parámetros de configuración.
Moneda: se precarga valor seleccionado para usar por defecto en parámetros de configuración.
Responsable de pago: es el cliente, no necesariamente el remitente o destinatario. Son administrados en el ERP. Se usará el cliente que está usando el sistema.
Tipo de seguro: se obtiene de los datos del cliente al haber sido seleccionado. Dependiendo el tipo de seguro puede llegar a cambiar en automático el Tipo de Cobro si así ha sido configurado en Parámetros de Configuración.
Porcentaje de seguro: se obtiene de los datos del cliente al haber sido seleccionado.
Valor declarado: definido por el usuario. Puede ser obligatorio si así ha sido configurado en parámetros de configuración.
Observaciones: definido por el usuario. Si el cliente tiene seguro por un tercero, se precargará la póliza del seguro si está dentro de los datos del cliente.
Referencia: definido por el usuario.
Paquetes: se agregan usando los productos registrados en el catálogo de productos.
Complementos SAT: definidos por el usuario. Los complementos son registros estáticos en base de datos y fueron proporcionados por el equipo del ERP.
Remitente: es la persona o empresa que manda la mercancía. Los remitentes vienen del ERP. Al seleccionar uno el resto de la información será cargada si en el ERP ha sido registrada correctamente.
Destinatario: es la persona o empresa que recibe la mercancía. Los destinatarios vienen del ERP. Al seleccionar uno el resto de la información será cargada si en el ERP ha sido registrada correctamente. La dirección y zona operativa asignada para el destinatario será usada para el proceso de última milla en caso de que aplique.
Entrega en sucursal: cuando se selecciona, la guía generada a partir del embarque no pasará por el proceso de última milla, sino por el proceso de entrega ocurre. Puede deshacer el cobro del concepto de entrega en caso de que aplique.
Entrega en diferente domicilio: al activar, la guía generada a partir del embarque entrará en proceso de última milla pero no se usará la dirección del destinatario, sino la especificada en los campos que aparecerán.
Entrega con cita: al activar se puede especificar una ventana de tiempo en la que se quiere que la mercancía sea entregada. Puede representar un costo extra si en parámetros de configuración fue especificado.
Conceptos de facturación: se generan con la cotización al presionar el botón Calcular tarifa. En el portal de cliente no se pueden agregar conceptos manualmente después de haber generado la cotización. Calcular la tarifa es el último paso porque es necesaria toda la información del embarque para realizar el cálculo. Si se edita información después de la cotización es necesario generar una nueva cotización presionando de nuevo el botón Calcular Tarifa. El concepto Flete es el único obligatorio. Si se produce algún error al generar la cotización no se podrá guardar el embarque hasta haber resuelto los errores. El funcionamiento de la lógica de tarifas no cuenta con ningún problema. Los “errores” que se han reportado han sido por errores de usuario al momento de configurar las tarifas o convenios.
Ya que se tienen todos los datos se agrega el embarque presionando el botón Guardar Embarque para hacer la llamada al endpoint:
- URL:
- /Embarques/Agregar
- Body:
- Los datos ya especificados anteriormente.
Al agregar correctamente el embarque se dará la opción al usuario de crear la guía a partir del embarque recién creado. En caso de aceptar, se agregará la guía y ambos registros quedarán relacionados. En caso de no aceptar se regresará al usuario al listado.
Modificar
Para modificar un registro se necesita ubicar en el listado y presionar el botón con icono de lápiz ubicado del lado izquierdo. Al presionar se mostrará el formulario de agregar con los datos del registro precargados. Los datos se obtienen al hacer una llamada al backend.
Obtener embarque por id
- URL:
- /api/Embarque/GetById/{IdRegistro}
- Variables:
- Id del registro
Ya con los datos cargados se puede modificar el formulario. Para guardar los cambios se presiona el botón Guardar Embarque ubicado en la parte inferior. Al presionarlo se hace una llamada al backend para actualizar la información.
Editar embarque
- URL:
- /api/Embarques/Modificar/{IdRegistro}
- Variables:
- Id del registro
- Body:
- Los datos ya especificados anteriormente.
Si la operación es exitosa se regresa al listado de registros. Si surge algún error se muestra mensaje al usuario y los datos permanecen en el formulario.
Consultar
Para consultar un registro se necesita ubicar en el listado y presionar el botón con icono de ojo ubicado del lado izquierdo. Al presionar, se mostrará el formulario de agregar con los datos del registro precargados y todos los campos deshabilitados. Los datos se obtienen al hacer una llamada al backend.
Obtener embarque por id
- URL:
- /api/Embarque/GetById/{IdRegistro}
- Variables:
- Id del registro
Eliminar
Para eliminar un registro se necesita ubicar en el listado y presionar el botón con icono de bote de basura, ubicado del lado izquierdo.
Solo pueden ser eliminados los registros que tengan estatus Cancelado.
Al eliminar, se hace la llamada al backend para validar los permisos del usuario.
- Validar permiso de usuario
- URL:
- /Utilerias/ValidaDerechos/{IdUsuario}/{IdPermiso}/3
- Variables:
- Id del usuario
- Id del permiso
- URL:
Si el usuario cuenta con el permiso necesario se hace una llamada al backend para realizar la acción.
- Eliminar embarque
- URL:
- /api/Embarques/Eliminar/{IdRegistro}/{IdUsuario}
- Variables:
- Id del registro
- Usuario
- URL:
Filtrar
En la vista de listado se pueden filtrar los registros usando diferentes parámetros, los parámetros deben ser características de los embarques deseados. Los parámetros que no se quieran usar para filtrar se pueden dejar en blanco para que no tengan efecto. En caso de usar el filtro por Folio y tener otros filtros agregados, serán ignorados para darle prioridad al folio. Una vez establecidos los filtros se hace la llamada al backend:
- URL:
- /Embarque/GetByFiltro/{fechaInicial}/{fechaFinal}/{sucursal}/{estatus}/{folio}/{origen}/{destino}/{cliente}
- Variables:
- fechaInicial: la fecha de la que se me empezarán a tomar registros
- fechaFinal: la fecha de la que se me terminarán a tomar registros
- sucursal: sucursal en la que se creó el embarque
- estatus: estatus en el que se encuentra el embarque
- folio: folio del embarque
- origen: origen del embarque
- destino: destino del embarque
- cliente: cliente del embarque
Al obtener los registros se mostrarán en el listado.
Importar
Para importar embarques es necesario tener configurada al menos una plantilla de importación. Para acceder a la función, seleccionar la pestaña Importar en la parte superior. Se mostrará un formulario, seguir los siguientes pasos:
- Selecciona el cliente, se obtendrá la plantilla de configuración creada para el cliente seleccionado. Este cliente también será asignado por defecto como responsable de pago del embarque.
- Si no se tiene el archivo de la plantilla, se puede descargar con el botón correspondiente.
- Cargar el archivo con los embarques presionando el botón Importar.
- Esperar a que se genere la vista previa.
- Confirmar la información. La cotización se generará junto con los embarques a la hora de guardar la información.
- Guardar la información presionando el botón Aceptar.
Los nuevos registros estarán disponibles en el listado.
Generar reporte
Para el reporte de un registro se necesita ubicar en el listado y presionar el botón con icono de hoja de papel ubicado del lado izquierdo. Al presionar, se descargará un archivo PDF con el reporte. Es necesario que previamente se haya creado el formato de impresión del proceso de embarque.
Generar reporte Guía
Para el reporte de un registro se necesita ubicar en el listado y presionar el botón con icono de hoja de papel ubicado del lado izquierdo. Al presionar, se descargará un archivo PDF con el reporte. Es necesario que previamente se haya creado el formato de impresión del proceso de guía.
4.4 Recolecciones
Descripción general
Este proceso se desarrolla iniciando en el archivo Recoleccion.js. Una recolección contiene casi la misma información que un embarque. La diferencia es que con las recolecciones se enfoca más a los datos del remitente para realizar recolección en el proceso de última milla, a diferencia del embarque que se enfoca en el destinatario.
Inicialización de la vista
El proceso inicia en la pestaña Listado, se obtiene el listado de recolecciones usando el endpoint (este endpoint también es usado para la funcionalidad de filtrar):
- URL:
- /Recoleccion/GetByFiltro/{fechaInicial}/{fechaFinal}/{sucursal}/{estatus}/{folio}/{origen}/{destino}/{cliente}
- Variables:
- fechaInicial: la fecha de la que se me empezarán a tomar registros
- fechaFinal: la fecha de la que se me terminarán a tomar registros
- sucursal: sucursal en la que se creó la recolección
- estatus: estatus en el que se encuentra la recolección
- folio: folio de la recolección
- origen: origen de la recolección
- destino: destino de la recolección
- cliente: se usará por defecto el que está usando el sistema
Al obtener la respuesta se muestra en un listado.
Acciones del usuario
Agregar
A continuación se explican los datos necesarios para crear una recolección:
Sucursal : se precarga tomando el valor de los datos de inicio de sesión del usuario.
Folio Recolección: el folio de recolección se generará automáticamente al crear la recolección, por lo que desde el frontend no se manda.
Fecha: se obtiene por código, es la fecha actual de creación.
Tipo de seguro: se obtiene de los datos del cliente al haber sido seleccionado. Dependiendo el tipo de seguro puede llegar a cambiar en automático el Tipo de Cobro si así ha sido configurado en Parámetros de Configuración.
Porcentaje de seguro: se obtiene de los datos del cliente al haber sido seleccionado.
Valor declarado: definido por el usuario. Puede ser obligatorio si así ha sido configurado en parámetros de configuración.
Observaciones: definido por el usuario. Si el cliente tiene seguro por un tercero, se precargará la póliza del seguro si está dentro de los datos del cliente.
Referencia: definido por el usuario.
Paquetes: se agregan usando los productos registrados en el catálogo de productos. Es necesario seleccionar un cliente para poder agregar paquetes.
Complementos SAT: definidos por el usuario. Los complementos son registros estáticos en base de datos y fueron proporcionados por el equipo del ERP.
Remitente: es la persona o empresa que manda la mercancía. Los remitentes vienen del ERP. Al seleccionar uno el resto de la información será cargada si en el ERP ha sido registrada correctamente. La dirección y zona operativa asignada para el remitente será usada para el proceso de última Milla
Destinatario: es la persona o empresa que recibe la mercancía. Los destinatarios vienen del ERP. Al seleccionar uno el resto de la información será cargada si en el ERP ha sido registrada correctamente.
Recolección en diferente domicilio: al activar, la recolección entrará en proceso de última milla pero no se usará la dirección del remitente, sino la especificada en los campos que aparecerán.
Programar cita de recolección: al activar se puede especificar una ventana de tiempo en la que se quiere que la mercancía sea recolectada. Puede representar un costo extra si en parámetros de configuración fue especificado.
Entrega en sucursal: cuando se selecciona, la guía generada a partir del embarque no pasará por el proceso de última milla, sino por el proceso de entrega ocurre. Puede deshacer el cobro del concepto de entrega en caso de que aplique.
Entrega en diferente domicilio: al activar, la guía generada a partir del embarque entrará en proceso de última milla pero no se usará la dirección del destinatario, sino la especificada en los campos que aparecerán.
Entrega con cita: al activar se puede especificar una ventana de tiempo en la que se quiere que la mercancía sea entregada. Puede representar un costo extra si en parámetros de configuración fue especificado.
Conceptos de facturación: se generan con la cotización al presionar el botón Calcular tarifa. En el portal de cliente no se pueden agregar conceptos manualmente después de haber generado la cotización. Calcular la tarifa es el último paso porque es necesaria toda la información de la recolección para realizar el cálculo. Si se edita información después de la cotización es necesario generar una nueva cotización presionando de nuevo el botón Calcular Tarifa. El concepto Flete es el único obligatorio. Si se produce algún error al generar la cotización no se podrá guardar la recolección hasta haber resuelto los errores. El funcionamiento de la lógica de tarifas no cuenta con ningún problema. Los “errores” que se han reportado han sido por errores de usuario al momento de configurar las tarifas o convenios.
Ya que se tienen todos los datos se agrega la recolección presionando el botón Guardar Recolección para hacer la llamada al endpoint:
- URL:
- /Recoleccion/Agregar
- Body:
- Los datos ya especificados anteriormente.
Al agregar correctamente la recolección se dará la opción al usuario de crear el embarque a partir de la recolección recién creada. En caso de aceptar, se agregará el embarque y ambos registros quedarán relacionados. En caso de no aceptar se regresará al usuario al listado.
Modificar
Para modificar un registro se necesita ubicar en el listado y presionar el botón con icono de lápiz ubicado del lado izquierdo. Al presionar se mostrará el formulario de agregar con los datos del registro precargados. Los datos se obtienen al hacer una llamada al backend.
Obtener recolección por id
- URL:
- /api/Recoleccion/GetById/{IdRegistro}
- Variables:
- Id del registro
Ya con los datos cargados se puede modificar el formulario. Para guardar los cambios se presiona el botón Guardar Recolección ubicado en la parte inferior. Al presionarlo se hace una llamada al backend para actualizar la información.
Editar recolección
- URL:
- /api/Recoleccion/Modificar/{IdRegistro}
- Variables:
- Id del registro
- Body:
- Los datos ya especificados anteriormente.
Si la operación es exitosa se regresa al listado de registros. Si surge algún error se muestra mensaje al usuario y los datos permanecen en el formulario.
Consultar
Para consultar un registro se necesita ubicar en el listado y presionar el botón con icono de ojo ubicado del lado izquierdo. Al presionar, se mostrará el formulario de agregar con los datos del registro precargados y todos los campos deshabilitados. Los datos se obtienen al hacer una llamada al backend.
Obtener recolección por id
- URL:
- /api/Recoleccion/GetById/{IdRegistro}
- Variables:
- Id del registro
Eliminar
Para eliminar un registro se necesita ubicar en el listado y presionar el botón con icono de bote de basura, ubicado del lado izquierdo.
Solo pueden ser eliminados los registros que tengan estatus Cancelado.
Al eliminar, se hace la llamada al backend para validar los permisos del usuario.
- Validar permiso de usuario
- URL:
- /Utilerias/ValidaDerechos/{IdUsuario}/{IdPermiso}/3
- Variables:
- Id del usuario
- Id del permiso
- URL:
Si el usuario cuenta con el permiso necesario se hace una llamada al backend para realizar la acción.
- Eliminar recolección
- URL:
- /api/Recoleccion/Eliminar/{IdRegistro}/{IdUsuario}
- Variables:
- Id del registro
- Usuario
- URL:
Filtrar
En la vista de listado se pueden filtrar los registros usando diferentes parámetros, los parámetros deben ser características de las recolecciones deseadas. Los parámetros que no se quieran usar para filtrar se pueden dejar en blanco para que no tengan efecto. En caso de usar el filtro por Folio y tener otros filtros agregados, serán ignorados para darle prioridad al folio. Una vez establecidos los filtros se hace la llamada al backend:
- URL:
- /Recoleccion/GetByFiltro/{fechaInicial}/{fechaFinal}/{sucursal}/{estatus}/{folio}/{origen}/{destino}/{cliente}
- Variables:
- fechaInicial: la fecha de la que se me empezarán a tomar registros
- fechaFinal: la fecha de la que se me terminarán a tomar registros
- sucursal: sucursal en la que se creó la recolección
- estatus: estatus en el que se encuentra la recolección
- folio: folio de la recolección
- origen: origen de la recolección
- destino: destino de la recolección
- cliente: cliente de la recolección
Al obtener los registros se mostrarán en el listado.
Generar reporte
Para el reporte de un registro se necesita ubicar en el listado y presionar el botón con icono de hoja de papel ubicado del lado izquierdo. Al presionar, se descargará un archivo PDF con el reporte. Es necesario que previamente se haya creado el formato de impresión del proceso de recolección.