Отчёты

Отчёты (/reports) — табличные выгрузки по данным сущностей. Отчёт строится одним из двух способов:

• конструктор — колонки (включая поля связанных сущностей), фильтры, группировка с промежуточными итогами, сортировка;
• SQL-запрос — запрос SELECT к данным всех сущностей тенанта, см. SQL-отчёты.

Готовый отчёт можно смотреть в интерфейсе, выгружать в CSV / XLSX / PDF и рассылать по расписанию на email — одинаково для обоих способов.

Отчёты дополняют дашборды и графики: график отвечает на вопрос «сколько и как меняется», отчёт — «какие именно записи и с какими значениями», в форме, пригодной для передачи руководителю или клиенту.

Кто что может

Право / роль	Возможности
reports.view	Видеть и выполнять отчёты, к которым дан доступ
reports.build	Создавать и редактировать собственные отчёты в конструкторе
reports.sql	Создавать и редактировать собственные SQL-отчёты
Роль Конструктор отчётов (report_builder)	Готовый набор: reports.build + reports.view
Роль Администратор отчётов (report_administrator)	То же + право раздела admin.reports — администрирование всех отчётов, включая SQL
Роль Администратор (admin)	Полный доступ ко всем отчётам без ограничений

Данные фильтруются правами

Отчёт конструктора показывает только те записи, которые доступны выполняющему его пользователю по правилам доступа к записям. Отчёты по расписанию выполняются от имени владельца отчёта — получатели письма увидят данные в объёме прав владельца.

SQL-отчёт читает все записи сущностей тенанта: правила доступа к записям к запросу не применяются. Поэтому reports.sql — отдельное право, и роль Конструктор отчётов его не включает.

Создание отчёта

1. Откройте раздел Отчёты
2. Нажмите Создать отчёт
3. На вкладке Основное укажите название, описание и сущность — источник данных. Если у вас есть право reports.sql, здесь же выбирается способ построения: Конструктор или SQL-запрос (про второй — в разделе SQL-отчёты)

TIP

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

Дальше отчёт настраивается по вкладкам.

Колонки

Кнопка Добавить колонку открывает дерево полей:

• поля самой сущности — любое поле из конструктора;
• поля связанных сущностей — через ссылочные поля можно «дотянуться» до полей связанной записи (до 2 переходов), например Заявка → Клиент → Название компании;
• у каждой колонки можно задать свой Заголовок колонки вместо автоматического.

Кнопка Добавить агрегат по связанным создаёт вычисляемую колонку по дочерним записям: количество, сумма, среднее, минимум или максимум по числовому полю связанной сущности, при необходимости — с условиями отбора дочерних записей. Пример: колонка «Открытых сделок» в отчёте по клиентам.

Фильтры

Каждый фильтр — это поле (своё или связанной сущности), оператор и значение. Доступные операторы: равно / не равно, содержит, сравнения (>, <, >=, <=), «одно из», диапазон дат, относительный период (Сегодня, Вчера, Текущая/Прошлая неделя, Последние N часов/дней и т.п.), между, пусто / не пусто, по категории, наличие связанных записей.

У фильтра есть переключатель Параметр пользователя — такой фильтр становится изменяемым при просмотре: зритель отчёта может подставить своё значение (например, выбрать период), не имея прав на редактирование самого отчёта. Флаг Обязательный не даст выполнить отчёт, пока параметр не заполнен.

Группировка и итоги

До 3 уровней группировки, каждый со своим направлением сортировки. Для сгруппированного отчёта настраиваются итоги — агрегатные значения по группам и по отчёту в целом:

• count — количество записей;
• sum, avg, min, max — по числовым полям;
• перцентили p50, p90, p95, p99 … — по числовым полям (например, «90 % заявок решаются быстрее X часов»).

Итог выводится в той колонке, где показано агрегируемое поле, поэтому поле должно присутствовать среди колонок отчёта.

Сортировка

Список полей с направлением (по возрастанию/убыванию) — применяется внутри групп или ко всему отчёту, если группировки нет.

Доступ

