Grafica 4.5 - Analisis de productos quimicos

Descripción General

Este endpoint proporciona información sobre el costo monetario de las preparaciones de productos químicos en una planta de tratamiento. La respuesta incluye tres secciones principales: un mapa de calor que muestra costos por día y por producto, indicadores clave de desempeño con resumen del mes en términos monetarios, y una gráfica de evolución que muestra tendencias de costos de los últimos 3 meses.

Nota importante: A partir de enero 2026, el endpoint utiliza datos de preparaciones de químicos (ChemicalPreparation) en lugar de dosificaciones (BalanceHistory), y todos los valores representan costos monetarios en lugar de cantidades físicas (litros/gramos).

Endpoint

GET /api/v1/dashboard/chemical-analysis/:treatmentPlantId

Parámetros Requeridos

Parámetros de URL

treatmentPlantId (string): ID de la planta de tratamiento

Query Parameters

month (string, requerido): Número del mes (1-12). Ejemplo: "12" para diciembre
year (string, requerido): Año en formato numérico. Ejemplo: "2025"

Ejemplo de Petición

GET /api/v1/dashboard/chemical-analysis/507f1f77bcf86cd799439011?month=12&year=2025

Fuente de Datos

Actualización (Enero 2026): El endpoint ahora utiliza preparaciones de químicos (ChemicalPreparation) en lugar de dosificaciones (BalanceHistory). Todos los valores representan costos monetarios (totalCost) en lugar de cantidades físicas.

Cambios Principales:

Antes: Usaba BalanceHistory con cantidadDosificada (litros/gramos)
Ahora: Usa ChemicalPreparation con totalCost (costo monetario)
Beneficio: Muestra el gasto real en dinero, permitiendo análisis financiero más preciso

Estructura de la Respuesta

La respuesta tiene la siguiente estructura:

json

{
  "msg": "Gráfica 4.5 - Análisis de productos quimicos",
  "data": {
    "heatmap": [...],
    "summary": {...},
    "evolution": [...]
  }
}

Importante: Todos los valores de totalConsumption en las tres secciones representan dinero (costo monetario), no cantidades físicas.

SECCIÓN A: Mapa de Calor (Heatmap)

Descripción

El mapa de calor agrupa los costos monetarios de las preparaciones de productos químicos por día y por producto, organizándolos por semana del mes y día de la semana. Esto permite visualizar patrones de gasto a lo largo del mes.

Cómo Funciona

Toma todas las preparaciones de químicos (ChemicalPreparation) del mes seleccionado con status: 'PREPARED'
Para cada preparación, calcula:
- La semana del mes (1 a 5, donde 1 es la primera semana)
- El día de la semana (Lun, Mar, Mié, Jue, Vie, Sáb, Dom)
- El día del mes (1 a 31)
Agrupa las preparaciones que pertenecen al mismo día Y mismo producto usando una clave única (semana-día-producto)
Suma todos los totalCost de las preparaciones del mismo producto en ese día
Ordena los resultados primero por semana y luego por día de la semana

Estructura de Datos

Cada elemento del array heatmap contiene:

week: Número de semana del mes (1-5)
dayOfWeek: Nombre del día de la semana (Lun, Mar, Mié, Jue, Vie, Sáb, Dom)
dayOfMonth: Día del mes (1-31)
totalConsumption: Suma total de costos monetarios de todas las preparaciones de ese producto en ese día (número exacto, sin redondeo)
chemicalName: Nombre del producto químico
date: Fecha en formato YYYY-MM-DD

Importante: Cada producto químico tiene su propio registro por día. Si el mismo día hay preparaciones de múltiples productos, aparecerán múltiples registros (uno por producto).

Ejemplo de Datos

json

{
  "heatmap": [
    {
      "week": 4,
      "dayOfWeek": "Mar",
      "dayOfMonth": 20,
      "totalConsumption": 417600,
      "chemicalName": "GENERICO C",
      "date": "2026-01-20"
    },
    {
      "week": 4,
      "dayOfWeek": "Mar",
      "dayOfMonth": 20,
      "totalConsumption": 78078,
      "chemicalName": "GENERICO A",
      "date": "2026-01-20"
    },
    {
      "week": 4,
      "dayOfWeek": "Mar",
      "dayOfMonth": 20,
      "totalConsumption": 112500,
      "chemicalName": "GENERICO B",
      "date": "2026-01-20"
    }
  ]
}

Notas para el Frontend

Los datos ya vienen ordenados por semana y día de la semana
Puedes usar week y dayOfWeek para organizar visualmente el mapa de calor
El totalConsumption representa dinero (costo monetario), no cantidad física
Cada producto tiene su propio registro por día, permitiendo visualizar el costo de cada producto por separado
Si un día tiene múltiples productos, habrá múltiples registros para ese día (uno por producto)

SECCIÓN B: KPIs - Resumen de Consumos (Monetario)

Descripción

Esta sección proporciona indicadores clave de desempeño: el costo total del mes y un desglose detallado por cada producto químico en términos monetarios.

