08. Отчёты и диаграммы
8.1. Общая концепция
Отчёты — это SQL-запросы с параметрами, которые пользователь может выполнять через интерфейс. Платформа генерирует форму для ввода параметров, выполняет запрос и отображает результат в виде таблицы. Для визуализации данных можно добавлять диаграммы.
Особенности отчётов в платформе:
- Только SQL (нельзя использовать DSL-функции внутри отчёта)
- Параметры подставляются через
{{ИмяПараметра}} - RLS не применяется автоматически (нужно явно добавить условия)
- Поддерживаются диаграммы на базе Chart.js
- Можно добавить переключатель для показа/скрытия диаграммы
8.2. Синтаксис отчёта
ОТЧЁТ ИмяОтчёта
ПАРАМЕТР ИмяПараметра ТИП_ДАННЫХ
ПАРАМЕТР ИмяДругогоПараметра ТИП_ДАННЫХ [ОБЯЗАТЕЛЬНЫЙ]
ЗАПРОС "SELECT ... WHERE ... = '{{ИмяПараметра}}'"
КОЛОНКА ИмяКолонки1 ТИП_ДАННЫХ
КОЛОНКА ИмяКолонки2 ТИП_ДАННЫХ
ВЫВОД_ДИАГРАММА ТИП "столбчатая"
ПОЛЕ_ДЛЯ_ДИАГРАММЫ ИмяКолонки
РЕСУРС ИмяКолонкиСЧислами
ПАРАМЕТР ПоказыватьГрафик БУЛЕВО
КОНЕЦВажно: Параметр ПАРАМЕТР ПоказыватьГрафик БУЛЕВО в DSL-блоке отчёта всегда должен указываться перед блоком ЗАПРОС.
8.3. Типы параметров
| Тип | Ключевое слово | Как выглядит в UI | Значение в SQL |
|---|---|---|---|
| Строка | СТРОКА | Текстовое поле | Подставляется как есть |
| Число | ЧИСЛО | Поле для ввода цифр | Подставляется как есть |
| Дата | ДАТА | Выбор даты | YYYY-MM-DD |
| Дата/Время | ДАТАВРЕМЯ | Выбор даты и времени | YYYY-MM-DD HH:MM:SS |
| Выбор из коллекции | ВЫБОР ИмяКоллекции | Выпадающий список | ID выбранной записи |
| Булево | БУЛЕВО | Чекбокс | 1 или 0 |
8.4. Управление отображением диаграммы
Для добавления пользовательского контроля над отображением диаграммы используется параметр ПАРАМЕТР ПоказыватьГрафик БУЛЕВО. По умолчанию (без этого параметра) диаграмма показывается всегда.
Поведение:
- Если параметр НЕ указан — диаграмма отображается всегда
- Если параметр указан — в интерфейсе появляется чекбокс «Показывать график», который по умолчанию включён (ИСТИНА)
- Если параметр указан и пользователь снял галочку — отображается только таблица без диаграммы
- Параметр должен указываться первым в блоке ОТЧЁТ (после объявления отчёта, перед ЗАПРОС)
Пример правильного размещения параметра:
ОТЧЁТ ПродажиПоМесяцам
ПАРАМЕТР ПоказыватьГрафик БУЛЕВО # ← первым после имени отчёта
ПАРАМЕТР Год ЧИСЛО ОБЯЗАТЕЛЬНЫЙ
ЗАПРОС "
SELECT
strftime('%m', Дата) as Месяц,
SUM(ИтогоСумма) as СуммаПродаж
FROM ЗаказНаряд
WHERE strftime('%Y', Дата) = '{{Год}}'
GROUP BY Месяц
ORDER BY Месяц
"
КОЛОНКА Месяц СТРОКА
КОЛОНКА СуммаПродаж ЧИСЛО
ВЫВОД_ДИАГРАММА ТИП "линейная"
ПОЛЕ_ДЛЯ_ДИАГРАММЫ Месяц
РЕСУРС СуммаПродаж
КОНЕЦ8.5. Диаграммы
Платформа поддерживает построение диаграмм на основе данных отчёта. Движок визуализации на базе Chart.js автоматически читает таблицу, очищает данные и строит график.
Поддерживаемые типы диаграмм:
| Команда в DSL | Тип графика | Для чего используется |
|---|---|---|
| СТОЛБИКОВАЯ (или ГИСТОГРАММА) | bar | Сравнение показателей |
| КРУГОВАЯ | pie | Отображение долей от целого |
| БУБЛИК | doughnut | Круговая диаграмма с отверстием |
| ЛИНЕЙНАЯ | line | Анализ динамики и трендов |
| РАДАР | radar | Сравнение нескольких метрик ("паутина") |
Синтаксис добавления диаграммы:
ВЫВОД_ДИАГРАММА <ТипДиаграммы>
ПОЛЕ_ДЛЯ_ДИАГРАММЫ <ИмяКолонкиДляПодписей>
РЕСУРС <ИмяКолонкиСЦифрами>
ПАРАМЕТР ПоказыватьГрафик БУЛЕВО # опционально, указывается перед ЗАПРОССохранение диаграммы как рисунка:
Любую построенную диаграмму пользователь может сохранить как изображение. Для этого необходимо нажать правой кнопкой мыши на диаграмму и в появившемся контекстном меню выбрать пункт «Сохранить картинку как...». Диаграмма сохранится в формате PNG с прозрачным фоном.
Пример отчёта с диаграммой (без переключателя):
ОТЧЁТ ВыручкаПоВидам
ПАРАМЕТР ДатаС ДАТАВРЕМЯ
ПАРАМЕТР ДатаПо ДАТАВРЕМЯ
ЗАПРОС "
SELECT ВидУслуги, SUM(Сумма) as СуммаВыручки
FROM Журнал_Продаж
GROUP BY ВидУслуги
"
КОЛОНКА ВидУслуги СТРОКА
КОЛОНКА СуммаВыручки ЧИСЛО
ВЫВОД_ДИАГРАММА БУБЛИК
ПОЛЕ_ДЛЯ_ДИАГРАММЫ ВидУслуги
РЕСУРС СуммаВыручки
КОНЕЦОсобенности работы диаграмм:
- Автоматическая очистка данных: числа с пробелами и запятыми преобразуются в корректные значения
- Экспорт в PNG правой кнопкой мыши: клик правой кнопкой по диаграмме → «Сохранить картинку как...»
- Игнорирование нулей: строки с ресурсом = 0 или «Нет данных» автоматически отсекаются
- Умный Fallback: при ошибке в имени колонки система берёт первую текстовую колонку для подписей и последнюю — для цифр
8.6. Примеры отчётов
Пример: Отчёт с диапазоном дат
ОТЧЁТ ПродажиЗаПериод
ПАРАМЕТР ДатаС ДАТА ОБЯЗАТЕЛЬНЫЙ
ПАРАМЕТР ДатаПо ДАТА ОБЯЗАТЕЛЬНЫЙ
ЗАПРОС "
SELECT Дата, Номер, Клиент, ИтогоСумма, Статус
FROM ЗаказНаряд
WHERE Дата BETWEEN '{{ДатаС}}' AND '{{ДатаПо}}'
ORDER BY Дата DESC
"
КОЛОНКА Дата ДАТАВРЕМЯ
КОЛОНКА Номер СТРОКА
КОЛОНКА Клиент ВЫБОР Клиенты
КОЛОНКА ИтогоСумма ЧИСЛО
КОЛОНКА Статус СТРОКА
КОНЕЦПример: Отчёт с необязательными параметрами
ОТЧЁТ ФильтрЗаказов
ПАРАМЕТР Клиент ВЫБОР Клиенты
ПАРАМЕТР Статус СТРОКА
ЗАПРОС "
SELECT id, Номер, Дата, Клиент, ИтогоСумма, Статус
FROM ЗаказНаряд
WHERE 1=1
{{ЕСЛИ Клиент}} AND Клиент = '{{Клиент}}' {{КОНЕЦ}}
{{ЕСЛИ Статус}} AND Статус = '{{Статус}}' {{КОНЕЦ}}
ORDER BY Дата DESC
"
КОЛОНКА id ЧИСЛО
КОЛОНКА Номер СТРОКА
КОЛОНКА Дата ДАТАВРЕМЯ
КОЛОНКА Клиент ВЫБОР Клиенты
КОЛОНКА ИтогоСумма ЧИСЛО
КОЛОНКА Статус СТРОКА
КОНЕЦПример: Агрегатный отчёт с GROUP BY и диаграммой с переключателем
ОТЧЁТ СуммаПродажПоКлиентам
ПАРАМЕТР ПоказыватьГрафик БУЛЕВО
ПАРАМЕТР ДатаС ДАТА
ЗАПРОС "
SELECT
К.Наименование as Клиент,
COUNT(З.id) as КоличествоЗаказов,
SUM(З.ИтогоСумма) as ОбщаяСумма
FROM ЗаказНаряд З
JOIN Клиенты К ON З.Клиент = К.id
WHERE 1=1
{{ЕСЛИ ДатаС}} AND З.Дата >= '{{ДатаС}}' {{КОНЕЦ}}
GROUP BY К.id
ORDER BY ОбщаяСумма DESC
"
КОЛОНКА Клиент СТРОКА
КОЛОНКА КоличествоЗаказов ЧИСЛО
КОЛОНКА ОбщаяСумма ЧИСЛО
ВЫВОД_ДИАГРАММА СТОЛБИКОВАЯ
ПОЛЕ_ДЛЯ_ДИАГРАММЫ Клиент
РЕСУРС ОбщаяСумма
КОНЕЦПример: Отчёт по журналу (остатки)
ОТЧЁТ СкладскиеОстатки
ПАРАМЕТР Склад ВЫБОР Склады
ЗАПРОС "
SELECT
Номенклатура,
SUM(_type * Количество) as ОстатокШт,
SUM(_type * Сумма) as СуммаНаСкладе
FROM Журнал_ОстаткиЗапчастей
WHERE 1=1
{{ЕСЛИ Склад}} AND Склад = '{{Склад}}' {{КОНЕЦ}}
GROUP BY Номенклатура
HAVING ОстатокШт != 0
"
КОЛОНКА Номенклатура ВЫБОР Номенклатура
КОЛОНКА ОстатокШт ЧИСЛО
КОЛОНКА СуммаНаСкладе ЧИСЛО
КОНЕЦ8.7. Важные ограничения
RLS не применяется автоматически: Отчёты не учитывают ограничения доступа из ролей. Добавляйте условия вручную:
ОТЧЁТ МоиЗаказы
ЗАПРОС "
SELECT id, Номер, Дата, ИтогоСумма
FROM ЗаказНаряд
WHERE Менеджер = {{ТЕКУЩИЙПОЛЬЗОВАТЕЛЬ().id}}
ORDER BY Дата DESC
"
КОЛОНКА id ЧИСЛО
КОЛОНКА Номер СТРОКА
КОЛОНКА Дата ДАТАВРЕМЯ
КОЛОНКА ИтогоСумма ЧИСЛО
КОНЕЦЭкранирование параметров: Для строковых параметров используйте кавычки вручную:
# Правильно
WHERE Наименование = '{{Наименование}}'
# Неправильно (вызовет ошибку SQL)
WHERE Наименование = {{Наименование}}Пустые параметры: Используйте конструкцию {{ЕСЛИ ...}} для необязательных параметров:
WHERE 1=1
{{ЕСЛИ Клиент}} AND Клиент = '{{Клиент}}' {{КОНЕЦ}}8.8. Best Practices
- Всегда используйте псевдонимы (AS) для колонок — они становятся заголовками в таблице
- Для необязательных параметров всегда используйте
{{ЕСЛИ ...}}— иначе пустой параметр сломает запрос - Не забывайте про кавычки для строковых параметров — это частая ошибка
- Для отчётов по журналам всегда используйте
SUM(_type * Ресурс)для расчёта остатка - Для больших отчётов добавляйте LIMIT — пользователи могут случайно выбрать огромный период
- Тестируйте SQL вручную перед добавлением в отчёт — используйте любой SQLite-клиент
- Помните про RLS — если данные должны быть ограничены, добавляйте
{{ТЕКУЩИЙПОЛЬЗОВАТЕЛЬ().id}}вручную - Для диаграмм с большим количеством категорий (>15) используйте СТОЛБИКОВУЮ или ЛИНЕЙНУЮ диаграмму, а не КРУГОВУЮ
- Если хотите дать пользователю выбор — показывать график или нет, добавьте параметр
ПАРАМЕТР ПоказыватьГрафик БУЛЕВОпервым в блоке отчёта (перед ЗАПРОС) - Напомните пользователям, что любую диаграмму можно сохранить как картинку через правую кнопку мыши