Формула настраиваемого поля

Создайте вычисляемые поля, которые автоматически вычисляют значения на основе других данных

Формулы настраиваемых полей используются для расчетов в диаграммах и панелях инструментов в Blue. Они определяют функции агрегации (СУММ, СРЗНАЧ, СЧЕТ, и т.д.), которые работают с данными настраиваемых полей для отображения вычисленных метрик в диаграммах. Формулы не вычисляются на уровне отдельных задач, а агрегируют данные из нескольких записей для целей визуализации.

Простой пример

Создайте формульное поле для расчетов в диаграммах:

mutation CreateFormulaField {
  createCustomField(input: {
    name: "Budget Total"
    type: FORMULA
    projectId: "proj_123"
    formula: {
      logic: {
        text: "SUM(Budget)"
        html: "<span>SUM(Budget)</span>"
      }
      display: {
        type: NUMBER
        precision: 2
        function: SUM
      }
    }
  }) {
    id
    name
    type
    formula
  }
}

Расширенный пример

Создайте валютную формулу с сложными расчетами:

mutation CreateCurrencyFormula {
  createCustomField(input: {
    name: "Profit Margin"
    type: FORMULA
    projectId: "proj_123"
    formula: {
      logic: {
        text: "SUM(Revenue) - SUM(Costs)"
        html: "<span>SUM(Revenue) - SUM(Costs)</span>"
      }
      display: {
        type: CURRENCY
        currency: {
          code: "USD"
          name: "US Dollar"
        }
        precision: 2
      }
    }
    description: "Automatically calculates profit by subtracting costs from revenue"
  }) {
    id
    name
    type
    formula
  }
}

Входные параметры

CreateCustomFieldInput

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя формульного поля
`type`	CustomFieldType!	✅ Да	Должно быть `FORMULA`
`projectId`	String!	✅ Да	Идентификатор проекта, в котором будет создано это поле
`formula`	JSON	Нет	Определение формулы для расчетов в диаграммах
`description`	String	Нет	Текст помощи, отображаемый пользователям

Структура формулы

{
  "logic": {
    "text": "Display text for the formula",
    "html": "HTML formatted display text"
  },
  "display": {
    "type": "NUMBER|CURRENCY|PERCENTAGE",
    "currency": {
      "code": "USD",
      "name": "US Dollar"  
    },
    "precision": 2,
    "function": "SUM|AVERAGE|AVERAGEA|COUNT|COUNTA|MAX|MIN"
  }
}

Поддерживаемые функции

Функции агрегации диаграмм

Формульные поля поддерживают следующие функции агрегации для расчетов в диаграммах:

Функция	Описание	ChartFunction Enum
`SUM`	Сумма всех значений	`SUM`
`AVERAGE`	Среднее значение числовых значений	`AVERAGE`
`AVERAGEA`	Среднее значение без нулей и пустых значений	`AVERAGEA`
`COUNT`	Количество значений	`COUNT`
`COUNTA`	Количество без нулей и пустых значений	`COUNTA`
`MAX`	Максимальное значение	`MAX`
`MIN`	Минимальное значение	`MIN`

Примечание: Эти функции используются в поле display.function и работают с агрегированными данными для визуализаций диаграмм. Сложные математические выражения или расчеты на уровне полей не поддерживаются.

Типы отображения

Отображение числа

{
  "display": {
    "type": "NUMBER",
    "precision": 2
  }
}

Результат: 1250.75

Отображение валюты

{
  "display": {
    "type": "CURRENCY",
    "currency": {
      "code": "USD",
      "name": "US Dollar"
    },
    "precision": 2
  }
}

Результат: $1,250.75

Отображение процента

{
  "display": {
    "type": "PERCENTAGE",
    "precision": 1
  }
}

Результат: 87.5%

Редактирование формульных полей

Обновите существующие формульные поля:

mutation EditFormulaField {
  editCustomField(input: {
    customFieldId: "field_456"
    formula: {
      logic: {
        text: "AVERAGE(Score)"
        html: "<span>AVERAGE(Score)</span>"
      }
      display: {
        type: PERCENTAGE
        precision: 1
      }
    }
  }) {
    id
    formula
  }
}

Обработка формул

Контекст расчета диаграммы

Формульные поля обрабатываются в контексте сегментов диаграмм и панелей инструментов:

Расчеты происходят при рендеринге или обновлении диаграмм
Результаты хранятся в ChartSegment.formulaResult как десятичные значения
Обработка осуществляется через выделенную очередь BullMQ с именем 'formula'
Обновления публикуются подписчикам панели инструментов для обновлений в реальном времени

Форматирование отображения

Функция getFormulaDisplayValue форматирует вычисленные результаты в зависимости от типа отображения:

NUMBER: Отображается как простое число с опциональной точностью
PERCENTAGE: Добавляет суффикс % с опциональной точностью
CURRENCY: Форматирует с использованием указанного кода валюты

Хранение результатов формул

Результаты хранятся в поле formulaResult:

{
  "number": 1250.75,
  "formulaResult": {
    "number": 1250.75,
    "display": {
      "type": "CURRENCY",
      "currency": {
        "code": "USD",
        "name": "US Dollar"
      },
      "precision": 2
    }
  }
}

Поля ответа

Ответ TodoCustomField

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для значения поля
`customField`	CustomField!	Определение формульного поля
`number`	Float	Вычисленный числовой результат
`formulaResult`	JSON	Полный результат с форматированием отображения
`todo`	Todo!	Запись, к которой принадлежит это значение
`createdAt`	DateTime!	Когда было создано значение
`updatedAt`	DateTime!	Когда значение было в последний раз вычислено

Контекст данных

Источник данных диаграммы

Формульные поля работают в контексте источника данных диаграммы:

Формулы агрегируют значения настраиваемых полей по задачам в проекте
Функция агрегации, указанная в display.function, определяет расчет
Результаты вычисляются с использованием SQL-функций агрегации (avg, sum, count и т.д.)
Расчеты выполняются на уровне базы данных для повышения эффективности

Общие примеры формул

Общий бюджет (отображение диаграммы)

{
  "logic": {
    "text": "Total Budget",
    "html": "<span>Total Budget</span>"
  },
  "display": {
    "type": "CURRENCY",
    "currency": { "code": "USD", "name": "US Dollar" },
    "precision": 2,
    "function": "SUM"
  }
}

Средний балл (отображение диаграммы)

{
  "logic": {
    "text": "Average Quality Score",
    "html": "<span>Average Quality Score</span>"
  },
  "display": {
    "type": "NUMBER",
    "precision": 1,
    "function": "AVERAGE"
  }
}

Количество задач (отображение диаграммы)

{
  "logic": {
    "text": "Total Tasks",
    "html": "<span>Total Tasks</span>"
  },
  "display": {
    "type": "NUMBER",
    "precision": 0,
    "function": "COUNT"
  }
}

Необходимые разрешения

Операции с настраиваемыми полями следуют стандартным разрешениям на основе ролей:

Действие	Необходимая роль
Create formula field	Project member with appropriate role
Update formula field	Project member with appropriate role
View formula results	Project member with view permissions
Delete formula field	Project member with appropriate role

Примечание: Конкретные необходимые роли зависят от конфигурации пользовательских ролей вашего проекта. Нет специальных констант разрешений, таких как CUSTOM_FIELDS_CREATE.

Обработка ошибок

Ошибка валидации

{
  "errors": [{
    "message": "Validation error message",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Настраиваемое поле не найдено

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Общие случаи использования

Финансовый учет
- Расчеты бюджета
- Отчеты о прибыли/убытках
- Анализ затрат
- Прогнозирование доходов
Управление проектом
- Проценты завершения
- Использование ресурсов
- Расчеты временных рамок
- Метрики производительности
Контроль качества
- Средние баллы
- Процент успешных/неуспешных результатов
- Метрики качества
- Отслеживание соблюдения
Бизнес-аналитика
- Расчеты KPI
- Анализ тенденций
- Сравнительные метрики
- Значения на панели инструментов

Ограничения

Формулы предназначены только для агрегаций диаграмм/панелей инструментов, а не для расчетов на уровне задач
Ограничены семью поддерживаемыми функциями агрегации (СУММ, СРЗНАЧ и т.д.)
Нет сложных математических выражений или расчетов между полями
Нельзя ссылаться на несколько полей в одной формуле
Результаты видны только в диаграммах и панелях инструментов
Поле logic предназначено только для отображаемого текста, а не для фактической логики расчета

Связанные ресурсы

Числовые поля - Для статических числовых значений
Валютные поля - Для денежных значений
Ссылочные поля - Для данных между проектами
Поля поиска - Для агрегированных данных
Обзор настраиваемых полей - Общие концепции