Cómo Funciona

Recorre todas las preparaciones de químicos (ChemicalPreparation) del mes con status: 'PREPARED'
Filtra solo las preparaciones con totalCost válido (número >= 0)
Suma todos los totalCost para obtener el costo total del mes
Agrupa las preparaciones por producto químico
Para cada producto, calcula:
- El costo total (suma de todos los totalCost de las preparaciones de ese producto)
- La cantidad física preparada (massConsumed: suma de quantityToPrepare)
- La unidad de medida (L para litros, G para gramos)

Estructura de Datos

El objeto summary contiene:

totalConsumptionMonth: Suma total de todos los costos monetarios del mes (número exacto)
productsBreakdown: Array con el desglose por producto

Cada elemento de productsBreakdown contiene:

productName: Nombre del producto químico
totalConsumption: Costo monetario total del producto en el mes (suma de totalCost)
massConsumed: Cantidad física preparada (suma de quantityToPrepare)
units: Unidad de medida (L, G, o noUnits)

Ejemplo de Datos

json

{
  "summary": {
    "totalConsumptionMonth": 608178,
    "productsBreakdown": [
      {
        "productName": "GENERICO C",
        "totalConsumption": 417600,
        "massConsumed": 144,
        "units": "L"
      },
      {
        "productName": "GENERICO A",
        "totalConsumption": 78078,
        "massConsumed": 50,
        "units": "L"
      },
      {
        "productName": "GENERICO B",
        "totalConsumption": 112500,
        "massConsumed": 75,
        "units": "L"
      }
    ]
  }
}

Notas para el Frontend

totalConsumptionMonth representa el gasto total en dinero del mes
totalConsumption por producto representa el costo monetario de ese producto
massConsumed representa la cantidad física preparada (opcional, por sugerencia del director técnico)
Puedes mostrar totalConsumptionMonth como un indicador principal de gasto
productsBreakdown es útil para gráficas de pastel o barras mostrando la distribución de costos por producto
Los valores son exactos, sin redondeo, así que puedes formatearlos según necesites

SECCIÓN C: Evolución por Producto (Monetario)

Descripción

Esta sección muestra la evolución del costo monetario de cada producto químico durante los últimos 3 meses, incluyendo el mes actual. Es útil para identificar tendencias y patrones de gasto a lo largo del tiempo.

Cómo Funciona

Calcula los últimos 3 meses a partir del mes seleccionado:
- Mes actual (el mes que se envió en los parámetros)
- Mes anterior (mes actual - 1)
- Mes anterior al anterior (mes actual - 2)
Para cada uno de estos 3 meses, obtiene todas las preparaciones de químicos (ChemicalPreparation) con status: 'PREPARED'
Filtra solo las preparaciones con totalCost válido (número >= 0)
Agrupa las preparaciones por producto químico y por mes
Suma los totalCost de todas las preparaciones del mismo producto en cada mes
Asigna un color predefinido a cada producto (si está definido, sino usa gris)
Ordena los datos por año y mes en orden ascendente

Estructura de Datos

El array evolution contiene un objeto por cada producto químico que tuvo preparaciones en alguno de los 3 meses.

Cada elemento contiene:

productName: Nombre del producto químico
color: Color hexadecimal para representar el producto en la gráfica
data: Array con los costos por mes, ordenados cronológicamente

Cada elemento del array data contiene:

month: Mes en formato MM/YYYY (ejemplo: "11/2025")
totalConsumption: Costo monetario total del producto en ese mes (suma de todos los totalCost)

Colores Predefinidos

Los siguientes productos tienen colores asignados:

Cloro: Azul (#0000FF)
pH-: Verde (#00FF00)
pH+: Rojo (#FF0000)
Otros productos: Gris (#808080)

Ejemplo de Datos

json

{
  "evolution": [
    {
      "productName": "GENERICO C",
      "color": "#808080",
      "data": [
        {
          "month": "11/2025",
          "totalConsumption": 100000
        },
        {
          "month": "12/2025",
          "totalConsumption": 250000
        },
        {
          "month": "01/2026",
          "totalConsumption": 417600
        }
      ]
    },
    {
      "productName": "GENERICO A",
      "color": "#808080",
      "data": [
        {
          "month": "11/2025",
          "totalConsumption": 50000
        },
        {
          "month": "01/2026",
          "totalConsumption": 78078
        }
      ]
    }
  ]
}

Notas para el Frontend

Cada producto tiene su propio array de datos, que puede tener 1, 2 o 3 elementos (dependiendo de en cuántos meses tuvo preparaciones)
Los datos ya vienen ordenados cronológicamente (mes más antiguo primero)
Puedes usar el color proporcionado para las líneas o barras de la gráfica
Si un producto no aparece en un mes, significa que no tuvo preparaciones ese mes (no incluye meses con costo cero)
El totalConsumption representa dinero (costo monetario), no cantidad física

Filtros Aplicados

El endpoint aplica los siguientes filtros automáticamente:

Por Planta: Solo incluye preparaciones de la planta especificada en treatmentPlantId
Por Estado: Solo incluye preparaciones con status: 'PREPARED' (preparaciones completadas)
Por Costo Válido: Solo procesa preparaciones con totalCost válido (número >= 0). Las preparaciones sin totalCost o con valores inválidos se ignoran sin generar errores
Por Rango de Fechas:
- Para el mapa de calor y KPIs: Solo el mes seleccionado (basado en preparedAt)
- Para la evolución: Los últimos 3 meses (incluyendo el mes actual), basado en preparedAt

Manejo de Errores

Error 400 - Parámetros Inválidos

json

{
  "msg": "Mes y año son requeridos"
}

json

{
  "msg": "Mes debe ser entre 1 y 12"
}

Error 404 - Planta No Encontrada

json

{
  "msg": "No existe una planta de tratamiento con id [ID]"
}

Error 500 - Error Interno

json

{
  "msg": "Error interno del servidor"
}

Casos Especiales

Sin Datos

Si no hay preparaciones con totalCost válido en el mes seleccionado, la respuesta será:

json

{
  "msg": "Analisis de productos quimicos",
  "data": {
    "heatmap": [],
    "summary": {
      "totalConsumptionMonth": 0,
      "productsBreakdown": []
    },
    "evolution": []
  }
}

Nota: Las preparaciones antiguas (creadas antes de implementar el campo totalCost) se ignoran automáticamente y no generan errores.

Precisión de Números

Todos los valores numéricos se calculan usando Decimal.js para mantener precisión exacta. No se aplica redondeo automático, por lo que el frontend puede decidir cómo formatear los números según sus necesidades.

Integración Frontend - Pasos Recomendados

Obtener los datos: Realiza la petición GET con el ID de la planta, mes y año
Validar la respuesta: Verifica que data existe y tiene las tres secciones
Renderizar el mapa de calor: Usa el array heatmap para crear una visualización tipo calendario. Nota: Cada producto tiene su propio registro por día, permitiendo visualizar el costo de cada producto por separado
Mostrar los KPIs: Usa summary.totalConsumptionMonth (gasto total en dinero) y summary.productsBreakdown para indicadores y gráficas. Importante: Formatea los valores como moneda (ej: $608,178.00)
Crear la gráfica de evolución: Usa el array evolution para una gráfica de líneas o barras, usando los colores proporcionados. Los valores representan costos monetarios por mes
Manejar casos vacíos: Si algún array está vacío, muestra un mensaje apropiado al usuario
Formatear valores monetarios: Todos los valores de totalConsumption deben formatearse como moneda (no como cantidades físicas)

Grafica 4.5 - Analisis de productos quimicos ​

Descripción General ​

Endpoint ​

Parámetros Requeridos ​

Parámetros de URL ​

Query Parameters ​

Ejemplo de Petición ​

Fuente de Datos ​

Cambios Principales: ​

Estructura de la Respuesta ​

SECCIÓN A: Mapa de Calor (Heatmap) ​

Descripción ​

Cómo Funciona ​

Estructura de Datos ​

Ejemplo de Datos ​

Notas para el Frontend ​

SECCIÓN B: KPIs - Resumen de Consumos (Monetario) ​

Descripción ​

Cómo Funciona ​

Estructura de Datos ​

Ejemplo de Datos ​

Notas para el Frontend ​

SECCIÓN C: Evolución por Producto (Monetario) ​

Descripción ​

Cómo Funciona ​

Estructura de Datos ​

Colores Predefinidos ​

Ejemplo de Datos ​

Notas para el Frontend ​

Filtros Aplicados ​

Manejo de Errores ​

Error 400 - Parámetros Inválidos ​

Error 404 - Planta No Encontrada ​

Error 500 - Error Interno ​

Casos Especiales ​

Sin Datos ​

Precisión de Números ​

Integración Frontend - Pasos Recomendados ​

Grafica 4.5 - Analisis de productos quimicos

Descripción General

Endpoint

Parámetros Requeridos

Parámetros de URL

Query Parameters

Ejemplo de Petición

Fuente de Datos

Cambios Principales:

Estructura de la Respuesta

SECCIÓN A: Mapa de Calor (Heatmap)

Descripción

Cómo Funciona

Estructura de Datos

Ejemplo de Datos

Notas para el Frontend

SECCIÓN B: KPIs - Resumen de Consumos (Monetario)

Descripción

Cómo Funciona

Estructura de Datos

Ejemplo de Datos

Notas para el Frontend

SECCIÓN C: Evolución por Producto (Monetario)

Descripción

Cómo Funciona

Estructura de Datos

Colores Predefinidos

Ejemplo de Datos

Notas para el Frontend

Filtros Aplicados

Manejo de Errores

Error 400 - Parámetros Inválidos

Error 404 - Planta No Encontrada

Error 500 - Error Interno

Casos Especiales

Sin Datos

Precisión de Números

Integración Frontend - Pasos Recomendados