Skip to main content

HLD - Bascula

Documento de diseño de alto nivel​

Versión: 1.0
Fecha: 08 Diciembre de 2025
Autor: José Alberto Hernández Galicia

Tabla de Contenido​

  1. Control de Cambios
  2. Introducción
  3. Descripción general del contexto y Alcance
  4. Visión General de la Arquitectura
  5. Descripción de componentes clave
  6. Interacciones y flujos de datos
  7. Decisiones Arquitectónicas y Justificación
  8. Consideraciones de seguridad y escalabilidad
  9. Requerimientos no funcionales
  10. Lineamientos y Estandares de Codificación

1. Control de Cambios​

VersiónAutorDescripciónFecha
1.0José Alberto Hernández GaliciaCreación09/12/2025

2. Introducción​

El propósito de este documento de Definición de Arquitectura de Alto Nivel (High-Level Design, HLD) es proporcionar una visión global y comprensiva de la arquitectura del sistema propuesto. Este documento sirve como un puente entre los requisitos del negocio y la implementación técnica detallada, ofreciendo una representación abstracta de los componentes principales del sistema, sus interacciones y las decisiones arquitectónicas clave que guiarán el desarrollo.

A través de este HLD, buscamos proporcionar una guía clara y estructurada que facilitará la transición hacia las etapas de diseño detallado y desarrollo, asegurando que el sistema final sea robusto, eficiente y alineado con los objetivos del negocio.

2.2. Objetivo​

Los objetivos del documento son:

Proporcionar una Visión General:

  • Describir la arquitectura del sistema en un nivel alto, destacando los componentes principales, sus responsabilidades y cómo interactúan entre sí.

Facilitar la Comunicación:

  • Actuar como una herramienta de comunicación entre las partes interesadas, incluyendo gerentes, desarrolladores, arquitectos, y otros involucrados en el proyecto, asegurando que todos tengan una comprensión común del sistema.

Establecer una Base Sólida:

  • Sentar las bases para las fases de diseño detallado y desarrollo, proporcionando un marco estructural que guíe las decisiones técnicas y de implementación.

Asegurar la Coherencia y la Escalabilidad:

  • Garantizar que el diseño del sistema sea coherente con los objetivos del negocio y pueda escalar para satisfacer futuras necesidades y requerimientos.

2.3. Alcance​

Este documento está estructurado para cubrir los siguientes aspectos esenciales de la arquitectura del sistema:

Descripción del Contexto y Alcance:

  • Definir el contexto en el que se desarrollará el sistema y los límites de su alcance.

Visión General de la Arquitectura:

  • Presentar un diagrama de alto nivel y una descripción de los componentes principales del sistema.

Descripción de Componentes Clave:

  • Detallar los componentes principales, sus roles y responsabilidades.

Interacciones y Flujos de Datos:

  • Describir cómo interactúan los componentes entre sí y cómo fluyen los datos a través del sistema.

Decisiones Arquitectónicas y Justificación:

  • Documentar las decisiones arquitectónicas clave y las razones detrás de ellas.

Consideraciones de Seguridad y Escalabilidad:

  • Discutir cómo se abordarán las preocupaciones de seguridad y cómo el diseño permitirá la escalabilidad del sistema.

Requisitos No Funcionales:

  • Identificar y describir los requisitos no funcionales importantes que deben ser considerados en el diseño.

2.4. Glosario​

La siguiente tabla enlista los términos y sus significados a usarse en el documento:

TÉRMINOSIGNIFICADO
MSAAcrónimo usado para referirse a una arquitectura de microservicios. Proviene de las palabras en inglés: MicroServices Architecture
ARArquitectura de Referencia
SOAService Oriented Architecture
ACIDAtomicity, Consistency, Isolation, Durability
TDDTest Driven Development
BDDBehavior Driven Development
DevOpsDevelopment and Operations
HTTPHypertext Transfer Protocol
DDDDomain Driven Design
JSONJavaScript Object Notation
RESTRepresentational state transfer
SOLIDPrincipios de diseño de software:
- S – Single Responsibility Principle (SRP)
- O – Open/Closed Principle (OCP)
- L – Liskov Substitution Principle (LSP)
- I – Interface Segregation Principle (ISP)
- D – Dependency Inversion Principle (DIP)

3. Descripción general del contexto y Alcance​

3.2. Descripción General del Proyecto​

