Отчёты — Администрирование

Справочник администратора домена отчётов (reports). Охватывает настройку отчётов, фильтров, прав доступа, импорт/экспорт пакетов отчётов, а также технику программирования FastReport-шаблонов и SQL-паттерны для источников данных. В документе собраны все административные интерфейсы (SPA-страница, редактор сущностей, API администрирования), критические инварианты FastReport, ограничения фильтров и типовые ошибки настройки с диагностическими запросами. За созданием и базовым процессом работы с отчётами — в academy-patterns.md; за диагностикой, Win-дизайнером и XLSX-экспортом — в support-guide-fastreport.md.

Механизмы администрирования

Домен reports охватывает настройку отчётов, фильтров, прав доступа и импорт/экспорт пакетов отчётов. Администрирование использует три механизма: пользовательскую SPA-страницу, редактор сущностей и API администрирования.

Пользовательская SPA-страница (в дереве автоадминки):

Alias формы	Название	Url	Таблица БД	Папка
reports	Отчеты	/administration/reports	dbo.Reports	Дополнительно

Редактор сущностей — три схемы JSON, каждая привязана к таблице БД:

Схема JSON	Таблица	Назначение
printForms	dbo.PrintForms	Печатные формы
registries	dbo.Registries	Реестры
registryColumns	(связанная)	Колонки реестров

API администрирования — четыре группы маршрутов для CRUD-операций с отчётами, фильтрами, правами и импортом/экспортом:

Маршрут	Методы	Назначение
/api/admin/reports	GET, POST, PUT, DELETE	CRUD отчётов, контексты
/api/admin/reports/filters	GET, POST, PUT, DELETE	CRUD фильтров и параметров
/api/admin/reports/{reportId:Guid}/*rights*	GET, POST, DELETE	Права групп (просмотр/редактирование/специальные)
/api/admin/reportstats	GET, POST	Экспорт/импорт пакетов отчётов

Ключевые настройки

Отчёты и контексты. Отчёты (Reports): Где настраивается: SPA-страница /administration/reports (пункт reports в дереве автоадминки) или API администрирования Таблица БД: dbo.Reports

Группы полей: карточка отчёта, описание, режим, шаблон.

Группа полей	Что контролирует
Имя, описание	Идентификация в интерфейсе
Режим отчёта	Внешняя форма / FastReports / внешняя отрисовка (подробнее — ниже)
Шаблон	Файл шаблона отчёта
Параметры	Настройки генерации

Как применяется: отчёт доступен пользователям через контекстное меню задачи/категории или через раздел отчётов.

Контексты отчёта (ReportContextObjects). Где настраивается: API администрирования (/{id}/context) Таблица БД: dbo.ReportContextObjects

Привязка отчёта к контексту использования. Определяет, где отчёт будет доступен. Значения поля Reports.Context: 0=Task, 1=Subcat, 2=Category, 3=User, 4=Group (подробнее: support-guide-fastreport.md секция 3.3, 8).

Режим отчёта (Reports.Mode). Обязательная колонка dbo.Reports; определяет, чем строится отчёт. Перечисление режимов состоит из трёх значений:

Значение	Режим	Чем строится отчёт
0	Внешняя форма	отдельная форма приложения; построителя у режима нет
2	FastReports	встроенный движок FastReport
3	Внешняя отрисовка	отдельный сервис отрисовки

Номер 1 в перечислении не определён: режим с этим номером снят, и операция смены режима такое значение не принимает. Пустого значения колонка не допускает. Режим проставляется автоматически при создании и копировании отчёта: если указано имя формы — внешняя форма, иначе FastReports. Обычное сохранение карточки режим не меняет.

Смена режима отчёта. Для смены есть отдельная операция административного API PUT api/admin/reports/{reportId}/mode; тело запроса — номер режима. Метод требует прав администратора платформы: при успехе отвечает 204 без тела, на неизвестный отчёт — 404, на недопустимый режим — 400, без прав — 403. Операция читает и пишет только колонку режима: остальные поля карточки она не перечитывает и не переписывает. Переключение допускается только между FastReports и внешней отрисовкой, причём проверяются оба конца — и текущий режим отчёта, и запрошенный. Отчёты внешней формы этой операцией не переводятся, и перевести отчёт в режим внешней формы ею тоже нельзя. В ответах административного API режим приходит числом: перечисление режимов на клиенте строковое, поэтому число переводится в название при разборе ответа, а при смене режима отправляется обратно числом.

Маршрут построения отчёта. Общая точка построения — POST api/reports/{reportId}/render. Маршрут проверяет право на сам отчёт и на объект контекста, берёт режим с записи отчёта и выбирает построитель, зарегистрированный на этот режим. Построитель должен быть ровно один: если для режима не зарегистрировано ни одного или их несколько, построение отклоняется с ошибкой конфигурации. Построители есть у FastReports и у внешней отрисовки; у режима внешней формы построителя нет, и такой отчёт маршрут не строит. Запрос уровня детализации (имя страницы шаблона и значения ячейки) принимает только внешняя отрисовка — построитель FastReports отклоняет его как ошибку конфигурации.

Канал к сервису отрисовки. Адрес сервиса задаётся пользовательской настройкой ReportingRenderServiceUrl, ключ подписи — секретом интеграции reportrender (поле Secret; секрет внутренний, смарт-скриптам он не отдаётся). Обе настройки обязательны: без адреса или без секрета построение отклоняется с ошибкой конфигурации ещё до обращения к данным.

Задание рендера собирает ядро. В него входят идентификатор построения, тело шаблона отчёта, культура, имя страницы, перечень страниц детализации, наборы данных (псевдоним, внутреннее имя, колонки с типами, строки) и параметры (имя, тип, значение). Задание сериализуется в JSON, сжимается gzip и уходит методом POST на /render по адресу сервиса. Сам секрет по сети не передаётся: запрос подписывается HMAC-SHA256 по каноническим байтам, а в заголовках идут версия схемы подписи, время выпуска, одноразовый номер и подпись. Сервис принимает подпись с расхождением времени не больше минуты и хранит одноразовые номера две минуты, поэтому перехваченный запрос повторить нельзя.

Число строк, которое ядро запрашивает у источника данных, ограничено пользовательской настройкой ReportingRowLimit (по умолчанию 10000). Время ожидания ответа сервиса берётся из параметра конфигурационного файла FastReportCommandTimeoutSeconds; если он не задан или неположителен, действует минута.

Процессы сервиса отрисовки. Документ строится не в основном процессе сервиса, а в дочерних процессах-воркерах; каждый воркер одновременно строит один отчёт. Число воркеров, предел памяти и время подготовки документа задаются в конфигурации сервиса отрисовки или переменными окружения:

Параметр	Переменная окружения	Что задаёт	По умолчанию
ReportingRender:WorkerCount	REPORTING_RENDER_WORKER_COUNT	число воркеров, не меньше 2	2
ReportingRender:WorkerGcHeapHardLimitBytes	REPORTING_RENDER_WORKER_GC_HEAP_HARD_LIMIT_BYTES	предел управляемой кучи одного воркера в байтах	не задан
ReportingRender:PrepareTimeoutSeconds	REPORTING_RENDER_PREPARE_TIMEOUT_SECONDS	время на подготовку документа, от 1 до 59 секунд	40

С недопустимым значением любого из этих параметров сервис не запускается. Если документ не подготовлен за отведённое время, построение прерывается: процесс воркера останавливается и запускается заново, а пользователь получает «Отчёт слишком тяжёлый. Сузьте отбор.» Запросы сверх числа воркеров ждут в очереди, мест в которой вдвое больше, чем воркеров. Если очередь заполнена или воркер не освободился за 10 секунд, сервис отвечает, что занят; пока какой-либо воркер перезапускается, запрос не получает отказ, а ждёт его. Устройство сервиса — в backend.md.

Сбой сервиса отрисовки. Исход построения пользователь видит по-разному в зависимости от того, что именно не сошлось:

Что произошло	Что видит пользователь
Сервис не отвечает, соединение не устанавливается, прочий сбой канала	«Сервис отрисовки недоступен.»
Ядро не дождалось ответа за отведённое время; сервис ответил своим таймаутом, отказом по размеру задания или сбоем процесса-воркера	«Отчёт слишком тяжёлый. Сузьте отбор.»
Сервис ответил, что занят	«Сервис отчётов занят, повторите через минуту»
Не задан адрес или секрет, пустой ответ сервиса, нет построителя для режима, для запрошенной страницы детализации не настроен источник	текст ошибки конфигурации
Сервис сообщил об ошибке шаблона	текст, который вернул сервис

Кроме текста в ответе идёт машинный признак вида ошибки — клиенту не нужно разбирать сообщение. Отказ по доступу отдаётся статусом 403; остальные виды ошибок приходят обычным статусом 200, разметки отчёта в таком ответе нет.

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

Фильтры и права доступа. Фильтры отчёта: Где настраивается: API администрирования (фильтры отчёта) Таблицы БД: dbo.ReportFilterLinks, таблицы Filter*

Форма фильтра: набор параметров и их порядок. Параметры определяют пользовательский ввод перед генерацией.

Права доступа: Где настраивается: API администрирования (права отчёта) Таблицы БД: dbo.ExternalObjects* (таблицы прав)

Видимость и редактирование отчёта по группам. Без прав отчёт не виден пользователям.

Печатные формы и реестры. Печатные формы: Где настраивается: редактор сущностей → printForms Таблица БД: dbo.PrintForms

Шаблоны документов для печати (Word/Excel), привязанные к категориям.

Реестры: Где настраивается: редактор сущностей → registries, registryColumns Таблица БД: dbo.Registries

Структура и колонки реестров, доступных для просмотра/экспорта.

Работа с отчётами на странице администрирования

Отчёты системы настраиваются на SPA-странице /administration/reports (пункт «Отчёты» в дереве автоадминки). Ниже — основные операции: просмотр списка, создание, редактирование настроек, действия с отчётом, импорт/экспорт, настройки экспорта и логирование.

Список отчётов

На странице отображается список всех настроенных в системе отчётов. Сами отчёты разрабатываются в дизайнере FastReport (см. §«FastReport: обязательные инварианты»).

Колонка «Режим» показывает, чем строится отчёт: «Внешняя форма», «FastReports» или «Внешняя отрисовка». По этим названиям список можно сортировать и фильтровать.

Подписи, диалоги и уведомления этой страницы показываются на языке интерфейса пользователя; как выбирается язык, если перевода нет, — см. localization/admin.md. Названия самих отчётов и значения фильтров задаёт администратор, они показываются так, как введены, и от языка интерфейса не зависят.

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

Чтобы создать новый отчёт, сначала заведите его в системе: нажмите «Создать» и укажите название, описание, блок и при необходимости порядок отчёта в блоке. После этого отчёт можно открыть в дизайнере FastReport и оформить его содержимое.

Редактирование настроек отчёта

Чтобы изменить описание и основные параметры отчёта, нажмите на него в списке.

Основные настройки отчёта:

Параметр	Описание
Название	Название отчёта
Описание	Описание отчёта
Контекст	Привязка отчёта к контексту использования (см. таблицу ниже)
Скрыт	Видимость отчёта
Порядок	Порядок отчёта в блоке
Системный	Признак системного отчёта

Режим отчёта. В карточке открытого на редактирование отчёта доступен выбор режима — «FastReports» или «Внешняя отрисовка». Поле показывается, только если отчёт уже в одном из этих режимов; у отчётов внешней формы его нет, и при создании отчёта режим не запрашивается. Выбранное значение применяется сразу, отдельно от кнопки сохранения: на время смены поле недоступно, при успехе обновляется и карточка, и список отчётов, при отказе возвращается прежнее значение и показывается сообщение об ошибке.

Источники отчёта. У отчёта в режиме внешней отрисовки в карточке доступен блок «Источники отчёта»: идентификатор источника, его тип — расширенный поиск задач, зарегистрированный источник или источник без данных, — сам источник, псевдоним и внутреннее имя набора данных, страница шаблона и порядок. Кнопка добавления и клик по строке открывают экран настройки источника — там задаются карта имён, сопоставление фильтров, а у источника вида «расширенный поиск задач» ещё и набор его категорий. Удаление запрашивает подтверждение и сообщает, сколько записей карты имён и сопоставлений удалено вместе с источником. У отчётов остальных режимов блока нет.

Пустые значения в документе. В режиме внешней отрисовки отсутствующее значение даты печатается пустой ячейкой, а не минимальной датой 01.01.0001. Заданные даты выводятся как прежде. Для остальных типов правило не менялось: отсутствующая строка печатается пустой, отсутствующие целое и дробное — нулём (0 и 0,00).

Язык встроенных надписей. Файл локализации FastReport сервис отрисовки не подключает, поэтому встроенные тексты самого движка FastReport выводятся на английском языке независимо от языка пользователя. Тексты, заданные в шаблоне, и данные это не затрагивает.

Контексты отчёта. Контекст определяет, откуда отчёт вызывается и какие параметры в него передаются. Во все отчёты дополнительно передаётся ID открывшего отчёт пользователя (CurrentUserID) — для проверки прав на просматриваемые данные.

Контекст	Параметры	Откуда вызывается	Что настраивается
0 — Задача	TaskID, SubcatID	Меню «Ещё» в карточке задачи	Категории/разделы, в которых отчёт доступен
1 — Категория	SubcatID	Контекстное меню категории	Категории/разделы (сейчас не используется)
2 — Раздел	CategoryID	Контекстное меню раздела	Разделы (сейчас не используется)
3 — Пользователь	UserID	Меню «Подробно» в профиле пользователя	Доступен из профиля любого пользователя с правом просмотра
4 — Группа	коллекция UserID + GroupID	Меню «Подробно» в составе группы	(сейчас не используется)

Проверка контекста при построении. Если у отчёта задан тип контекста, построение без идентификатора объекта запрещено: нулевой или непереданный идентификатор отклоняется отказом в доступе, а не строит отчёт без ограничения выборки. Тип контекста в запросе должен совпадать с типом, заданным в свойствах отчёта, — при расхождении построение отклоняется независимо от идентификатора. Право на объект контекста проверяется по его типу: для задачи — доступ к задаче, для категории — любое право в ней, для раздела — любое право хотя бы в одной из его категорий, для группы — членство в ней. Для контекста «Пользователь» отчёт можно построить по себе, а по другому сотруднику — только имея доступ к его карточке: полные права администратора, отсутствие запрета на просмотр сведений о пользователях или межгрупповое право на просмотр общей информации. Отказ из-за непереданного объекта сопровождается текстом «Отчёт строится из карточки задачи.» — с типом объекта из свойств отчёта (категории, раздела, пользователя, группы); остальные отказы по доступу обезличены: «нет права на построение отчёта». Тот же обезличенный отказ получают запрос к несуществующему отчёту и запрос с объектом контекста к отчёту без типа контекста. Код ответа в обоих случаях — 403. Каждый отказ пишется в журнал сервера с идентификаторами построения, отчёта и пользователя и причиной: ContextRequired, ContextTypeMismatch, ReportNotVisible и другие.

⚠️ Контроль прав пользователя на данные, которые показывает отчёт, возложен на разработчика отчёта.

Действия с отчётом: онлайн-редактор, Win-дизайнер, права

В строке отчёта по кнопке действий открывается меню: настроить права доступа и перейти к редактированию — онлайн или на своём устройстве.

Онлайн-редактор. Открывает отчёт в онлайн-редакторе FastReport прямо в браузере.

Win-дизайнер. Открывает отчёт в десктоп-дизайнере FastReport (его нужно предварительно установить; для работы требуется .NET Framework 4.6.1). Дизайнер поставляется .zip-архивом в служебной категории «Репозиторий версий приложения».

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

Импорт и экспорт отчётов

Для переноса отчётов между инсталляциями используется импорт/экспорт. Отчёты переносятся вместе с фильтрами, смарт-выражениями и частично с настройками контекста. Кнопка «Импорт/экспорт» над списком открывает окно выбора.

Порядок работы:

• Экспорт — выделите нужные отчёты (несколько — с зажатым Shift) и нажмите «Экспортировать». Создаётся архив (по умолчанию report_export.zip) с набором XML-файлов.
• Импорт — нажмите «Выбрать файл», укажите архив и нажмите «Импортировать». Отчёты добавятся вместе с фильтрами; тип контекста сохранится, но сами объекты контекста и права доступа нужно настроить заново.

⚠️ Если отчёт с таким же GUID уже есть в системе — он будет заменён новым, с потерей привязки к объектам контекста.

Настройки экспорта

В пользовательском режиме отчёт можно выгрузить в файл — у каждого формата свои настройки.

В режиме администрирования параметры выгрузки настраиваются для четырёх форматов — по кнопке в колонке «Настройки экспорта».

Формат	Настройки
Docx	Тип экспорта (табличный / послойный / абзацы); высота строки (совпадает / минимальна); Wysiwyg; оптимизированная печать
Xlsx	Wysiwyg; разрывы страниц; только данные; без разрывов таблицы; оптимизированная печать
Rtf	Wysiwyg; разрывы страниц; формат картинок (нет / PNG / JPEG / метафайл — по умолчанию .EMF)
Ppt	Формат картинок (PNG / JPEG)

⚠️ Для корректного экспорта в Excel элементы отчёта в дизайнере FR обязательно должны быть привязаны к рабочей области (сетке).

Логирование действий с отчётами

Действия с отчётами фиксируются в общем системном журнале: редактирование основных настроек отчёта, правка содержимого в онлайн-редакторе и Win-дизайнере, импорт и экспорт, а также изменения условий фильтрации (добавление, редактирование, удаление).

Типичные ошибки настройки

Частые проблемы настройки отчётов и способы их диагностики:

Симптом	Причина	Где проверить	SQL-диагностика
Отчёт есть в админке, но не виден пользователю	Не настроены права на группу пользователя	Права отчёта	select * from dbo.ExternalObjectsViewRights where ExternalObjectId = (select ExternalObjectId from dbo.Reports where id = {reportId})
Фильтр отчёта пустой/неверный	Некорректные ReportFilterLinks или порядок параметров	Фильтры отчёта	select * from dbo.ReportFilterLinks where ReportId = {reportId}
После импорта отчёт работает некорректно	Частично перенесённые связи фильтров/прав	Целостность связок	Проверить ReportFilterLinks, ExternalObjects* для импортированного отчёта
Отчёт не виден в контекстном меню	Не привязан контекст	Контекст отчёта	select * from dbo.ReportContextObjects where ReportID = {reportId}

FastReport: обязательные инварианты

FastReport-отчёт — административная настройка, в которой администратор создаёт карточку отчёта, права, контекст, фильтр, шаблон и параметры экспорта. Пошаговый процесс создания отчёта и базовые источники данных уже описаны в academy-patterns.md, практический чеклист Win-дизайнера и диагностики — в support-guide-fastreport.md.

⚠️ Критично: для новых FR-отчётов в пользовательских custom-app-settings должен быть включён параметр useNewFRReports=true. Без этой настройки новый FR-контур не открывает отчёты корректно.

Печать отчёта нового FR-контура. На лист выводится только область документа: боковое меню, шапка приложения и полоса уровней детализации не печатаются. Печатается тот уровень детализации, который открыт. Печать вызывается кнопкой «Печать» над документом или средствами браузера — подготовка листа в обоих случаях одинакова. Документ шире листа уменьшается, чтобы уместиться целиком, но не мельче 40 %: если и при таком масштабе он не помещается, правая часть на лист не попадёт. Документ уже листа не растягивается. Поле от края листа — 8 мм.

⚠️ MSSQL и PostgreSQL не взаимозаменяемы: отчёт, созданный на MSSQL, содержит источник данных MSSQL. При переносе на PostgreSQL FastReport продолжит пытаться подключаться к старому источнику, что приводит к ошибкам. Для PostgreSQL нужен отдельный отчёт с отдельным источником данных; автоматического переключения SQL-диалекта нет.

⚠️ Права на данные внутри отчёта — ответственность разработчика отчёта. Права видимости отчёта и права на данные в SQL-источнике — разные уровни. CurrentUserID передаётся автоматически, но SQL отчёта должен сам применять его для фильтрации данных.

Дизайнер, контексты и автоматические параметры

FastReport-отчёт открывается в одном из трёх дизайнеров:

Дизайнер	Как открыть	Ограничения
Win-дизайнер	действие «Win-дизайнер» у отчёта	ссылка на скачивание из интерфейса больше не предоставляется; ZIP берётся из служебной категории «Репозиторий версий приложения»; нужен .NET Framework 4.7.1; SQL-сервер должен быть доступен с машины дизайнера
Онлайн-дизайнер Task Center	/MVC/ReportDesigner/{id}	доступен администраторам
Онлайн-дизайнер .NET Core	/reportdesigner/{id}	Доступен только администраторам системы (god-права); права на просмотр или редактирование отчёта конструктор не открывают. Остальным возвращается «Доступ запрещён»

Для сетевых требований Win-дизайнера см. support-guide-fastreport.md. Для 7-шаговой последовательности создания отчёта см. academy-patterns.md.

CurrentUserID передаётся во все отчёты автоматически. Этот параметр нужен не для интерфейса, а для SQL/скриптов отчёта: по нему разработчик отчёта ограничивает данные правами текущего пользователя.

Контексты, в которых отчёт доступен пользователю:

Context	Где доступен отчёт	Автоматические параметры	Особенности настройки
0 Task	карточка задачи, меню «Ещё» / отчёты	TaskID, SubcatID	можно ограничить доступность отчёта категориями/разделами
1 Subcat	контекст категории	SubcatID	используется для отчётов по категории
2 Category	контекст раздела	CategoryID	в старом руководстве помечен как неиспользуемый сценарий
3 User	профиль пользователя	UserID	список доступных значений не настраивается; доступ определяется правом просмотра отчёта
4 Group	просмотр состава группы	коллекция UserID + GroupID	в старом руководстве помечен как неиспользуемый сценарий

Все параметры отчёта применяются совместно: контекстные параметры, CurrentUserID и параметры фильтра не отменяют друг друга.

Фильтры FR: параметры и пустые значения

Базовые фильтры «Период» и «Выпадающий список» уже разобраны в academy-patterns.md. Ниже — правила, которые критичны именно для администратора/разработчика FR-шаблона.

Передача значений фильтра в отчёт. Незаполненный фильтр в отбор не передаётся: параметр просто отсутствует, а не приходит пустым. Выбор всех значений равнозначен незаполненному фильтру, если список значений параметра задан статическим набором или источником без смарт-выражения; для параметра со смарт-списком действует другое правило — см. подраздел ниже. Множественный выбор передаётся списком значений. У скрытого параметра при отсутствии значения используется значение по умолчанию; пустая строка и ноль считаются заданными значениями, а не отсутствием. Правило действует на странице отчёта; в виджетах и других местах фильтры передаются как прежде. Если отчёт открыт с сохранённым набором фильтров, порядок источников такой: явно переданное значение перекрывает значение из набора, а параметры, которых нет ни там, ни там, добирают собственные умолчания.

Именование параметров и ограничения выпадающего списка

Соответствие имён параметров между настройкой фильтра и FastReport:

Тип фильтра	Имя в настройке фильтра	Параметр в FastReport
Строка / Число / Выпадающий список / Пользователь / Группа / Категория / Оргструктура	Name	FilterName
Период	Period	FilterPeriodFrom, FilterPeriodTo

Для SQL-параметров дат обычно нужен тип DateTime. Для числовых ID, которые приходят из выпадающего списка как строка, безопасный вариант — оставить параметр запроса VarChar и дать SQL Server выполнить преобразование в запросе.

Удаление параметров фильтра. Параметр нельзя удалить, если он используется в сопоставлениях источников данных отчётов: система отклоняет удаление и перечисляет, где параметр задействован. Это относится и к удалению фильтра целиком — вместе с ним удаляются его параметры. Сначала уберите ссылки в сопоставлениях, затем удаляйте.

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

Обходное решение — убрать ключевое слово EXEC из смарт-выражения фильтра и переписать источник в виде:

SELECT * FROM (...)

В таком виде поиск по значениям фильтра работает корректно.

Передача значений: пустые, default и вызов из строки

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

Тип фильтра	Если значение выбрано	Если значение не выбрано
Строка	строка	null
Число	число	null
Дата	дата	null
Период	две даты: Filter<Name>From, Filter<Name>To	null для открытого начала/конца
Выпадающий список	строка; при мультивыборе — значения через запятую без пробелов	null
Пользователь / Группа / Оргструктура / Категория	строка ID через запятую без пробелов	пустая строка "", не null

⚠️ Фильтры Пользователь/Группа/Оргструктура/Категория всегда мультивыборные. Их нельзя штатно ограничить одним значением; SQL должен принимать строку ID.

⚠️ Фильтр по категориям не заменяет проверку прав в SQL. В самом фильтре пользователь видит только категории, где у него есть хотя бы одно из прав: «Просматривать все задачи», «Создавать задачи», «Исполнять», «Администратор задач», «Администратор категории». Если пользователь выбирает раздел, в отчёт передаётся список доступных ему категорий раздела. Но если пользователь не выбрал ни одной категории/раздела, контроль прав полностью остаётся на SQL отчёта.

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

1. вручную создать параметр в дизайнере с нужным типом и именем Filter<Имя> или Filter<Имя>From/Filter<Имя>To, затем сохранить отчёт;
2. временно задать в фильтре непустой default, открыть отчёт в дизайнере, убедиться что параметры созданы, сохранить отчёт, затем вернуть пустой default.

Для открытого периода default SQL-параметров подбирается так, чтобы не отсечь реальные данные. Типовой нижний default:

@from = '01.01.1900'

SQL-условие для открытого периода:

WHERE (@from IS NULL OR t.Date >= @from)
  AND (@to   IS NULL OR t.Date <= @to)

«Все» в мультивыборе: параметр со смарт-списком

Пункт «Все» в мультивыборе означает все значения списка этого параметра, а не отсутствие ограничения по нему.

Если список значений задаёт смарт-выражение, при построении отчёта признак «Все» раскрывается в результат того же выражения, что наполняет список фильтра:

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

Признак «Все» строкой в запрос отчёта не передаётся: параметр приходит уже раскрытым набором значений либо отсутствует. Параметр, список которого задан без смарт-выражения, со значением «Все» в отбор не передаётся — отчёт строится так же, как без этого параметра. Если при активном признаке «Все» не удаётся получить настройки фильтра или результат смарт-выражения, построение завершается ошибкой настройки отчёта, а не отчётом с расширенным отбором.

Параметры фильтра в строке вызова

Для прямого вызова отчёта значения фильтров передаются в формате f{paramID}_{Name}_v=.... Значение из строки вызова имеет приоритет над default в фильтре. Имя параметра регистрозависимо.

Тип параметра	Пример
строка	f11_Mod_v=test
число	f11_Mod_v=2
дата	f11_Mod_v=25.06.2018
период	f11_Mod_v=from:25.06.2018;to:20.06.2018
пользователь / оргструктура / выпадающий список / группа / категория	f11_Mod_v=1,2,3
режим «только для чтения»	f11_r=1

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

Уровни отчёта: итоги и агрегаты на основной и детальной страницах

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

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

Если у итога в Evaluator указана несуществующая полоса, отчёт останавливается на ошибке конфигурации, и в сообщении названы имя итога, страница, набор данных и сама указанная полоса — вместо общего «Report template failed», по которому причину приходилось искать чтением XML шаблона.

Техники программирования в FastReport

Тернарный оператор, преобразование типов и итоги в заголовке

⚠️ Не использовать IIf() для защиты от null при форматировании. IIf() вычисляет все ветки до выбора результата, поэтому форматирование null всё равно падает. Тернарный оператор вычисляет только нужную ветку.

IsNull("FilterPeriodFrom") ? "-" : FormatDateTime([FilterPeriodFrom])

Для строки периода применяйте тот же принцип отдельно к началу и окончанию периода.

В рамках одного отчёта тип параметра должен быть одинаковым во всех местах использования. Числовые константы должны соответствовать ожидаемому типу: например, для Double используйте 60.0, а не 60.

Если итог по группе выводится в заголовке, а не в подвале группы:

Настройка	Значение
итоговое поле	ProcessAt = GroupFinished
объект Report	DoublePass = True
поле названия группы	ProcessAt = Default

Название группы и итог должны быть разными объектами. Название печатается на первом проходе, итог — после завершения группы.

Детальная страница, вызов с кнопки и восстановление из .FRX

Для перехода из основного отчёта в детальную страницу FastReport передаёт значения через гиперссылку. Если нужно передать список ID, не используйте запятую: FastReport трактует её как разделитель разных параметров. Практичный разделитель — _.

111_222_333

Название вкладки детальной страницы формируется автоматически из переданных параметров и вручную не задаётся.

Явное значение в ссылке детализации (внешняя отрисовка). В шаблоне отчёта с внешней отрисовкой значение для детализации можно передать напрямую, а не восстанавливать по раскладке таблицы. В свойствах гиперссылки ячейки задаются два поля: Hyperlink.Expression — выражение по колонкам родительского набора, например [main.TaskID], и Hyperlink.ReportParameter — имя параметра, например TaskKey. Заполняются оба поля: без любого из них ссылка строится как раньше. Служба отрисовки считает выражение в контексте строки набора и добавляет значение в ссылку — #report-drill/{страница}?{имя}={значение}, имя и значение кодируются в адресе. Имя параметра должно совпасть с полем «Имя ячейки» записи сопоставления источника страницы детализации, у которой вид значения — «Значение из ячейки набора»; тогда детализация отбирает данные по этому значению. У ячейки матрицы оба поля заполняются так же, но выражение пишется по измерениям самой матрицы — тем, что объявлены в её строках и колонках, например [Table.mat_year] для измерения строки и [Table.mat_month] для измерения колонки, — а имя набора в ссылке на измерение можно и не указывать: [mat_year]. Такое выражение служба отрисовки считает в контексте конкретной ячейки — по значениям измерений её строки и колонки, — и в ссылку попадает значение именно этой ячейки: ячейки разных строк получают значения своих строк, а две ячейки одной строки в разных колонках — разные значения. Поэтому ключ детализации не зависит от раскладки колонок. Если у ячейки матрицы Hyperlink.ReportParameter не задан, ссылка строится как раньше — без значения; так же она строится, когда выражение не удаётся связать с измерениями матрицы: ссылка не на измерение (мера), неизвестное или неоднозначное измерение, незакрытая кавычка.

Для кнопки в карточке задачи обычно используется контекст «Задача». JavaScript-выражение открывает просмотр отчёта и передаёт TaskID как contextId:

window.open('/reports/view/{reportId}?contextId=' + TaskID, '_newtab');

Локальная копия шаблона FastReport сохраняется в .FRX. Восстановление через начальный экран дизайнера полностью заменяет содержимое отчёта в БД. Перед восстановлением нужно понимать, что текущий ContentXml будет перезаписан.

SQL-паттерны для FR-источников

Базовый пример SQL-источника и гиперссылки на задачу есть в academy-patterns.md и academy-patterns.md. Ниже — паттерны, которые нужны для нетривиальных отчётов.

Гиперссылки, HTML-очистка и служебные категории

Два способа построения гиперссылок на карточки задач:

Способ	Когда использовать	Пример
Выражение в свойстве гиперссылки	когда идентификатор задачи есть в источнике данных	["/spa/tasks/" + ToString([Table.TaskID])]
Относительный URL из SQL-источника	когда не хочется добавлять Settings как источник	сформировать URL в SQL и выбрать готовое поле в настройках гиперссылки

Для профиля пользователя используется тот же подход с UserID.

Ссылки старого формата. Адрес вида MainTaskForm.aspx?TaskID= в шаблоне при отрисовке документа заменяется на относительный /spa/tasks/{номер} — в том числе когда перед ним стоит [Settings.ApplicationPath] + или полный адрес этой же площадки. Шаблон в базе при этом не меняется. Адрес с номером задачи не из цифр и ссылка на другую установку остаются как есть, вторая пишется в лог службы отрисовки.

Если в категории разрешён HTML в тексте задачи, FastReport может некорректно отрисовать неполный HTML. Для плоского текста используйте SQL-функцию очистки:

SELECT dbo.fnStripTags(T.TaskText) AS TaskText
FROM TasksInSubcat11Denormalized T

Альтернативные функции, которые встречаются в отчётах: cm_StripHTML, cm_ReplaceHTML, cm_ReplaceEverything.

Полный путь категории хранит разделитель Fraction Slash ⁄ (U+2044). В SQL используйте NCHAR(8260):

SELECT REPLACE(Subcategories.FullPath, NCHAR(8260), '\\') AS SubcatName
FROM Subcategories

Чтобы отчёт переносился между инсталляциями, не зашивайте ID служебных категорий. Добавьте Settings как источник данных и используйте поля:

Поле Settings	Категория
CalendarSubcatID	календарь
ChatSubcatID	общение / чаты
PrivateSubcatID	личные задачи

Для исключения задач из этих категорий передайте строку ID и проверяйте SubcatID через CHARINDEX или LIKE.

Мультивыбор в SQL и список выбранных значений в шапке

Параметр мультивыбора приходит строкой ID через запятую. Перед проверкой удобно добавить запятые в начало и конец строки: ,123,456,789,. Пустой выбор после такой нормализации даёт ,,.

WHERE (@subcat = ',,')
   OR (CHARINDEX(',' + CAST(T.SubcatID AS varchar(max)) + ',', @subcat) > 0)

Альтернативный вариант — табличная функция GetMultiValues:

WHERE (@subcat = ',,')
   OR (CAST(T.SubcatID AS varchar(max)) IN (
        SELECT [Value]
        FROM dbo.GetMultiValues(@subcat, ',')
   ))

В коде отчёта для строковых значений можно проверять вхождение через .ToString().Contains(...).

Для вывода выбранных категорий/пользователей/групп в шапке используйте отдельный SQL-источник с FOR XML PATH('') и той же проверкой CHARINDEX:

SELECT
  (SELECT REPLACE(S.FullPath, NCHAR(8260), '\\') + '; '
   FROM Subcategories S
   WHERE CHARINDEX(',' + CAST(S.SubcatID AS varchar(max)) + ',', @subcat) > 0
   FOR XML PATH('')) AS SubcatNames
FROM Subcategories

Если нужно вывести каждый элемент с новой строки, добавьте <br/> в SQL и после FOR XML PATH верните экранированные символы обратно. Для поля FastReport должен быть включён режим HTML-тегов.

SELECT REPLACE(REPLACE(
  (SELECT G.Descr + ', <br/>'
   FROM Groups G
   WHERE CHARINDEX(',' + CAST(G.GroupID AS varchar(max)) + ',', @GroupID) > 0
   FOR XML PATH('')),
  '&lt;', '<'), '&gt;', '>') AS GroupNames
FROM Groups

Рабочие минуты и Excel-формулы

Для рабочих минут используйте SQL-функцию:

dbo.tc_DiffWorkingMinutes(StartTime, EndTime)

Для отображения результата строкой в C#-коде отчёта обычно используется функция diff_str(int WMinutes), которая берёт Settings.WorkMinutesInDay и возвращает строку вида X дн. X ч. X мин.. Таблица Settings должна быть добавлена как источник данных.

Для генерации формул Excel из FR используется вспомогательная C#-функция ColumnNumberToName(int), возвращающая имя колонки (1 -> A, 2 -> B). Если порядок пересчёта формул важен, в начало формулы добавляют цифру очереди (1=..., 2=...) и затем запускают макрос .xlam AddIn, который сортирует и применяет формулы.

Дизайн FR-шаблонов и экспорт

Подробные режимы XLSX-экспорта (Wysiwyg, DataOnly, Seamless, PrintOptimized), настройки ExportSettings и API экспорта уже описаны в support-guide-fastreport.md. Здесь зафиксированы правила дизайна, которые влияют на корректность вывода.

Excel-сетка и матрицы

⚠️ Для Excel элементы отчёта обязательно привязывать к сетке. Если объекты не выровнены по одной сетке или пересекаются, FastReport создаёт лишние строки/столбцы и объединённые ячейки. После завершения шаблона включите привязку к сетке и выровняйте все элементы.

В обычных полях условное выделение может читать Value, Text или значения других ячеек. В матрицах порядок вычисления ячеек зависит от Layout (DownThenAcross / AcrossThenDown), поэтому чтение соседней ячейки в условии может быть нестабильным. Надёжнее читать исходное значение из DataSource, а не из уже отрисованной ячейки.

Для pivot/матрицы свойства Visible=false часто недостаточно. Для скрываемой колонки/строки применяйте одновременно:

Свойство	Значение
Width / Height	0
Autosize	False
MinWidth / MinHeight	0
Padding	убрать отступы по соответствующей оси

Макет страницы: Unlimited height/width и «таблица в таблице»

Unlimited height отключает вертикальную пагинацию в браузере. Unlimited width нужен для широких матриц, которые растут по горизонтали. Настройка задаётся отдельно для каждой страницы отчёта.

FastReport не поддерживает вложенные таблицы как отдельные объекты. Для макета «таблица в таблице» используйте обычную таблицу для центральной части и текстовые поля по краям. У повторяющихся текстовых полей выставляется Duplicates=Merge, чтобы визуально получить объединённые вертикальные заголовки.

Интерактивность и изображения

Спойлер собирается из CheckBox, гиперссылки со значением группы, BeforePrint у заголовка группы и Click у чекбокса. В Click меняется список раскрытых групп и вызывается Report.Refresh().

⚠️ Клик по спойлеру полностью перезагружает отчёт. Для тяжёлых отчётов и больших наборов данных спойлеры использовать нельзя: пользователь будет ждать повторного формирования отчёта.

Изображения для объекта Picture можно брать из таблицы UploadFiles файлового провайдера. Для вложений задачи используется провайдер по умолчанию (FileProviders.UseToWriteFiles = 1), для файлового ДП — провайдер из ExtParamsFileSettings или провайдер по умолчанию.

Ключевые таблицы связки:

Сценарий	Таблицы
файлы задачи	FileStorageFileToTaskLinks, FileStorageFileVersions, {FileProviderDb}.dbo.UploadFiles
файлы ДП	FileStorageFileToExtParamLinks, FileStorageFileVersions, {FileProviderDb}.dbo.UploadFiles

В старом руководстве отдельно указано, что для корректного отображения изображений у используемого файлового провайдера не должно быть включено сжатие данных. Если изображения хранятся в файловом ДП, для него можно выделить отдельный провайдер без сжатия.

Прочие дизайн-приёмы:

Приём	Правило
сортировка по клику	менять DataBand.Sort в обработчике Click; работает только на главной странице отчёта, не на детальных страницах
кликабельная шапка сортировки	шапка столбца должна быть текстовым полем (Label), не ячейкой таблицы
несколько страниц в документе	чтобы новая страница продолжила печататься на текущей странице, включить PrintOnPreviousPage
текстовый экспорт печатных форм	RTF обычно лучше сохраняет форматирование, переносы и нестандартные шрифты, чем DOCX/PDF

Импорт, экспорт и форматы выгрузки

Экспорт отчётов создаёт ZIP-архив с XML-файлами. При импорте отчёты добавляются вместе с фильтрами; тип контекста переносится, но конкретные объекты контекста нужно указать заново. Права доступа после импорта также настраиваются заново.

⚠️ Совпадение отчётов проверяется по GUID. Если импортируемый отчёт имеет GUID уже существующего отчёта, старый отчёт заменяется новым. Привязки к объектам контекста при этом теряются.

Для локального восстановления одного шаблона используется .FRX из Win-дизайнера; это не то же самое, что пакетный экспорт/импорт отчётов через админку.

Настройки экспорта по форматам:

Формат	Настройки	Примечания
Docx	тип экспорта: табличный / послойный / абзацы; высота строки: совпадает / минимальна; Wysiwyg; оптимизированная печать	табличный экспорт кладёт каждый абзац в отдельную ячейку; послойный — в текстовые поля; абзацы — форматированный текст
Xlsx	см. support-guide-fastreport.md	не дублируется здесь: режимы и API уже описаны в support-guide
Rtf	Wysiwyg; разрывы страниц; картинки: нет / PNG / JPEG / метафайл	метафайл .EMF — default и лучший вариант для качества диаграмм
Ppt	картинки: PNG / JPEG	используется для презентационного вывода

Готовые отчёты и ограничения прав

В поставке есть 35 типовых отчётов. Они полезны как готовый инструмент и как примеры FR-шаблонов, но имеют отдельное ограничение прав.

⚠️ В готовых отчётах права на задачи проверяются частично. Списки задач внутри отчёта могут содержать задачи, на просмотр которых у пользователя нет прав. Проверка прав сработает только при переходе по гиперссылке в карточку задачи; отдельные задачи могут не открыться.

⚠️ Совместимость: корректная работа готовых отчётов поддерживается с SQL Server 2014; SQL Server 2012 — ограниченно.

Список типовых отчётов:

№	Отчёт
1	Аудит доступа к задаче
2	Время активности пользователей в системе
3	Время активности пользователя в системе
4	Диаграмма Ганта по отсутствиям
5	Журнал регистрации действий пользователей
6	Задачи, не выполненные за рекомендуемый срок
7	Занятость сотрудников в группах за период
8	Информация по просроченным задачам
9	Использование дискового пространства
10	История доступа к файлам
11	Итоги дня
12	Нарушения регламентов работы с задачами
13	Общая статистика по задачам
14	Отчёт по входу сотрудников в 1Форму
15	Отчёт по переносам сроков
16	Отчёт по статусам
17	Поставленные задачи на группу
18	Просроченные задачи для пользователя
19	Работа по поставленным задачам
20	Статистика загрузки сотрудника
21	Статистика исполнения задач группой для орг.единиц
22	Статистика использования мобильных приложений
23	Статистика по акцептантам
24	Статистика по подписям
25	Статистика по просроченным задачам
26	Статистика по сотруднику за период
27	Табель трудозатрат
28	Табель трудозатрат по задаче
29	Табель трудозатрат по категории
30	Табель трудозатрат по проекту
31	Табель трудозатрат по сотруднику
32	Трудозатраты по задачам
33	Трудозатраты по задачам категории
34	Трудозатраты по задачам проекта
35	Трудозатраты по сотруднику

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

Источник данных отчёта настраивается на отдельном экране в администрировании отчётов. Под формой настроек источника расположена карта имён — таблица, которая связывает поля источника с именами колонок набора данных: по этим именам к данным обращается шаблон отчёта.

Добавление источника. Источник заводится на том же экране: указываются вид источника, псевдоним и внутреннее имя набора данных — эти три поля обязательны, — а также ссылка на источник и страница шаблона. После создания источник открывается для настройки карты имён и сопоставления фильтров.

Синхронизация с шаблоном. Настроенные источники можно привести в соответствие с текущим шаблоном отчёта: операция создаёт недостающие источники, дополняет карты имён новыми колонками и перестраивает объявленные в шаблоне таблицы, а источники, данные которых в отчёт не выведены, не трогает. Отчёт при этом должен быть в режиме внешней отрисовки — иначе операция отклоняется с ошибкой запроса. Ошибкой заканчиваются и случаи, когда в шаблоне повторяются внутренние имена наборов данных, нет ни одного узла соединения с данными или новая таблица объявлена при нескольких соединениях сразу: тогда непонятно, к какому из них её отнести. Если отчёт изменился с момента чтения шаблона, запись не проходит и возвращается конфликт — состояние надо перечитать и повторить синхронизацию. Когда расхождений нет, ничего не записывается: операция сообщает, что изменения не требуются.

Уникальность псевдонима. Псевдоним набора данных уникален в пределах отчёта: два источника одного отчёта не могут носить один и тот же псевдоним, регистр букв при сравнении не учитывается. В разных отчётах одинаковые псевдонимы допустимы. Занятый псевдоним не принимается ни при создании источника, ни при переименовании уже существующего (повторное сохранение под своим собственным псевдонимом проходит): новый источник не заводится, изменение не сохраняется, а на экране показывается сообщение «Набор данных с таким алиасом уже существует» (в сообщении псевдоним назван алиасом).

Набор категорий источника. У источника вида «расширенный поиск задач» может быть свой набор категорий, сужающий состав доступных полей. Набор хранится у источника, передаётся при его создании и изменении через API администрирования и задаётся в интерфейсе настройки источника (см. ниже). Если набор не задан, состав полей возвращается полным. Пустой набор равнозначен незаданному. У источников остальных видов набор не хранится: даже если он придёт в запросе, сервер его не запишет. Набор ограничивает только дополнительные параметры: постоянные поля расширенного поиска остаются в составе всегда, а поля, уже сохранённые в карте имён, — даже если их категории в наборе нет.

Выбор категорий в карте имён. У источника вида «расширенный поиск задач» набор категорий задаётся прямо на экране настройки источника: кнопка «Категории» расположена в блоке «Карта имён» — под выбором источника, над таблицей карты — и показывает текущий набор источника. У источников других видов этой кнопки нет. Если у отчёта несколько источников, кнопка относится к источнику, выбранному в списке; у отчёта с единственным источником она видна и без выбора. Клик открывает выбор категорий: разделы выбрать нельзя, в набор сохраняются только категории. Пока набор не задан, рядом с кнопкой выводится подпись «Категории не выбраны — доступны все поля источника»: пустой набор и есть «все категории», отдельного переключателя для этого нет.

Сохранение набора. Набор сохраняется сразу после закрытия выбора, отдельной кнопки сохранения у него нет. Состав полей в списке «Поле источника» перечитывается после сохранения сам — перезагружать страницу не нужно. Набор можно задать и источнику, созданному ранее: пересоздавать его не требуется. Если в карте имён уже сохранено поле категории, которой нет в текущем наборе, поле остаётся доступным в списке, и сохранение карты проходит без ошибки.

Доступ к зарегистрированному источнику при построении. Зарегистрированный источник отдаёт данные отчёту, только если пользователь состоит хотя бы в одной из групп, перечисленных в административной настройке источника. Если список групп в настройке пуст или не задан, отчёт с таким источником строит только администратор системы; остальным построение отклоняется отказом по доступу с текстом «Не удалось построить отчёт.». Администратор системы эту проверку проходит всегда. Общие правила доступа к источнику, по которым пустой список ограничения не задаёт, — в описании источников данных.

Состав колонок зарегистрированного источника. Список полей для карты имён берётся из каталога базы данных, при этом сам объект-источник не выполняется. Если у функции PostgreSQL несколько перегрузок с одним именем, а в ссылке на источник указано только имя без полной сигнатуры, тип колонок считается неизвестным: система не выбирает произвольную перегрузку. То же состояние — когда состав не удалось прочитать из каталога: ошибка чтения, динамический SQL в процедуре, временные таблицы. В этом состоянии список полей показывает только то, что уже сохранено в настройке колонок источника, без типов из базы, и означает «состав не определён», а не «в источнике нет колонок». Одна перегрузка, а также таблицы, представления и процедуры Microsoft SQL Server дают состав и типы из каталога как прежде.

Отбор у источника, перенесённого из иерархии задач. Такому источнику условия фильтра недоступны: он отдаёт данные дерева по контракту иерархии, а тот условий не знает. Если в отчёте по такому источнику задан непустой отбор, построение прерывается ошибкой конфигурации, а её причина с именем источника записывается в журнал; на экране отчёта показывается общий отказ «Не удалось построить отчёт.». Сортировка и параметры отчёта для него также не применяются. Отбор для отчёта по такому источнику оставляют пустым.

Карта имён и сопоставление фильтров относятся к выбранному источнику: если у отчёта их несколько, источник выбирается в списке на том же экране. Пока источник не выбран, обе таблицы не показываются.

Строка карты содержит поле источника, имя колонки набора, порядок сортировки и признак сортировки по убыванию. Поле источника выбирается из состава колонок, который платформа получает от самого источника; имя колонки задаётся вручную. В выпадающем списке поля источника есть строка поиска: список сужается по введённому тексту. Порядок сортировки — необязательное число: если он не задан, колонка в сортировке не участвует.

Поиск в этом списке идёт по названию поля и по его техническому имени, выполняется на уже загруженном составе и к серверу не обращается; очищенная строка возвращает полный список. Состав, по которому идёт поиск, уже сужен набором категорий источника, если он задан.

Обе колонки строки обязательны, а поле источника должно присутствовать в его составе — иначе строка помечается ошибкой и карта не сохраняется. Имена сопоставляются с колонками источника без учёта регистра: поле TaskId в карте имён считается тем же, что колонка TaskID источника. Сохранение заменяет список целиком: при отказе сервера не сохраняется ни одна строка, причина показывается на экране.

Сопоставление фильтров с источником в карту имён не входит и задаётся на том же экране отдельной таблицей.

Сопоставление фильтров. Каждая запись связывает значение фильтра отчёта с параметром или колонкой источника. В записи указываются вид значения — параметр фильтра, значение из контекста отчёта или значение ячейки набора, — сам параметр или вид контекста, часть развёрнутого значения, канал раскладки — параметр источника или условие по колонке, — целевое имя и операция сравнения. Набор доступных операций зависит от типа колонки и вида источника. Если значение для записи не заполнено, при построении отчёта запись пропускается; исключение — операции «Пусто» и «Не пусто» в условии по колонке: они применяются и без значения. Запись с каналом «параметр источника» у зарегистрированного источника, для которого не задана функция приёма параметров, не пропускается и при пустом значении: построение отчёта с таким источником завершается ошибкой. Сохранение заменяет список записей целиком.

Список «Параметр фильтра». Фильтр в записи сопоставления выбирается из значений, привязанных к текущему отчёту; список запрашивается по внешнему идентификатору отчёта-источника, а не по его числовому Id на площадке. Сбой загрузки списка показывается сообщением об ошибке — молчаливо пустого списка в этом случае больше нет.

Составной параметр. Значение источника может быть склеено из нескольких частей, например 111_222. Для такого значения в записи сопоставления заполняются разделитель и номер части — только вместе, нумерация частей с 1. Из значения берётся указанная часть и связывается со своей колонкой набора детализации: в условии по колонке часть приводится к типу этой колонки, а в канале «параметр источника» уходит как есть, потому что тип колонки там неизвестен. Даты в частях разбираются день-первыми (дд.мм.гггг), независимо от культуры сервера. Задать только разделитель или только номер части нельзя, и составное значение несовместимо с операцией «Между»: такая запись не сохраняется. Номер части, которого нет в значении, и часть, не подходящая к типу колонки, дают ошибку построения, а не расширяют выборку; пустая часть пропускается — как и незаполненное значение записи. Если разделитель и номер части не заданы, значение используется целиком: поведение записи прежнее.

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

• для текстовых колонок — «Равно», «Не равно», «Содержит», «Не содержит», «Начинается с», «Заканчивается на», «Пусто», «Не пусто»;
• для числовых колонок и дат — «Равно», «Не равно», «Меньше», «Меньше или равно», «Больше», «Больше или равно», «Между», «Пусто», «Не пусто»;
• для колонок со списком значений (все исполнители, все акцептанты, подписи, дополнительные параметры выбора пользователей и множественного выбора задач) — «Содержит хотя бы одно» и «Не содержит ни одного».

Если операция недопустима, условие не строится и построение отчёта завершается ошибкой; текст исключения — «Ошибка в параметре» с целевым именем записи. Для колонок, тип которых не объявлен или не относится ни к одному из этих видов, например логических, проверка не выполняется. Записи с каналом «параметр источника» она не касается.

Прочие источники и связанные документы

Темы, не дублируемые в этом файле (основные источники):

Тема	Где основной источник
процесс создания FR-отчёта, 3 типа источников данных, базовая гиперссылка на задачу	academy-patterns.md
Win-дизайнер, сетевые требования, диагностика, маршруты API	support-guide-fastreport.md
Настройки экспорта в XLSX	support-guide-fastreport.md
пользовательские сценарии запуска отчётов	business.md