8.1. Team Metrics API

Описание API

Team Metrics API предоставляет данные о метриках команд и отделов в компании. Этот API используется для отображения показателей производительности, вовлеченности и других метрик на дашборде и в аналитических отчетах.

Endpoint информация

Принцип работы

API Team Metrics работает по следующему принципу:

1. Аутентификация - проверка company_token для идентификации компании
2. Валидация параметров - проверка корректности переданных параметров (период и метрика)
3. Выборка данных - запрос к базе данных PostgreSQL для получения метрик команд
4. Агрегация данных - расчет средних значений по метрикам для каждого отдела
5. Расчет изменений - вычисление абсолютных и относительных изменений метрик
6. Форматирование ответа - подготовка данных в требуемом формате

Схема процесса в n8n

В n8n API реализовано как рабочий процесс со следующими основными шагами:

1. HTTP Trigger - точка входа, принимающая HTTP-запрос
2. Function Node - валидация параметров и токена
3. PostgreSQL - запрос к базе данных для получения метрик по отделам
4. Function Node - обработка результатов и расчет средних значений
5. PostgreSQL - запрос для получения предыдущих значений метрик
6. Function Node - расчет изменений метрик
7. Set - форматирование финального ответа
8. Respond to Webhook - отправка ответа клиенту

Формат ответа

[
  {
    "departmentId": 3,
    "metrics": {
      "wellness": 6.4,
      "happiness": 8.1,
      "alignment": 6.9,
      "relationship_with_peers": 7.3,
      "relationship_with_manager": 7.4,
      "feedback": 6.7,
      "personal_growth": 8.3,
      "recognition": 7,
      "satisfaction": 7.1,
      "ambassadorship": 7.2
    },
    "engagement_score": 7.2,
    "absolute_changes_by_metric": {
      "wellness": -0.5,
      "happiness": -0.3,
      "alignment": -0.5,
      "relationship_with_peers": -0.3,
      "relationship_with_manager": -0.4,
      "feedback": -0.4,
      "personal_growth": 0,
      "recognition": -0.5,
      "satisfaction": -0.4,
      "ambassadorship": -0.6,
      "engagement_score": -0.4
    },
    "name": "Тестовый отдел"
  },
  // Другие отделы
]
                    

Алгоритм расчета метрик

API использует следующий алгоритм для расчета метрик команд:

1. Сбор данных - получение всех ответов на опросы от сотрудников отдела за указанный период
2. Группировка по метрикам - группировка ответов по соответствующим метрикам
3. Расчет средних значений - вычисление среднего значения для каждой метрики
4. Расчет общего показателя вовлеченности - вычисление общего значения на основе всех метрик
5. Сравнение с предыдущим периодом - расчет изменений по сравнению с предыдущим аналогичным периодом

Особенности и примечания

• API поддерживает фильтрацию по конкретной метрике с помощью параметра paramNameMetric
• Значения метрик нормализуются в диапазоне от 0 до 10
• Расчет абсолютных изменений производится как разница между текущим и предыдущим значением
• API оптимизирован для быстрой работы даже с большими объемами данных
• Результаты кэшируются для повышения производительности при частых запросах

Интеграция с фронтендом

Данный API используется на фронтенде для следующих компонентов:

• Дашборд с показателями метрик команд
• Карточки команд с основными метриками
• Графики изменения метрик во времени
• Тепловые карты метрик по отделам

Пример использования API на фронтенде:

// Пример функции для получения метрик команд
async function getTeamMetrics(period = '3m', metricName = null) {
  const params = new URLSearchParams();
  
  if (period) {
    params.append('curdate', period);
  }
  
  if (metricName) {
    params.append('paramNameMetric', metricName);
  }
  
  const url = `https://api.hroom.ai/webhook/teams/metric/get?${params.toString()}`;
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${localStorage.getItem('companyToken')}`,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
}