Alcance del MVP​

  • Registrar la salida vinculada a una entrada abierta, con segunda pesada y cálculo de diferencia
  • Dar de alta choferes para seleccionarlos al registrar entradas/salidas
  • Dar de alta vehículos para asociarlos a movimientos de báscula
  • Registrar contenedores/cajas para asociarlos a entradas/salidas
  • Dar de alta productos (leche, queso, desechos, etc.) para seleccionarlos en los movimientos y cálculos.
  • Administrar usuarios, roles y alcances para controlar quién ve/edita qué módulos.
  • Consultar y exportar movimientos para controlar operaciones, diferencias y entradas sin salida
  • Un endpoint para consultar Entradas para Disponer información para otros sistemas como YMS o LDV
  • Un endpoint para consultar Salidas para Disponer información para otros sistemas como YMS o LDV

Arquitectura Propuesta​

La solución propuesta es llevar la implementación de estos procesos a una arquitectura en microservicios con microfrontend dentro de una infraestructura cloud.

Frontend - Módulos​

Módulo Usuario

Módulo Camion

Backend - Microservicios​

alpura-back-java-msa-balance: Microservicio encargado de toda operativadad del peso de los camiones, como son los registros de las entradas y salidas.

Componentes reutilizables:

  • Catalogo de producos: Actualmente en la arquitectura , se tiene varios compones que se puede reutilizar, como es es el caso de gestor de cátalogos, este apartado vamos dar esta los productos.

  • Gestión Usuario: Este módulo ya existe actualemtne en la arquitectura de Alpura, el cual este nuevo requerimiento podemos reutilizar para la administración de usuario.

  • Reportes : Ya se cuenta con un componente que se puede usar para generar diferentes tipos de reportes, Solo se tiene que configurar en el proyecto de acuerdo a las regals de negocio.

    • Solicitar un maquetado html por UX
    • El html se deberá guardar a nivel de base de datos.

alpura-back-java-msa-report: Microservicio encargado de realizar los diferentes reportes solicitado por el sistema. -Poder exportar a un Excel/PDF

Base de Datos​

Para el sistema de la BÁSCULA se tiene como propuesta una base de datos estructurada (PostgreSQL) para almacenar toda información de usuarios, camion, choferes y administración de contenedores , etc.

Tecnología Frontend​

Finalmente, para la interfaz del Usuario se pretende llevar el desarrollo con Angular, donde buscamos mejorar la interacción con las pantallas, que le sea fácil interactuar con la información en los diferentes módulos que proveerá el sistema.

En esta solución se busca mejorar la eficiencia, manejo de errores, ofrecerle al usuario una interfaz intuitiva y la alta disponibilidad de servicio.

Características funcionales​

Características no funcionales​

3.3. Descripción de Escenarios y Seguimiento​

Gestión de Usuario​

En el siguiente escenario muestra el usuario pueda tener credenciales para poder acceder al sistema

  1. Ingresar usuario,contraseña
  2. De acuerdo al rol de cada usuario , va poder ver diferentes pantallas
  3. La sesión se registra y le muestra la pantalla

Alta y Edición

  1. Dar de alta un usuario
  2. Poder asignarle un rol como son :
    • Entrada
    • Salida
    • Catálogos
    • reportes
  3. Control de acceso por planta/bascula
  4. Poder realizar búsqueda:
    • usuario
    • rol
    • estado

Entrada de Vehículo​

Entrada Camión

  1. Usuario logueado como Operador de Báscula
  2. Ingresa los siguientes campos :
    • Fecha/hora
    • Báscula (1/2)
    • Tipo movimiento=Entrada
    • Placa contenedor
    • Placas vehículo
    • No. económico (opc.)
    • Transporte
    • Proveedor/Razón social (si aplica)
    • Chofer (nombre y licencia)
    • Producto
    • Origen (opc.)
    • Ticket (leche, opc.)
    • Peso 1 (kg)
    • Selector manual (S/N)
    • Doble pesado (S/N)
    • Usuario
    • Observaciones (opc.).
  3. Lectura de peso
    • 3.1 Manual
    • 3.2 Automático(viene de la bascula)
  4. Guardar Informacion
    • Valida Obligatoriedad
    • Generar Id Entrada
    • Estatus Abierto
  5. Si un catalgo no existe contende, dar de alta al momento.
  6. Validar si va ser doble pesaje poner S

Consulta entrada

  1. Usuario logueado como Sistema Integrador
  2. Poder realizar consultar por lo siguientes campos:
    • rango de fechas
    • placa(opc)
    • económico(opc)
    • estatus (opc)
    • proveedor (opc)
    • ticket (opc)
  3. validar campos obligatorios
    • numericos
    • existencia de los catalgos en la BD
  4. Mostrar en el sistema la información
    • id_entrada
    • estatus
    • detalle

