---
title: "Метрики"
description: "Создание бизнес-метрик Frame — число, временной график, столбцы и распределение по категориям"
canonical_url: "https://frame.qubeek.io/ru/developers/functions/metrics"
---
# Метрики

> Создание бизнес-метрик Frame — число, временной график, столбцы и распределение по категориям

Метрики показывают бизнес-показатели на [информационной панели](https://frame.qubeek.io/ru/developers/resources/dashboards): выручку, число заказов, динамику регистраций, распределение по статусам. Каждая метрика — PHP-класс с `calculate(FrameRequest $request)`. Это не сбор инфраструктурных метрик Prometheus.

## Выберите тип

Базовые классы находятся в пространстве имён `Frame\LaravelMetrics`, DTO — в `Frame\LaravelMetrics\DTO`.

<table>
<thead>
  <tr>
    <th>
      Базовый класс
    </th>
    
    <th>
      Результат <code>
        calculate()
      </code>
    </th>
    
    <th>
      Применение
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ValueMetric
      </code>
    </td>
    
    <td>
      <code>
        StatValue
      </code>
    </td>
    
    <td>
      Одно число и сравнение с предыдущим периодом
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LineChartMetric
      </code>
    </td>
    
    <td>
      <code>
        LineChart
      </code>
    </td>
    
    <td>
      Временной ряд с заполнением пропусков нулями
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BarChartMetric
      </code>
    </td>
    
    <td>
      <code>
        BarChart
      </code>
    </td>
    
    <td>
      Столбцы по времени; сервер также умеет группировать категории
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PieChartMetric
      </code>
    </td>
    
    <td>
      <code>
        PieChart
      </code>
    </td>
    
    <td>
      Распределение по категориям
    </td>
  </tr>
</tbody>
</table>

В проверенных исходниках зарегистрированных Artisan-команд и стабов нет генератора `frame:metric`. Создайте класс вручную. Команда `frame:dashboard` создаёт дашборд, а не метрику.

## Создайте классы

Ниже — иллюстративные примеры для приложения с моделью `App\Models\Order`, числовой колонкой `total`, строковой `status` и датой `created_at`. Замените модель и поля своей схемой. Примеры сверены с сигнатурами исходников, но не запускались в приложении.

### ValueMetric: выручка

Хелпер `sum()` возвращает `float`, а не DTO. Передайте его результат в `StatValue::createCurrency()`. Предыдущее значение хелпер сохраняет в экземпляре метрики; передайте его в DTO самостоятельно.

```php [app/Frame/Metrics/RevenueMetric.php]
<?php

declare(strict_types=1);

namespace App\Frame\Metrics;

use App\Models\Order;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\LaravelMetrics\DTO\StatValue;
use Frame\LaravelMetrics\ValueMetric;

final class RevenueMetric extends ValueMetric
{
    public function calculate(FrameRequest $request): StatValue
    {
        $value = $this->sum(
            $request,
            Order::query()->where('status', 'paid'),
            'total',
            'created_at',
        );

        return StatValue::createCurrency(
            $this->label,
            $value,
            $this->getPreviousValue(),
            'RUB',
            2,
        );
    }
}
```

### LineChartMetric: заказы по дням

Третий аргумент `count()` — `TimeUnit`, четвёртый — считаемая колонка, пятый — колонка даты. Передача `'created_at'` третьим позиционным аргументом ошибочна.

```php [app/Frame/Metrics/OrdersByDayMetric.php]
<?php

declare(strict_types=1);

namespace App\Frame\Metrics;

use App\Models\Order;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\LaravelMetrics\DTO\LineChart;
use Frame\LaravelMetrics\Enums\TimeUnit;
use Frame\LaravelMetrics\LineChartMetric;

final class OrdersByDayMetric extends LineChartMetric
{
    public function calculate(FrameRequest $request): LineChart
    {
        return $this->count(
            $request,
            Order::query(),
            TimeUnit::DAY,
            'id',
            'created_at',
        );
    }
}
```

### BarChartMetric: столбцы по дням

Для встроенного Vue BarChart используйте временные категории: его рендерер разбирает `category` как ISO-дату и сортирует по времени.

```php [app/Frame/Metrics/OrdersByDayBarsMetric.php]
<?php

declare(strict_types=1);

namespace App\Frame\Metrics;

use App\Models\Order;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\LaravelMetrics\BarChartMetric;
use Frame\LaravelMetrics\DTO\BarChart;
use Frame\LaravelMetrics\Enums\TimeUnit;

final class OrdersByDayBarsMetric extends BarChartMetric
{
    public function calculate(FrameRequest $request): BarChart
    {
        return $this->count(
            $request,
            Order::query(),
            TimeUnit::DAY,
            'id',
            'created_at',
        );
    }
}
```

### PieChartMetric: статусы заказов

У Pie-хелперов нет автоматической фильтрации по периоду. Если она нужна, получите границы через `getDateRanges()` и добавьте `whereBetween()` в свой запрос, как в примере.

```php [app/Frame/Metrics/OrdersByStatusMetric.php]
<?php

declare(strict_types=1);

namespace App\Frame\Metrics;

use App\Models\Order;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\LaravelMetrics\DTO\PieChart;
use Frame\LaravelMetrics\PieChartMetric;

final class OrdersByStatusMetric extends PieChartMetric
{
    public function calculate(FrameRequest $request): PieChart
    {
        [$currentRange] = $this->getDateRanges($request);
        $query = Order::query()->whereBetween('created_at', $currentRange);

        return $this->countByCategory(
            $request,
            $query,
            'status',
            limit: 10,
            sortDirection: 'desc',
        );
    }
}
```

## Подключите к Dashboard

Верните экземпляры метрик из `Dashboard::cards()`. Отдельного реестра PHP-метрик нет: `Dashboard::metrics()` собирает их из карточек, включая вложенные `Group`.

```php [app/Frame/Dashboards/SalesDashboard.php]
<?php

declare(strict_types=1);

namespace App\Frame\Dashboards;

use App\Frame\Metrics\OrdersByDayBarsMetric;
use App\Frame\Metrics\OrdersByDayMetric;
use App\Frame\Metrics\OrdersByStatusMetric;
use App\Frame\Metrics\RevenueMetric;
use Frame\Core\Dashboards\Dashboard;
use Frame\Laravel\Http\Requests\FrameRequest;

final class SalesDashboard extends Dashboard
{
    public static function cards(FrameRequest $request): array
    {
        return [
            RevenueMetric::make('Выручка')->withRange(30),
            OrdersByDayMetric::make('Заказы по дням')->withRange(30),
            OrdersByDayBarsMetric::make('Заказы: столбцы')->withRange(30),
            OrdersByStatusMetric::make('Статусы заказов')->withRange(30),
        ];
    }

    public static function title(): string
    {
        return 'Продажи';
    }
}
```

Добавьте дашборд в существующий callback `DashboardManager::buildUsing()` вашего `FrameServiceProvider::boot()`. Повторный вызов `buildUsing()` заменяет callback, поэтому не регистрируйте им каждый дашборд отдельно и не удаляйте уже подключённые классы.

Для нового провайдера минимальный пример такой. Существующий провайдер целиком не заменяйте: сохраните его настройки, регистрации и правила доступа.

```php [app/Providers/FrameServiceProvider.php]
<?php

declare(strict_types=1);

namespace App\Providers;

use App\Frame\Dashboards\SalesDashboard;
use Frame\Core\Dashboards\DashboardManager;
use Frame\Core\Dashboards\Dashboards;
use Frame\Laravel\FrameApplicationServiceProvider;

class FrameServiceProvider extends FrameApplicationServiceProvider
{
    public function boot(): void
    {
        parent::boot();

        app(DashboardManager::class)->buildUsing(
            fn (Dashboards $dashboards) => $dashboards->push(SalesDashboard::class),
        );
    }
}
```

Этот пример регистрирует панель, но не выдаёт права на неё. Доступ настройте отдельно в приложении.

## Период и детализация

`getDateRanges()` берёт `range` из запроса; если ключ отсутствует — из `withRange(int|array $range)`. Массив на практике должен содержать две даты, разбираемые Carbon. PHPDoc у `withRange()` описывает элементы как `int`, но реализация диапазона разбирает даты через `Carbon::parse()`.

<table>
<thead>
  <tr>
    <th>
      <code>
        range
      </code>
    </th>
    
    <th>
      Текущее окно
    </th>
    
    <th>
      Предыдущее окно
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Нет значения или <code>
        empty()
      </code>
      
       (<code>
        null
      </code>
      
      , <code>
        0
      </code>
      
      , <code>
        '0'
      </code>
      
      , <code>
        []
      </code>
      
      , пустая строка)
    </td>
    
    <td>
      От <code>
        now() - D дней
      </code>
      
       до <code>
        now()
      </code>
      
      , где <code>
        D = frame.metrics.default_range_days
      </code>
      
      , fallback <code>
        30
      </code>
    </td>
    
    <td>
      От начала текущего минус <code>
        D дней
      </code>
      
       до начала текущего минус один день
    </td>
  </tr>
  
  <tr>
    <td>
      Положительное число дней, например <code>
        30
      </code>
      
       или <code>
        '30'
      </code>
    </td>
    
    <td>
      От <code>
        now() - N дней
      </code>
      
       до <code>
        now()
      </code>
    </td>
    
    <td>
      От <code>
        now() - 2N дней
      </code>
      
       до <code>
        now() - N дней
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Массив <code>
        [start, end]
      </code>
    </td>
    
    <td>
      Ровно эти две границы
    </td>
    
    <td>
      От <code>
        start - (end - start)
      </code>
      
       до <code>
        start
      </code>
    </td>
  </tr>
</tbody>
</table>

Числовое значение приводится к `int`; передавайте положительное целое. Отрицательное значение, массив не из двух дат, обратный порядок и неразбираемая дата приводят к `InvalidRangeException`. Не используйте `range=0` как запрос «за всё время»: это окно по умолчанию.

Например, JSON-параметр диапазона имеет вид:

```json
{
  "range": ["2026-10-01T00:00:00+03:00", "2026-10-31T23:59:59+03:00"]
}
```

Это форма параметра, а не тело POST: штатный эндпоинт метрики — GET. Для query string передайте `range[0]` и `range[1]`. Значения `from`, `to`, `granularity` и строковые пресеты вроде `last_30_days` автоматически не читаются. Границы не округляются до начала/конца суток; `whereBetween()` включает обе. У соседних текущего/предыдущего окон может совпадать граничный момент. Строка только с датой означает момент, разобранный Carbon, а не конец дня.

Для `ValueMetric` и временных Line/Bar-хелперов диапазон применяется даже без явного `range`. Колонка даты по умолчанию — `getQualifiedCreatedAtColumn()` модели. Для категориального Bar тоже используется эта колонка, заменить её аргументом нельзя. Для Pie период задавайте своим запросом.

`TimeUnit` содержит `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR`. Хелперы временных рядов по умолчанию используют `DAY`. Автоподбор вызывайте явно: `determineTimeUnit($request->input('range'))`. Он выбирает HOUR при числе дней ≤ 2, DAY ≤ 31, WEEK ≤ 90, MONTH ≤ 730, иначе YEAR; пороги читаются из `frame.metrics.range_thresholds`. Без значения выбирает DAY; MINUTE автоматически не выбирается. Внутри `getDateRanges($request, $unit)` аргумент `$unit` не меняет границы.

Line дополняет отсутствующие временные точки нулями. Bar возвращает только найденные группы. Недельные группы привязаны к понедельнику.

Line и временной Bar сохраняют предыдущий агрегат через `setPreviousValue()`, но их DTO сериализуют только точки, без `previousValue`. У категориального Bar предыдущий агрегат сейчас вычисляется на клоне запроса, уже ограниченного текущим периодом: два `whereBetween()` пересекаются. Не используйте это состояние как достоверное сравнение периодов без отдельного расчёта. Pie-хелперы предыдущий агрегат не вычисляют.

### SQL по драйверам

Группировка времени использует `TimeUnit::getSqlExpression()` и фактический драйвер подключения модели:

<table>
<thead>
  <tr>
    <th>
      Драйвер
    </th>
    
    <th>
      Выражения
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mysql
      </code>
      
      , <code>
        mariadb
      </code>
    </td>
    
    <td>
      <code>
        DATE_FORMAT
      </code>
      
      , <code>
        DATE
      </code>
      
      , <code>
        YEAR
      </code>
      
      ; неделя через <code>
        DATE_SUB
      </code>
      
       и <code>
        WEEKDAY
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pgsql
      </code>
    </td>
    
    <td>
      <code>
        TO_CHAR
      </code>
      
      ; неделя через <code>
        date_trunc('week', ...)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sqlite
      </code>
    </td>
    
    <td>
      <code>
        strftime
      </code>
      
      ; неделя через <code>
        date
      </code>
      
       с вычислением смещения
    </td>
  </tr>
  
  <tr>
    <td>
      Прочие
    </td>
    
    <td>
      Только fallback <code>
        DATE(column)
      </code>
      
      , без полноценной детализации
    </td>
  </tr>
</tbody>
</table>

Наличие веток SQL не доказывает совместимость всего приложения с каждой СУБД. Проверьте свой драйвер, типы дат, часовой пояс и выбранную детализацию отдельно. Имена колонок и SQL-функции задавайте в коде, не берите их напрямую из запроса.

## Справочник хелперов

Все перечисленные хелперы — `protected`, для вызова внутри `calculate()`. Ниже сигнатуры, а не отдельные исполняемые PHP-файлы. `Builder` означает **Eloquent** `Illuminate\Database\Eloquent\Builder`, не `Illuminate\Database\Query\Builder`. Строка `$model` — имя класса модели; объект модели аргументом не принимается. Переданный Builder может изменяться хелперами графиков — при повторном использовании клонируйте его.

### ValueMetric

`count`, `sum`, `average`, `min`, `max` возвращают `float`. Не оборачивайте их в несуществующий `StatValue::make()`.

```php
count(FrameRequest $request, Builder|string $model, ?string $dateColumn = null): float
sum(FrameRequest $request, Builder|string $model, string $column, ?string $dateColumn = null): float
average(FrameRequest $request, Builder|string $model, string $column, ?string $dateColumn = null): float
min(FrameRequest $request, Builder|string $model, string $column, ?string $dateColumn = null): float
max(FrameRequest $request, Builder|string $model, string $column, ?string $dateColumn = null): float
aggregate(FrameRequest $request, Builder|string $model, string $function, ?string $column = null, ?string $dateColumn = null): float
```

У `aggregate()` порядок — функция, числовая колонка, колонка даты. При `column: null` используется квалифицированный первичный ключ модели. `average()` вызывает агрегат `avg`.

### LineChartMetric

Для суммы и среднего колонка стоит перед `TimeUnit`; у `aggregate()` порядок иной — сначала `TimeUnit`, затем функция. Отдельных `min()` / `max()` в этом классе нет.

```php
count(FrameRequest $request, Builder|string $model, TimeUnit $unit = TimeUnit::DAY, ?string $column = null, ?string $dateColumn = null): LineChart
sum(FrameRequest $request, Builder|string $model, string $column, TimeUnit $unit = TimeUnit::DAY, ?string $dateColumn = null): LineChart
average(FrameRequest $request, Builder|string $model, string $column, TimeUnit $unit = TimeUnit::DAY, ?string $dateColumn = null): LineChart
aggregate(FrameRequest $request, Builder|string $model, TimeUnit $unit, string $function, ?string $column = null, ?string $dateColumn = null): LineChart
```

### BarChartMetric

Временные хелперы возвращают `BarChart`; отдельного `average()` нет, среднее можно запросить через `aggregateByTime(..., 'avg', ...)`.

```php
count(FrameRequest $request, Builder|string $model, TimeUnit $unit = TimeUnit::DAY, ?string $column = null, ?string $dateColumn = null): BarChart
sum(FrameRequest $request, Builder|string $model, string $column, TimeUnit $unit = TimeUnit::DAY, ?string $dateColumn = null): BarChart
aggregateByTime(FrameRequest $request, Builder|string $model, TimeUnit $unit, string $function, ?string $column = null, ?string $dateColumn = null): BarChart
countByCategory(FrameRequest $request, Builder|string $model, string $categoryColumn, int $limit = 10, ?string $sortDirection = 'desc'): BarChart
sumByCategory(FrameRequest $request, Builder|string $model, string $categoryColumn, string $valueColumn, int $limit = 10, ?string $sortDirection = 'desc'): BarChart
averageByCategory(FrameRequest $request, Builder|string $model, string $categoryColumn, string $valueColumn, int $limit = 10, ?string $sortDirection = 'desc'): BarChart
aggregateByCategory(FrameRequest $request, Builder|string $model, string $function, string $categoryColumn, ?string $valueColumn = null, int $limit = 10, ?string $sortDirection = 'desc'): BarChart
```

Серверный `countByCategory($request, $query, 'status')` действительно существует. Но стандартный Vue BarChart не является универсальным категориальным рендерером: текстовые статусы не становятся корректной осью времени. Для них используйте Pie или свой компонент.

### PieChartMetric

В Pie нет отдельного `averageByCategory()`: для среднего доступен `aggregateByCategory()` с `'avg'`. Хелпер `createFromArray()` не обращается к БД.

```php
countByCategory(FrameRequest $request, Builder|string $model, string $categoryColumn, int $limit = 10, ?string $sortDirection = 'desc'): PieChart
sumByCategory(FrameRequest $request, Builder|string $model, string $categoryColumn, string $valueColumn, int $limit = 10, ?string $sortDirection = 'desc'): PieChart
aggregateByCategory(FrameRequest $request, Builder|string $model, string $function, string $categoryColumn, ?string $valueColumn = null, int $limit = 10, ?string $sortDirection = 'desc'): PieChart
createFromArray(array $data): PieChart
```

Для категориальных Bar/Pie `limit = 10` ограничивает число возвращённых категорий, а не объединяет остальные в «Другие». `0` снимает лимит; `sortDirection: null` отключает явную сортировку, `'asc'` / `'desc'` сортируют по агрегату. Значение `null` категории получает подпись `(Empty)`. Не рассчитывайте, что `frame.metrics.category_limit` заменит аргумент: в сигнатурах зафиксировано `10`.

## DTO и JSON

Эндпоинт возвращает результат `resolve()` напрямую, без оболочки `data`. Не путайте его с описанием карточки и с `Overlook`: последний — другая карточка со сводкой ресурсов, не DTO метрики.

### Одно число

У `StatValue` есть следующие фабрики. В отличие от хелперов модели, они уже возвращают DTO.

```php
StatValue::createNumber(string $label, float $value, ?float $previousValue = null, int $decimals = 0): self
StatValue::createPercent(string $label, float $value, ?float $previousValue = null, int $decimals = 2): self
StatValue::createCurrency(string $label, float $value, ?float $previousValue = null, string $currency = 'USD', int $decimals = 0): self
```

`createPercent()` принимает уже проценты: `25`, а не `0.25`. Пример JSON для числа 120 после 100:

```json
{
  "label": "Заказы",
  "value": 120,
  "previousValue": 100,
  "format": "number",
  "currency": "USD",
  "decimals": 0,
  "showArrow": true,
  "trendThreshold": 0,
  "colorType": "positive-is-success",
  "hidePercentChange": false,
  "changePercent": 20,
  "changeValue": 20
}
```

Сериализация использует именно camelCase. Управляйте отображением через `setDecimals(int)`, `setFormat(string)`, `setCurrency(string)`, `setShowArrow(bool)`, `setTrendThreshold(float)`, `setColorType(string)`, `setHidePercentChange(bool)`; сеттеры возвращают `self`. Для показателя, рост которого нежелателен, задайте `setColorType('positive-is-danger')`.

DTO считает `changePercent = (value - previousValue) / abs(previousValue) * 100`. При предыдущем `null` или нуле процент равен `null`; `changeValue` равен `null` только при предыдущем `null`. Vue пересчитывает процент из значений сам: нулевой предыдущий результат не показывает как делитель, нулевое изменение не выводит. Не обещайте стрелку роста «с нуля».

`formattedValue` и `previousFormattedValue` поддерживаются Vue-компонентом, но стандартный PHP `StatValue` их не сериализует. Форматирование по умолчанию делает `Intl.NumberFormat` в браузере.

### Точки графиков

Line/Bar/Pie сериализуются в **массив точек**, а не в объект `labels/datasets`. Конструкторы точек:

```php
new TimeDataPoint(DateTimeImmutable $date, int|float $value, array $metadata = [])
new CategoryDataPoint(string $category, int|float $value, ?string $series = null, ?string $color = null, array $metadata = [])
new PieDataPoint(string $name, float $value, ?string $color = null, array $metadata = [])
```

Импортируйте `DateTimeImmutable` из глобального пространства, а точки — из `Frame\LaravelMetrics\DTO`. DTO принимают их через `addDataPoint()` соответствующего типа. У `PieChart` есть старый `addSectors(array $data)` с формой `['Новые' => 12.0]`, но он записывает в точки цвета вроде `text-blue-500`. Встроенный SVG-рендерер использует `color` напрямую как `fill`, а класс Tailwind не является CSS-цветом. Для ручных секторов используйте `addDataPoint(new PieDataPoint('Новые', 12.0, '#3B82F6'))`; [пример](https://frame.qubeek.io/ru/developers/resources/dashboards#piechartmetric-%D1%80%D0%B0%D1%81%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5) задаёт цвета явно.

<table>
<thead>
  <tr>
    <th>
      DTO
    </th>
    
    <th>
      Обязательные JSON-поля точки
    </th>
    
    <th>
      Дополнительные поля
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        LineChart
      </code>
    </td>
    
    <td>
      <code>
        date: string
      </code>
      
       в ISO 8601, <code>
        value: number
      </code>
    </td>
    
    <td>
      Например <code>
        formattedValue: string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BarChart
      </code>
    </td>
    
    <td>
      <code>
        category: string
      </code>
      
      , <code>
        value: number
      </code>
    </td>
    
    <td>
      <code>
        series: string
      </code>
      
      , <code>
        color: string
      </code>
      
      , <code>
        formattedValue: string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PieChart
      </code>
    </td>
    
    <td>
      <code>
        name: string
      </code>
      
      , <code>
        value: number
      </code>
    </td>
    
    <td>
      <code>
        color: string
      </code>
      
      , <code>
        percentage: number
      </code>
      
      , <code>
        formattedValue: string
      </code>
    </td>
  </tr>
</tbody>
</table>

`metadata` разворачивается в поля самой точки, вложенного ключа `metadata` нет. Pie вычисляет `percentage` от суммы **возвращённых** секторов с округлением до одного знака; при сумме ≤ 0 процент не добавляется. Если задан лимит категорий, это доли выбранных категорий, не всей таблицы.

Например, ответ Line:

```json
[
  {"value": 3, "formattedValue": "3", "date": "2026-10-01T00:00:00+00:00"},
  {"value": 0, "formattedValue": "0", "date": "2026-10-02T00:00:00+00:00"}
]
```

## Контракт Vue и опции

Backend сериализует описание Value-карточки с `component: 'Value'` и `props: {name, label}`. У графика — `component: 'Chart'`, дополнительно `props.chart_type` и `props.options`. Числовые данные не встроены в это описание.

`@frame/vue` регистрирует `Value` и `Chart` через `DashboardComponentRegistry.register({name, component})` (принимается и массив). Страница дашборда находит компонент по `component`, переводит props через `toCamelProps()` и добавляет `dashboard`. Так `chart_type` становится `chartType`. Карточки отдельно запрашивают `GET /dashboards/{dashboard}/metrics/{name}` относительно API base URL клиента.

Встроенные Value/Chart-карточки не добавляют `range`, `filters` или `group_by` в этот GET и не предоставляют селектор периода. `withRange()` задаёт серверный fallback. Самостоятельная передача query-параметров требует отдельной интеграции клиента.

Имя метрики выводится из basename PHP-класса: удаляется `Metric`, между строчными/заглавными буквами вставляется дефис, результат приводится к нижнему регистру. Например, `RevenueMetric` → `revenue`. Метрики с одинаковым именем внутри одного дашборда не различаются подписью: контроллер выбирает первую найденную.

`Value` использует `StatValue` из `@frame/vue-charts`. `Chart` выбирает из своей карты `line`, `bar`, `pie`, `donut`, `half-donut`, `progress`, `breakdown`. Наличие UI-типа не означает наличие одноимённого PHP-хелпера. Графики Frame используют SVG и D3, не настройки Chart.js или ApexCharts.

### ChartOptions

Передайте `ChartOptions` в `setOptions()` карточки или переопределите `getDefaultOptions(): ChartOptions` в классе метрики. Это опции карточки, а не часть ответа с точками. Фабрики: `createDefaultLineChartOptions()`, `createDefaultBarChartOptions()`, `createDefaultPieChartOptions()`.

<table>
<thead>
  <tr>
    <th>
      Сеттер, возвращает <code>
        self
      </code>
    </th>
    
    <th>
      Сериализуемое значение
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        setXAxis(?string $title = null, ?int $tickCount = null, ?bool $gridLines = null)
      </code>
    </td>
    
    <td>
      <code>
        xAxis: {title, tickCount, gridLines}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setYAxis(?string $title = null, ?int $tickCount = null, ?bool $gridLines = null)
      </code>
    </td>
    
    <td>
      <code>
        yAxis: {title, tickCount, gridLines}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setTooltip(?bool $enabled = true)
      </code>
    </td>
    
    <td>
      <code>
        tooltip: {enabled}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setAnimation(?bool $enabled = true, ?int $duration = 500)
      </code>
    </td>
    
    <td>
      <code>
        animation: {enabled, duration}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setLegend(?bool $enabled = true, ?string $position = 'bottom')
      </code>
    </td>
    
    <td>
      <code>
        legend: {enabled, position}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setMargin(?int $top = 10, ?int $right = 10, ?int $bottom = 30, ?int $left = 40)
      </code>
    </td>
    
    <td>
      <code>
        margin: {top, right, bottom, left}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setColors(array $colors)
      </code>
    </td>
    
    <td>
      <code>
        colors: string[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setA11yTitle(?string $a11yTitle)
      </code>
    </td>
    
    <td>
      <code>
        a11yTitle: string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setA11yDescription(?string $a11yDescription)
      </code>
    </td>
    
    <td>
      <code>
        a11yDescription: string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setTheme(?string $theme)
      </code>
    </td>
    
    <td>
      <code>
        theme: string
      </code>
    </td>
  </tr>
</tbody>
</table>

PHP DTO пропускает свойства, равные `null`, но не проверяет весь набор значений. Сериализация опции не гарантирует её поддержку рендерером:

- Line/Bar используют `yAxis.tickCount`, `yAxis.gridLines`, `tooltip.enabled`, `legend.enabled`; число подписей X адаптивное (3 на мобильном, 5 на desktop), а не из `xAxis.tickCount`. Названия осей из DTO не выводятся этим шаблоном.
- PHP допускает строку позиции легенды, но Vue-контракт задаёт только `top` / `bottom`. Line показывает легенду только при нескольких сериях.
- `margin`, `theme`, `a11yDescription` не имеют соответствующих props в этих встроенных Line/Bar/Pie-компонентах. `animation.duration` не является универсальным регулятором анимации этих графиков.
- `BarChart` не раскладывает плоские точки по `series`; при массиве массивов основной показ берёт первую серию. Не обещайте grouped/stacked bar на основании DTO.
- Bar-хелпер берёт цвета из `getOptions()->getColors()` или дефолтной палитры; Pie-хелпер — из `frame.metrics.chart_colors`. Цвет точки приоритетнее палитры в UI. Передавайте непустые массивы цветов и CSS-цвета вроде `#3B82F6`, а не Tailwind-классы для SVG `fill`.

## Доступ, фильтры и область данных

Метрика не получает запрос ресурса автоматически. Хелперы начинают с переданного Eloquent Builder или `(new $model)->newQuery()`. Они не вызывают resource query, Slim-фильтры или применение `filters` из запроса. Глобальные Eloquent scopes модели могут работать, но это свойство модели, а не обещание Metrics API. SoftDeletes и tenant-ограничения проверяйте для конкретного запроса.

Штатный маршрут находится внутри группы `auth:frame`, `IdentifyTenant`, `RequiresStrongAuthorizationMiddleware`. Контроллер проверяет Gate `frame-view-dashboard.{slug}` **или** `frame-view-dashboard`, ищет зарегистрированный дашборд и метрику в его `metrics()`, затем вызывает `resolve()`. Неизвестная метрика даёт 404.

Это разные уровни:

- Аутентификация и Gate разрешают обращение к эндпоинту.
- Наличие карточки в `cards()` определяет обнаружение метрики. `Dashboard::metrics()` не проверяет `show()` / `hide()`; `canBrowse()` / `authorize()` панели также не вызываются этим контроллером напрямую.
- Условия SQL определяют, чьи записи попадут в агрегат. Само разрешение на панель не добавляет `where tenant_id = ...` и не заменяет policy для данных.

**Рекомендация для приложения:** проверяйте права на конкретный показатель на сервере и стройте Builder с разрешённой областью данных до агрегации. Разбирайте и валидируйте свои фильтры явно. Клиентское скрытие карточки и наличие `IdentifyTenant` не доказывают изоляцию запроса метрики.

## Кеширование

Фактический default `BaseMetric::cacheFor(): ?int` — `null`: **кеш выключен**. `refreshAfter(): ?int` тоже возвращает `null`. Значения `frame.metrics.cache_duration` / `cache_refresh` в конфигурации workspace не подключены этими базовыми методами.

Переопределение `cacheFor()` положительным числом включает кеш; число задаётся **в минутах**. `resolve()` умножает его на `60` перед `Cache::remember()`. Если проходит проверка `method_exists(Cache::class, 'flexible')` и задан `refreshAfter()`, в `cache()->flexible()` передаётся массив `[cacheFor * 60, refreshAfter * 60]`. Не считайте наличие Laravel 11+ достаточным доказательством выбора этой ветки и не копируйте интервалы из workspace без проверки порядка, ожидаемого вашим cache API.

<warning>

Базовый ключ имеет форму `metrics.{static::name()}.{md5(json_encode(params))}`. В `params` только входные `range`, `filters` (default `[]`) и `group_by`; `null` исключаются. Пользователь, tenant, дашборд, настройки экземпляра (`withRange()`), `from` / `to` и другие пользовательские параметры в ключ не входят. Даже одинаковый basename метрик в разных namespace может дать одно имя. Автоматической изоляции кеша по пользователю или tenant нет.

</warning>

**Рекомендация для приложения:** оставьте кеш выключенным для пользовательских/tenant-зависимых показателей или переопределите `getCacheKey(FrameRequest $request): string`. Включите в собственный ключ серверно определённые actor/tenant scope, версию расчёта, фактические границы периода и все параметры, влияющие на результат. Изоляция ключа не заменяет ограничения SQL и проверку доступа.

Наличие `filters` в ключе не означает применение фильтров к запросу. При cache hit `calculate()` не вызывается: возвращается сохранённый DTO. Поэтому предыдущее значение для Value должно храниться в самом `StatValue`, как в примере, а не читаться из состояния экземпляра после `resolve()`.

## Проверка в своём приложении

Это рекомендации по приёмке, а не автоматически выполненные проверки Metrics API:

- Сверьте схему модели, импорты, права на показатель и область SQL-запроса.
- Проверьте без `range`, числовой диапазон и две точные даты; отдельно — границы суток, недели, пустой результат и предыдущий ноль.
- Сравните суммы с независимым запросом на изолированных данных и выбранном драйвере БД.
- Проверьте фактический JSON без обёрток и отображение во встроенном Vue-компоненте.
- Для scoped-метрик проверьте прямой GET под двумя пользователями/tenant, с разрешением и отказом; при включённом кеше повторите на холодном и прогретом кеше.

## Что дальше

- [Информационные панели](https://frame.qubeek.io/ru/developers/resources/dashboards) — карточки и регистрация дашборда
- [Агрегации](https://frame.qubeek.io/ru/developers/resources/summarizers) — итоги в таблицах ресурсов
- [Авторизация](https://frame.qubeek.io/ru/developers/resources/authorization) — серверные проверки доступа
- [Мультитенантность](https://frame.qubeek.io/ru/developers/customization/tenancy) — область данных приложения


## Sitemap

See the full [sitemap](https://frame.qubeek.io/sitemap.md) for all pages.