По умолчанию отчёт видит только владелец (и администраторы). На вкладке Доступ его можно выдать:

• конкретным пользователям;
• ролям;
• группам.

Получатели доступа видят отчёт в списке и могут выполнять его (с собственными значениями параметров), но не редактировать.

Расписания

Вкладка Расписания автоматизирует рассылку:

Поле	Описание
Cron-выражение	Периодичность в формате cron, например 0 8 * * 1 — по понедельникам в 08:00
Часовой пояс	В каком поясе трактовать cron-выражение
Формат	CSV, XLSX или PDF
Получатели	Email-адреса и/или пользователи системы (можно вперемешку)
Параметры	Значения параметров-фильтров для этого расписания
Активно	Выключенное расписание сохраняется, но не выполняется

Кнопка Запустить сейчас выполняет расписание немедленно — удобно проверить письмо, не дожидаясь cron.

Файл до 10 МБ приходит вложением в письмо; более крупный — ссылкой на скачивание (ссылка действует 7 дней).

SQL-отчёты

SQL-отчёт — запрос SELECT к данным тенанта. Способ построения выбирается при создании и потом не меняется. Вкладки SQL-отчёта: Основное, Запрос, Параметры, Доступ, Расписания.

Вкладка «Запрос»

Слева — схема: таблицы, доступные запросу, и их колонки с типами. Щелчок по имени вставляет его в редактор. Редактор подсказывает имена таблиц, колонок (в том числе после псевдоним.) и параметров (после :).

Кнопка Выполнить (или Ctrl+Enter в редакторе) запускает несохранённый текст и показывает первые 200 строк, время выполнения и ошибку Postgres с номером строки, если запрос не выполнился.

Какие таблицы видит запрос

Таблица	Что в ней
<имя сущности>	По таблице на каждую сущность, имя — системное имя сущности (table_name). Колонки: id, uid, created_at, updated_at, created_by, updated_by, затем по колонке на каждое поле и data — все значения записи в JSONB
<сущность>_<связь>_<сущность>	Связи «многие-ко-многим»: id, l_table_id, r_table_id, created_at
sys_users	Пользователи тенанта: id, name, first_name, last_name, middle_name, email, position, company_id, org_unit_id, manager_id, created_at
sys_companies	Компании тенанта: id, name, code, is_external
sys_org_units	Подразделения тенанта: id, name, company_id, parent_id
sys_field_options	Подписи вариантов у полей-списков и статусов: entity, field, value, label (на языке зрителя), labels (все языки)

Типы колонок полей:

Тип поля	Тип колонки
Целое, дробное, валюта, число	numeric
Логическое	boolean
Дата	date
Дата и время	timestamptz
Ссылка на запись, пользователя, компанию, подразделение, категорию (одно значение)	bigint — id записи
Любое поле с несколькими значениями, файлы, изображения, координаты	jsonb
Остальные	text

Значение, которое не приводится к типу колонки (например, текст в числовом поле), приходит как NULL; исходное значение остаётся в data.

Пример — заявки по исполнителям с подписью статуса:

SELECT u.name AS "Исполнитель",
       coalesce(st.label, i.status) AS "Статус",
       count(*) AS "Заявок"
FROM incidents i
LEFT JOIN sys_users u ON u.id = i.assigned_to
LEFT JOIN sys_field_options st
       ON st.entity = 'incidents' AND st.field = 'status' AND st.value = i.status
WHERE i.created_at >= :period_from AND i.created_at < :period_to
GROUP BY 1, 2
ORDER BY 3 DESC

Названия колонок результата — это имена или псевдонимы из SELECT (AS "Заголовок"). Группировку и итоги SQL-отчёт считает сам запрос (GROUP BY, ROLLUP, оконные функции) — вкладок конструктора у него нет.

Параметры

Параметр — значение, которое зритель вводит перед запуском. В запросе он пишется как :имя. Типы:

Тип	В запросе
Текст	:имя — text
Число	:имя — numeric
Дата	:имя — date
Период	:имя_from и :имя_to — границы выбранного периода (timestamptz), конец не включается: WHERE created_at >= :имя_from AND created_at < :имя_to