Salida de camión

  1. Usuario logueado como Operador de Báscula
  2. Seleccionar entrada abierta id, placa, Económico, proveedor, fecha.
  3. Ingresar los siguientes campos
    • Fecha/hora salida
    • Peso (hay dos opciones)
      • Automatica
      • Manual
  4. Calcular la diferencia (aplicar litros en su caso)
    • Peso2 - peso1
  5. Guardar la información
    • se actualiza estatus = Cerrado
    • Evitar duplicar Cierres
  6. Si no hay entrada realizar los siguientes
    • Bloquear la salida e informar que se debe registrar en el sistema (Proceso Entrada).

Consulta Salida

  1. Usuario logueado como Sistema Integrador
  2. Poder realizar consultar por lo siguientes campos:
    • rango de fechas
    • placa(opc)
    • económico(opc)
    • estatus (opc)
    • proveedor (opc)
    • ticket (opc)
    • entrada
  3. validar campos obligatorios
    • numericos
    • existencia de los catalgos en la BD
  4. mostrar en el sistama la información
    • id_entrada
    • estatus
    • detalle

Alta/Consulta/Edición de Chofer​

  1. Usuario logueado como Operador de Báscula
  2. Ingresa datos para registrar un tipo de chofer
    • Nombre Completo (unico)
    • No. Licencia. (unico)
    • Vigencia(opc)
    • Transporte(opc)
    • Estatus (activo/inactivo)

consulta

  1. Usuario logueado como Operador de Báscula
  2. Busqueda por
    • nombre
    • licencia
  3. Se muestra resultado en el sistema

Edición

  1. Usuario logueado como Operador de Báscula
  2. Consulta de chofer
  3. mostrar la información en la pantalla
    • Nombre Completo (unico)
    • No. Licencia. (unico, no se puede editar)
    • Vigencia(opc)
    • Transporte(opc)
    • Estatus (activo/inactivo)
    • fecha ultima modificacion
    • usuario que modifico

Administración de Contenedores​

Alta*

  1. Usuario logueado como Operador de Báscula
  2. Ingresar campos para el registro de un contenedor
    • Placa Contenedor
    • Identificador Interno(opc)
  3. Registro exitoso.

Consulta

  1. Usuario logueado como Operador de Báscula
  2. Ingresar campos para la busqueda
    • Placa Contenedor
    • Identificador
  3. Se muestra los resultados en el sistema.

Edición

  1. Usuario logueado como Operador de Báscula
  2. Ingresar campos para la busqueda
    • Placa Contenedor
    • Identificador
  3. Se muestra los resultados en el sistema.
  4. Actualización de información
  • Placa Contenedor
  • Identificador
  1. Se agrega información de auditorio
    • fecha modificacion
    • Usuario
  2. Edición exitoso

Administración de Productos​

Alta*

  1. Usuario logueado como Operador de Báscula
  2. Ingresar los datos para la alta de producto
    • Nombre de producto
    • Identificador interno
    • estatus
  3. validar para no duplicar información de producto
  4. Se guarda la información en el repositorio.

Consulta

  1. Usuario logueado como Operador de Báscula
  2. Ingresar los datos para la busqueda de producto
    • Nombre de producto
    • Identificador interno
  3. Se muestra el resutaldo de la información en el sistema.

Nota Este módulo, es un componente que podemos reutilizar del siguiente Microservicio

  • alpura-back-java-msa-general-catalog
    • Para dar de alta/consulta/edición de productos,

Generación de reportes​

  1. Usuario logueado como Operador de Báscula
  2. Para generar el reporte , se realiza la busqueda por lo siguientes filtro
    • Rango de fechas
    • Placa vehículo
    • Placa contenedor
    • No. económico
    • Proveedor
    • Transporte
    • Chofer
    • Producto
    • Estatus (Abierta/Cerrada)
    • Ticket.
  3. Muestra la informacón en el sistema con las siguientes caracteristicas
    • Información paginada y por ordenar por campos
      • Entrada vs Salida (Peso1, Peso2, Diferencia)
      • fechas/horas
      • usuario.
  4. El reporte generado, debe poderse exportar en :
    • Excel
    • CSV
  5. Fin

Nota Este módulo, se tiene un componente que podemos llevar a cabo las configuraciones para la generación de reportes

Consulta Movimientos​

3.4. DIAGRAMA DE CONTEXTO​

Orquestación y comunicación​

En el siguiente diagrama podemos visualizar los microservicios con los módulos del front el como se va estar llevando comunicación.

4. Visión General de la Arquitectura​

La Arquitectura del sistema se describe en 3 principales vistas, una vista física, una vista lógica, y una vista de los principales componentes o drivers del sistema.

4.2. Capa de la vista física​

El diagrama representa una posible distribución de componentes en servidores lógicos o físicos/virtuales

4.3. Capa de la vista lógica​

4.3.1. Flujo 1​

Diagrama de Secuencia de clientes:

4.4. Capa de la vista principal​

(Nota: En este apartado se debe incluir la descripción y diagrama de la vista principal)

