Propósito: Servicio CORE del sistema Bimtrazer. Gestión completa de etiquetas (labels) de planificación, cálculo de avances ponderados, proyecciones, factores de compresión y SPI. Es el servicio con mayor complejidad y número de endpoints.
Tecnología: Go 1.24.0 / Gin v1.10.0
Puerto::8102
Módulo:labels
CI/CD: GitLab CI/CD
Propósito de Negocio en Detalle
Las etiquetas (labels) son el mecanismo central de organización del trabajo en Bimtrazer. Una etiqueta agrupa bloques constructivos con pesos de contribución, permitiendo: - Calcular el avance total de una fase de obra - Proyectar fechas de término ajustadas - Comparar lo planificado vs lo ejecutado - Generar gráficos de curva S (proyección temporal)
Endpoints Expuestos (~47 totales)
GET (14 endpoints)
Path
Descripción
GET /labels/by-project/:projectId
Lista etiquetas del proyecto
GET /labels/dashboard/:projectId
Etiquetas asignadas al dashboard
GET /labels/groups/:projectId
Grupos de etiquetas
GET /labels/groups/alias-and-codes/:projectId
Alias y códigos de grupos
GET /labels/:projectId
Etiquetas por proyecto
GET /labels/last-dates/:projectId
Últimas fechas actualizadas
GET /labels/graph-data/:projectId/:labelCode
Datos de gráfico de proyección
GET /labels/graph-data-freezing-past/:projectId/:labelCode
Gráfico con congelación del pasado
GET /graph-data-v2/:projectId/:labelCode
Gráfico V2 mejorado
GET /graph-data-freezing-past-v2/:projectId/:labelCode
V2 con congelación del pasado
GET /labels/calculate-in-progress-contributions/:projectId/:labelCode
Contribuciones en progreso
GET /fixed-weights/:projectId
Pesos fijos configurados
GET /general/:projectId
Etiqueta general del proyecto
GET /schedule/progress/by-period/:projectId/:labelCode/:frequency
Progreso por período
POST (9 endpoints)
Path
Descripción
POST /labels/labelsRecursive
Recorrer etiquetas recursivamente
POST /labels/labels
Listar etiquetas con filtros
POST /labels/labelIntersect
Cruce de etiquetas (filtro AND/OR)
POST /labels/groups
Crear grupo de etiquetas
POST /labels
Crear etiqueta
POST /labels/block-weights/by-codes
Pesos de bloques por código
POST /labels/calculate-compression-factors
Calcular factores de compresión
POST /get-progress/by-label
Obtener progreso por etiqueta
POST /get-advance-data/by-label
Datos de avance
POST /labels/validate-xlsx
Validar archivo XLSX importado
PUT (24 endpoints)
Path
Descripción
PUT /labels/assign-to-dashboard
Asignar etiquetas al dashboard
PUT /labels/update-dates
Actualizar fechas de bloques en etiqueta
PUT /labels/update-weights-by-duration
Calcular pesos proporcionales a duración
PUT /labels/update-weights-to-default
Resetear pesos igualitarios
PUT /labels/set-weights/by-codes
Pesos manuales por código de bloque
PUT /labels/set-weights/by-description
Pesos por descripción de bloque
PUT /labels/set-weights/by-label-and-description
Pesos combinados
PUT /labels/set-weights/by-label-and-code
Pesos combinados por label y código
PUT /labels/average-weighting/by-label
Ponderación promedio por etiqueta
PUT /labels/assign-all-blocks-to-general
Asignar todos los bloques a la etiqueta general
PUT /labels/fix-zero-weights
Corregir bloques con peso = 0
PUT /calculate-fixed-weights
Calcular pesos fijos
PUT /labels/set-executed-blocks/all-labels
Marcar bloques ejecutados en todas las etiquetas
PUT /labels/set-weights/according-fixed-value
Pesos según valor fijo predefinido
PUT /labels/aux-50/set-weights/prev-report
Pesos del reporte anterior (AUX-50)
PUT /labels/aux-50/advance-by-week
Avance semanal AUX-50
PUT /labels/aux-50/set-weights/by-week
Pesos por semana AUX-50
PUT /labels/aux-50/set-fixed-weights/executed-and-past-blocks
Pesos fijos para bloques ejecutados y pasados
PUT /labels/aux-50/set-exceptions
Excepciones en cálculo AUX-50
PUT /labels/graph-calculation
Calcular gráficos (V1)
PUT /labels/graph-calculation-v2
Calcular gráficos (V2 mejorado)
PUT /graph-values/all-projects
Actualizar gráficos de todos los proyectos
PUT /graph-values/fix-freezed-past
Corregir congelación de pasado
PUT /calculate-costs-by-dates
Calcular costos por fechas
PUT /fixed-weights
Actualizar pesos fijos
DELETE (4 endpoints)
Path
Descripción
DELETE /labels/blocks-by-description
Eliminar bloques de etiqueta por descripción
DELETE /labels/blocks-by-code
Eliminar bloques de etiqueta por código
DELETE /fixed-weights
Eliminar pesos fijos
DELETE /labels/block-dates
Eliminar fechas de bloques
Base de Datos
Motor: MongoDB
Conexión: Pool dinámico multi-proyecto + bases especiales (manager, managerv2)
Colecciones Usadas
Colección
Base de Datos
Descripción
labels
{projectId}
Definición jerárquica de etiquetas
labelGroups
{projectId}
Grupos de etiquetas
plan_records
{projectId}
Historial de planificación ejecutada
plan_freezing_past
{projectId}
Planificación congelada del pasado
compressions
{projectId}
Factores de compresión históricos
exceptions
{projectId}
Excepciones en cálculos
blockIfc
{projectId}
Referencia a bloques (lectura)
costs
{projectId}
Datos de costo planificado
Variables de Entorno
Variable
Descripción
ENVIRONMENT
Ambiente: dev, qa, prod
{ENV}_PORT
Puerto HTTP (:8102)
{ENV}_API_URL
URL de la API
{ENV}_MEDIA_URL
URL del servicio media
{ENV}_DB_USER
Usuario MongoDB
{ENV}_DB_PASSWORD
Contraseña MongoDB (sensible)
{ENV}_DB_HOST
Host MongoDB
{ENV}_DB_PORT
Puerto MongoDB
{ENV}_OWNER_EMAIL
Email de notificaciones de error
Dependencias Externas
Servicio
Llamada
Propósito
lblsref
PUT /labels-calculation
Propagar cambios de pesos
media
lectura
Obtener URLs de documentos
SMTP (gmail)
email
Notificaciones de error a administradores
Procesos Internos Especiales
Worker Pool
Máximo: 3 procesos concurrentes para operaciones pesadas
Requisito: 350MB de RAM libre antes de ejecutar
Operaciones controladas: cálculo de compresiones, graph-calculation, actualización masiva de pesos
Propósito: Evitar saturación del servidor con cálculos intensivos
Notificaciones por Email
Envía emails SMTP cuando ocurren errores en cálculo de pesos
Destinatarios: administradores del sistema (configurados en {ENV}_OWNER_EMAIL)
Librería: gopkg.in/gomail.v2
Conceptos de Negocio Clave
Congelación del Pasado (Freezing Past)
Mecanismo que fija los valores históricos de planificación para evitar revisión retroactiva. Los datos pasados se almacenan en plan_freezing_past y no se modifican en cálculos futuros. Existe en versión V1 (original) y V2 (mejorada).
Factores de Compresión
Al detectar desviación entre lo planificado y lo ejecutado, se calcula un factor multiplicativo: