Documentación Desarrollo Trexsas Backend

Java Package

Package Resources

• Logos
• QR
• Static
• Templates
• Application Properties
• Keystore.p12 (Certificación de seguridad página web)

RevisionPapeles

GlobalExceptionHandler

El modelo de este proyecto está basado en las siguientes anotaciones:

@Entity
@Table(name = "nombreTabladb")

Definen a la clase que es una entidad de modelado de datos y de tablas de la base de datos donde la anotación @Table debe apuntar a la tabla de la base de datos. Los nombres de las columnas de la tabla deben coincidir exactamente para poder mapearlos de forma correcta, también es posible renombrarlos con variables privadas.

Ejemplo de estructura de datos

@Entity
@Table(name = "afiliacion")
public class Afiliacion {
    
    @Id
    @GeneratedValue
    @Column(name = "id_afiliacion")
    private Long idAfiliacion;
    
    @Size(max = 10)
    @Column(name = "codigo_interno_afiliacion")
    private String codigoInternoAfiliacion;
}

Descripción de Anotaciones

Los repositorios forman parte de la capa de persistencia de datos del proyecto y está construido utilizando Spring Data JPA, un módulo que simplifica de forma significativa la interacción con la base de datos.

Esta interfaz es responsable de ejecutar todas las operaciones necesarias para consultar, almacenar, actualizar o eliminar información relacionada con las tablas.

Funcionalidades Automáticas

Al extender de JpaRepository<nombreModelo, Long>, el repositorio obtiene automáticamente:

• Búsquedas por ID
• Obtención de todos los registros
• Creación y actualización de entidades
• Eliminación de registros
• Contadores y validación de existencia
• Paginación y ordenamiento integrados

Consultas Personalizadas

Además de las operaciones básicas, el repositorio define consultas personalizadas mediante la anotación @Query. Estas consultas permiten obtener información más específica.

La capa de servicio es una parte fundamental de la arquitectura de la aplicación, ya que se encarga de manejar la lógica de negocio y de coordinar las operaciones que involucran el acceso a datos.

El servicio actúa como un intermediario entre los controladores y los repositorios, garantizando una separación adecuada de responsabilidades.

Características del Servicio

Este servicio, marcado con la anotación @Service, encapsula todas las operaciones necesarias para gestionar una entidad del sistema.

Métodos Esenciales

Visión General del Servicio

• Gestiona toda la lógica de negocio relacionada con una entidad específica
• Aísla la interacción con la base de datos mediante el uso del repositorio
• Facilita el mantenimiento y la escalabilidad del proyecto
• Mantiene una arquitectura limpia al evitar colocar lógica innecesaria en los controladores
• Proporciona métodos claros y reutilizables

Cifrador

Esta clase es una utilidad para convertir una contraseña en un hash usando SHA-256.

package com.itefs.trexsas.utilidades;

import org.apache.commons.codec.digest.DigestUtils;

public class Cifrador {
    
    public String cifrar(String clave) {
        String cifrada = DigestUtils.sha256Hex(clave);
        return cifrada;
    }
}

DigestUtils.sha256Hex():

• Toma tu texto (ej: "123456")
• Aplica algoritmo SHA-256
• Convierte el resultado a formato hexadecimal

ConvertirNumeroLetra

Esta clase maneja cantidades grandes (miles, millones, miles de millones) y convierte números a texto en español.

Análisis del Método Principal

public String cantidadConLetra(String s)

Recibe una cadena (ejemplo "1234.56") y devuelve la parte entera convertida a palabras.

Paso 1: Preparación del número

BigDecimal totalBigDecimal = new BigDecimal(s).setScale(2, BigDecimal.ROUND_DOWN);
long parteEntera = totalBigDecimal.toBigInteger().longValue();

Convierte el texto a BigDecimal para manejar números grandes con precisión, redondea hacia abajo a 2 decimales y extrae la parte entera como número long.

Paso 2: Separación en grupos de tres cifras

El número se divide de derecha a izquierda en bloques de 3 cifras:

1. Unidades (0 – 999)
2. Miles (1,000 – 999,999)
3. Millones (1,000,000 – 999,999,999)
4. Mil millones (hasta 999,999,999,999)

int triUnidades      = (int)((parteEntera % 1000));
int triMiles         = (int)((parteEntera / 1000) % 1000);
int triMillones      = (int)((parteEntera / 1000000) % 1000);
int triMilMillones   = (int)((parteEntera / 1000000000) % 1000);

Correo

Este fragmento pertenece a un servicio de envío de correos en Spring Boot. Su función es enviar un correo HTML cuando un usuario solicita recuperar su contraseña.

Inyección de dependencias

@Autowired
private JavaMailSender mailSender;

Spring Boot inyecta automáticamente un objeto JavaMailSender, que es la clase responsable de enviar correos electrónicos.

Asuntos predefinidos

private final String olvidoClave = "Olvidaste tu clave TREX.SAS";
private final String solicitudAfiliacion = "Solicitud de vinculación a TREX.SAS";
private final String reserva = "Reserva de transporte con TREX.SAS";

Método enviarCorreoRecuperacion

@Async
public void enviarCorreoRecuperacion(...) {
    // Construcción del mensaje HTML
    String cuerpoMensaje = "<body style=...>" ... "</body>";
    
    // Configuración del mensaje
    MimeMessage message = mailSender.createMimeMessage();
    MimeMessageHelper helper = new MimeMessageHelper(message, true);
    
    helper.setSubject(olvidoClave);
    helper.setTo(destinatario);
    helper.setText(cuerpoMensaje, true);
    
    // Envío del correo
    mailSender.send(message);
}