5. Descripción de componentes clave​

(Nota: En este apartado se debe incluir la descripción detallada de los componentes principales del sistema)

5.2. Atributos de calidad​

(Nota: En este apartado se deben listar y explicar los atributos de calidad requeridos para la arquitectura)

Componentes (artefactos)​

En este apartado tenemos todos los componentes considerados para la solución de alpuraOne.

  • Análisis de requerimientos
  • Diagrama de casos de Uso
  • Diagramas de Contexto
  • Diagramas de secuencia
  • Diagrama de arquitectura
  • Diseño de base entidad relación
  • Análisis EBS Oracle alpuraOne
  • Maquetado web Módulo Usuarios
  • Maquetado web Módulo Productos
  • Maquetado web Módulo Chofer
  • Maquetado web Módulo Contenedores
  • Maquetado web módulo Reportes
  • Creación de grupo en gitlab
  • Creación de repositorio alpura-back-java-msa-balance
  • Creación de repositorio alpura-back-java-msa-report
  • Creación de repositorio alpura Front
  • Solicitud de usuarios base de datos postgreSQL
  • Creación de esquema Bascula
  • Desarrollo de microservicio alpura-back-java-msa-balance
  • Desarrollo de microservicio alpura-back-java-msa-report
  • Desarrollo web Módulo Usuarios
  • Desarrollo web Módulo Productos
  • Desarrollo web Módulo Chofer
  • Desarrollo web Módulo Contenedores
  • Desarrollo web módulo Reportes
  • Configuración Pipeline microservicio alpura-back-java-msa-balance
  • Configuración Pipeline de microservicio alpura-back-java-msa-report
  • Configuración pipeline front
  • Despliegue CI/CD microservicio alpura-back-java-msa-balance
  • Despliegue CI/CD de microservicio alpura-back-java-msa-report
  • Despliegue CI/CD front
  • Pruebas Unitarias de microservicio alpura-back-java-msa-balance
  • Pruebas Unitarias de microservicio alpura-back-java-msa-report
  • Pruebas unitarias Módulo Usuarios
  • Pruebas unitarias Módulo Productos
  • Pruebas unitarias Módulo Chofer
  • Pruebas unitarias Módulo Contenedores
  • Pruebas unitarias Módulo Reportes
  • Pruebas E2E Módulo Usuarios
  • Pruebas E2E Productos
  • Pruebas E2E Chofer
  • Pruebas E2E Contenedores
  • Pruebas E2E Reportes
  • Liberación Producción Módulo Usuarios
  • Liberación Producción Productos
  • Liberación Producción Módulo Chofer
  • Liberación Producción Módulo Contenedores
  • Liberación Producción módulo Reportes
  • Liberación Producción módulo Detalle LPN
  • Liberación Producción de microservicio alpura-back-java-msa-balance
  • Liberación Producción de microservicio alpura-back-java-msa-report

5.3. Restricciones​

(Nota: En este apartado se deben listar las restricciones técnicas y de negocio que afectan la arquitectura)

6. Interacciones y flujos de datos​

Entidades​

En el siguiente diagrama podemos visualizar las principales entidades para la solución propuesta.

Diccionario de datos​

Tabla:​

7. Decisiones Arquitectónicas y Justificación​

[Explicar de manera clara las decisiones de arquitectura de los principales componentes utilizados]

8. Consideraciones de seguridad y escalabilidad​

[Se deberá indicar el número de transacciones soportadas por cada uno de los componentes así como las réplicas requeridas en ambientes productivos]

[Agregar los aspectos de seguridad]

Escalabilidad horizontal: La arquitectura basada en microservicios debe permitir escalar dinámicamente instancias de API o bases de datos según demanda.

Arquitectura modular: Los componentes deben estar desacoplados para facilitar el mantenimiento y la escalabilidad.

9. Requerimientos no funcionales​

[Listar y explicar los requerimientos no funcionales a considerar en la arquitectura]

(Ver sección 3.2 para la tabla completa de características no funcionales)

10. Lineamientos y Estandares de Codificación​

Un estándar de codificación completo comprende todos los aspectos de la generación de código. Si bien los programadores deben implementar un estándar de forma prudente, éste debe tender siempre a lo práctico. Un código fuente completo debe reflejar un estilo armonioso, como si un único programador hubiera escrito todo el código de una sola vez.

El estándar busca asegurarse de que todos los programadores del proyecto trabajen de forma coordinada.

[Incluir el estándar de codificación utilizado actualmente]

10.2. Lineamientos Tecnológicos​

A continuación, se presentan los estándares y componentes considerados dentro del desarrollo. Si existiera alguna excepción o desviación en implementación forzada por la tecnología deberá ser informado para su aprobación.

[Pendiente por realizar definición]