Skip to content

README.md

Latest commit

 

History

History
123 lines (84 loc) · 9.05 KB

README.md

File metadata and controls

123 lines (84 loc) · 9.05 KB
Raw
logoo

Sistema de Gestión de Brechas Digitales e Inclusión (B2G)

Static Badge Badge en Desarollo

Java Spring Boot Maven TiDB Docker Render Static Badge Swagger Spring Data JPA Hibernate

📝 Descripción del Proyecto

El Sistema de Gestión de Brechas Digitales e Inclusión (B2G) es una plataforma de analítica territorial diseñada para gobiernos y organizaciones. Su objetivo es centralizar, cruzar y visualizar datos críticos como la infraestructura de red móvil (antenas) y los indicadores socioeconómicos locales (empleo, educación y salud mental).

A través de este motor, los tomadores de decisiones pueden identificar qué regiones sufren de exclusión digital y coordinar planes de acción basados en datos reales.

⚡ Características Principales

  • Mapeo de Infraestructura: Consulta y procesamiento geográfico de datos de antenas y niveles de congestión de red en tiempo real.
  • Tendencias Históricas Cruzadas: Endpoints optimizados que unifican estadísticas de empleo mensuales con la calidad de conectividad por clusters.
  • Arquitectura de Alto Rendimiento: Consultas nativas eficientes (CTEs y JSON) que delegan el procesamiento pesado a la base de datos para respuestas en milisegundos.
  • Documentación Interactiva: Contratos de API totalmente integrados con Swagger para facilitar el trabajo en paralelo con el Frontend.

📂 Arquitectura y Estructura de Capas

El código fuente se organiza bajo una arquitectura modular y limpia dentro del paquete raíz com.example.appbitb2g, dividiendo las responsabilidades de forma estricta:

  • Controladores (controller): Puerta de entrada que expone los endpoints de la API REST, gestiona los métodos HTTP, políticas de CORS y validaciones iniciales.
  • DTOs (dto): Objetos de transferencia de datos inmutables definidos mediante Records de Java, encargados de transportar la información blindando las entidades de la base de datos y cumpliendo el contrato JSON con el Frontend.
  • Servicios (service e service.impl): Núcleo de la lógica de negocio donde se procesan, unifican y filtran los flujos de datos (usando Java Streams y manejo seguro de nulos) antes de enviarlos a la vista.
  • Persistencia y Modelos (model y repository): Capa encargada del mapeo de entidades con Hibernate y la comunicación con MySQL/TiDB mediante Spring Data JPA, incluyendo las consultas nativas optimizadas.

🚦Endpoints de la API y Contratos de Datos

Documentación Swagger

La API cuenta con documentación interactiva generada automáticamente con Swagger/OpenAPI. Una vez que el servicio esté corriendo (ya sea en local o en producción), puedes explorar los endpoints, ver los esquemas de datos y realizar peticiones de prueba desde tu navegador.

🚀 Instrucciones para Correr el Proyecto Localmente

Prerrequisitos

  • Docker y Docker Compose instalados.
  • Git.

🛠️ Pasos para la Ejecución con Docker

  1. Clonar el repositorio: 
    git clone https://github.com/No-Country-simulation/S06-26-NC-EQUIPO--72.git
  2. Configurar las variables de entorno: 
    Asegúrate de configurar las credenciales de tu base de datos y servicios en el archivo .env local
(o pasarlas como variables al contenedor) respetando las llaves
requeridas (SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, etc.) *(Mas detalle siguiente sección)
  3. Construir y levantar el contenedor: 
     # Si usan Docker Compose para levantar el entorno completo:
  docker compose up --build

  # O si construyen la imagen individualmente:
  docker build -t app-b2g-back .
  docker run -p 8080:8080 --env-file .env app-b2g-back

El servidor web se compilará y empaquetará automáticamente dentro del contenedor, quedando disponible en el puerto 8080.

Despliegue en Producción

Este servicio backend está preparado para ser desplegado en cualquier plataforma de tipo PaaS que acepte archivos de tipo Dockerfile. En este caso el servicio se encuentra desplegado en la plataforma Render mediante el archivo Dockerfile que se encuentra en la raíz del proyecto.

Si necesitas replicar este despliegue o configurar un entorno de staging, sigue estas instrucciones:

1. Configuración del Servicio en Render

  • Crea un nuevo Web Service en Render y conéctalo al repositorio de GitHub.
  • Llena los campos de configuración principales con los siguientes valores:
    • Branch: elegir la rama del repositorio remoto (main, develop, etc).
    • Root Directory: back (Crítico: Esto le indica a Render que solo debe leer la carpeta del backend y su Dockerfile).
    • Runtime: Docker (Crítico: No usar entornos nativos, seleccionar Docker).
    • Instance Type: Free (o la capa requerida).

Nota: Los campos de "Build Command" y "Start Command" serán ignorados o desaparecerán al elegir Docker, ya que el Dockerfile interno se encarga de empaquetar con Maven y arrancar el servidor. Si se elige la capa gratuita que ofrece Render, el servicio desplegado sufrirá de un cold-start debido a que la plataforma suele poner en suspención los servicios desplegados de forma gratuita. El tiempo de inicialización del servicio luego de la suspensión automática suele rondar lo 4 o 5 min.

2. Variables de Entorno (Environment Variables)

Para que el contenedor de Spring Boot logre comunicarse con la base de datos externa y el servicio de IA del cual depende, se deben agregar estrictamente las siguientes variables de entorno en el panel de Render (pestaña Environment).

Spring Boot utilizará la característica de Relaxed Binding para sobrescribir los valores locales de application.properties.

Nombre dela Variable (Key) Valor Esperado (Value) Descripción
AI_SERVICE_URL url_ia_service URL del servicio de IA
SPRING_DATASOURCE_URL jdbc:mysql://[DB_HOST]:[DB_PORT]/[DB_NAME]??sslMode=VERIFY_IDENTITY&serverTimezone=UTC La URL de conexión JDBC. Debe incluir sslMode=VERIFY_IDENTITY por seguridad y separar las credenciales.
SPRING_DATASOURCE_USERNAME db_user_example El usuario de la base de datos de producción.
SPRING_DATASOURCE_PASSWORD ******** La contraseña asignada por el proveedor de la base de datos.

Importante sobre el Puerto: No es necesario configurar una variable PORT manual. En este caso Render inyecta dinámicamente el puerto, y el Dockerfile del proyecto está preparado para leerlo y asignar Spring Boot al puerto correcto de forma automática.

3. Base de Datos Externa

La instancia de MySQL no corre dentro de Render por motivos de persistencia de disco y cuota de espacio. Las credenciales insertadas en el paso anterior deben obtenerse del panel de control del clúster de MySQL del proveedor que se haya seleccionado. En nuestro caso se ha elegido TiDB como proveedor de servicio para almacenar los datos en una instancia de MySQL.

Para conectarte localmente a esta base de datos de producción (ej. usando DBeaver o MySQL Workbench), recuerda que se debe configurar la conexión requiriendo SSL (Use SSL: Require).

Autores


Georgina Bosque
Matías Almaraz
Héctor Cortez
Tomás Barrera