@Async indica que este método se ejecutará en segundo plano, es decir, sin bloquear la solicitud HTTP del usuario.

GeneradorCredenciales

Esta clase está diseñada para crear automáticamente credenciales (usuario y contraseña) que puedan asignarse a una persona al momento de registrarse en un sistema.

Método para generar un nombre de usuario

public String generarUsuario(String nombres, String apellidos)

Crea un nombre de usuario combinando:

• La primera inicial del nombre
• El primer apellido completo
• La inicial del segundo apellido (si la persona tiene dos apellidos)

Método para generar una contraseña aleatoria

public String generarContraseña()

Crea una contraseña compuesta por 15 caracteres aleatorios, usando:

• Letras mayúsculas
• Letras minúsculas
• Números

GeneradorNumeroFuec

Esta clase está diseñada para generar un código único siguiendo una estructura numérica fija. Este tipo de funcionalidad se usa cuando una organización necesita emitir identificadores oficiales o consecutivos con un formato estandarizado.

Componentes principales

La clase define varios valores constantes usados como partes del número final:

• Un código territorial
• Un código de habilitación
• El año actual tomado del sistema
• Un año base o referencia establecida previamente

Método para generar el número principal

public String generarNumeroFuec(int consecutivoInternoContrato)

Este método recibe un número interno que representa un consecutivo, y lo transforma para cumplir un formato específico.

GeneradorToken

Esta clase está diseñada para generar y manipular tokens JWT, que son cadenas firmadas digitalmente usadas para autenticación, autorización o transporte seguro de información dentro de un sistema.

Los tokens JWT permiten incluir datos dentro de una estructura compacta y verificable sin necesidad de mantener una sesión en el servidor.

Funcionamiento general

Cada token incluye tres partes:

1. El encabezado
2. La información interna (claims)
3. La firma, generada con una clave secreta

La firma garantiza que el token no pueda ser modificado sin invalidarse.

Métodos principales

Pdf

La clase Pdf es un servicio de Spring (@Service) encargado de generar diferentes documentos PDF (contratos, FUEC, facturas, órdenes de servicio, cuentas de cobro) usando la librería JasperReports.

Tecnologías utilizadas

• JRXML → Plantillas diseñadas en iReport o Jaspersoft Studio
• QR → Genera códigos QR (para el FUEC)
• NumeroALetras → Convierte números a texto
• Conexiones a base de datos → Para llenar reportes con datos desde MySQL

Flujo general

1. Recibe datos desde tu sistema
2. Carga un diseño .jrxml de JasperReports
3. Inyecta los parámetros
4. Genera un PDF en una carpeta del proyecto
5. (Opcional) genera o elimina códigos QR
6. (Opcional) llena reportes con bases de datos reales

Métodos principales

PropertiesReader

La clase PropertiesReader funciona como un archivo de configuración centralizada dentro de tu aplicación.

Su objetivo principal es definir todas las rutas de carpetas donde se guardan y se leen los archivos utilizados por tu sistema.

Beneficios

• Evita tener rutas "quemadas" en todas partes del código
• Cambias la ruta en un solo lugar y toda la app se actualiza
• Permite separar fácilmente entorno de pruebas y entorno de producción
• Hace el código más limpio y mantenible

Atributo principal: ruta_raiz

// Entorno de pruebas se utiliza el path de abajo
public static final String ruta_raiz = 
    "C:/Users/D.agudelo/Documents/archivos_trex/";

Esta es la carpeta base donde se guardan todos los archivos.

Subrutas generadas

URL para los QR del FUEC

public static final String URL_FUEC_QR = 
    "http://127.0.0.1:4200/#/fuecInfo/";

El sistema genera códigos QR para los FUEC. El QR abre una URL que permite ver el documento desde el frontend (Angular).

QR

Esta clase tiene tres propósitos principales:

1. Generar un código QR en formato PNG
2. Borrar un QR previamente generado
3. Construir un texto descriptivo para incluir en el QR o documentos asociados

Método generateQR

public String generateQR(String text, int h, int w) throws Exception

Hace lo siguiente:

1. Generar un nombre único para el archivo usando fecha y hora
2. Crear el archivo destino
3. Cifrar el valor que irá en el QR
4. Construir el enlace final que quedará dentro del QR
5. Generar el QR con ZXing
6. Crear la imagen en memoria
7. Guardar el archivo en disco

Método eliminarQR

public void eliminarQR(String nombre)

Permite borrar un QR ya creado. Es útil para:

• Limpieza de archivos temporales
• Regenerar un QR actualizado

Método toString(...)

Este método construye un texto grande que describe todos los datos del FUEC (vehículo, conductores, fechas, contrato...).

Whatsapp

Esta clase es un servicio Spring (@Service) utilizado para enviar mensajes por WhatsApp usando la API de Twilio.

Atributos importantes

public static final String ACCOUNT_SID = 
    "ACa53de39534fae34c11d90e2fa78b1200";
public static final String AUTH_TOKEN = 
    "d045770f3476eb51ce3518f9d421d834";

Método main - Prueba de integración

Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

Message message = Message.creator(
    new PhoneNumber("whatsapp:+573003103066"),
    new PhoneNumber("whatsapp:+14155238886"),
    "Esto es una prueba de envio desde la plataforma trex"
).create();

System.out.println("Mensaje enviado con SID: " + message.getSid());

Explicación:

• El primer número es el destinatario real
• El segundo es el número de sandbox de Twilio
• El texto es el mensaje que llega por WhatsApp

Logos

QR

Static

Home.html

application.properties