Периоды — те же, что у фильтра «относительный период» в конструкторе; границы считаются в часовом поясе зрителя, а для расписания — в поясе расписания.

Незаполненный необязательный параметр подставляется как NULL, поэтому условие по нему пишут так: (:status IS NULL OR status = :status). Значение по умолчанию используется, когда зритель параметр не менял, и в запусках по расписанию. Если в запросе встретился необъявленный :имя, на вкладке «Параметры» появляется кнопка, которая его добавит.

Что нельзя в запросе

• Одна команда: всё после ; — ошибка.
• Только чтение: запрос начинается с SELECT, WITH, VALUES или TABLE и выполняется в транзакции только для чтения.
• Только таблицы из схемы: запрос выполняется под отдельной ролью базы данных, у которой нет доступа к остальным таблицам и к данным других тенантов.
• Время: на просмотр и кнопку «Выполнить» — 30 секунд, на экспорт и расписание — 300 секунд (REPORTS_SQL_TIMEOUT, REPORTS_SQL_EXPORT_TIMEOUT). Запрос дольше останавливается с ошибкой.
• Двоеточие перед именем (:имя) — всегда параметр, двойное двоеточие (::text) — приведение типа. В срезе массива ставьте пробел после двоеточия: arr[1: n].

Доступ к SQL-отчёту

Назначенные пользователи, роли и группы видят в отчёте всё, что возвращает запрос, — фильтра по их правам нет. Текст запроса им не показывается: зритель видит только панель параметров и результат.

Просмотр и экспорт

Открытый отчёт (/reports/view/…) показывает данные прямо в интерфейсе — с группами, итогами и панелью параметров, если они настроены. Синхронный просмотр ограничен 10 000 строк; если данных больше, используйте экспорт.

Экспорт выполняется в фоне: нажмите кнопку нужного формата — задача уходит в очередь, а готовый файл появляется в списке выгрузок отчёта, откуда его можно скачать. Ограничения форматов:

Формат	Лимит строк	Комментарий
CSV	без практического лимита	Самый быстрый и лёгкий формат
XLSX	50 000	Готов для Excel: заголовки, группы, итоги
PDF	1 000	Для печати/подписи; при больших объёмах выгружайте XLSX/CSV

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

Примеры бизнес-кейсов

Еженедельная сводка для руководителя поддержки

Сущность Заявки:

• Колонки: номер, тема, статус, исполнитель, дата создания;
• Фильтр: «Дата создания» → относительный период → Прошлая неделя;
• Группировка: по исполнителю; итог — count (сколько заявок обработал каждый);
• Расписание: 0 8 * * 1, формат XLSX, получатель — руководитель отдела.

Каждый понедельник в 08:00 руководитель получает письмо с готовой таблицей за прошедшую неделю.

Контроль SLA через перцентили

Сущность Заявки, при условии что автоматизация или процесс записывает в запись числовое поле «Время решения, ч»:

• Колонки: категория, время решения;
• Фильтр-параметр: «Дата закрытия» → диапазон дат (зритель выбирает период сам);
• Группировка: по категории; итоги — avg и p90 по времени решения.

Отчёт отвечает на вопрос «90 % заявок какой категории мы решаем быстрее чем за N часов» — это честнее среднего, которое маскирует выбросы.

Клиенты с открытыми сделками (агрегат по связанным)

Сущность Клиенты из CRM-пресета:

• Колонки: название, менеджер + агрегат по связанным: count сделок с условием «статус = Открыта» и sum по полю «Сумма» тех же сделок;
• Сортировка: по сумме открытых сделок по убыванию;
• Доступ: роль менеджеров продаж.

Получается живой «пайплайн по клиентам», который каждый менеджер открывает со своими правами — правила доступа к записям автоматически ограничат список его клиентами.

Смотрите также

• Дашборды и графики — визуальная аналитика в реальном времени
• Доступ к записям — как права влияют на содержимое отчёта
• Пользователи, группы, роли — назначение ролей report_builder / report_administrator