Смарт-фильтры — Администрирование¶
Обзор¶
Домен smart-filters охватывает создание и редактирование смарт-выражений (SmartExpressions) — универсального механизма условий и вычислений в 1Форме. Смарт-выражения используются как:
- Фильтры (
IsFilter = 1) — условия отбора в гридах, виджетах, отчётах - Условия правил (
IsFilter = 0) — триггерные условия в smart-actions - Вычисления — значения параметров в пакетах действий
- Смарт-доступ — динамические права (см.
smart-actions/admin.md)
Администрирование использует: - Кастомные SPA-страницы — 3 формы (SmartExpressions, SmartQueries) — зарегистрированы в дереве автоадминки, но открывают собственные SPA-страницы - Admin API — 6 контроллеров (редактор, конструктор, тест-кейсы)
EntityEditor для данного домена не используется.
Механизмы администрирования¶
Кастомные SPA-страницы (в дереве автоадминки)¶
| Alias формы | Название | Url | Таблица БД | Папка |
|---|---|---|---|---|
general-smart |
Общие смарты | /administration/smart-packs |
dbo.SmartExpressions | Общая бизнес-логика |
all-smart |
Все смарты | /administration/smart-packs?globalEventsOnly=false |
dbo.SmartExpressions | Общая бизнес-логика |
rebus-queues |
Очереди шины сообщений | /administration/rebus-queues |
dbo.SmartQueries | Системные настройки |
Формы general-smart и all-smart разделяются с доменом smart-actions (обе работают с dbo.SmartExpressions). Smart-filters отвечает за создание/редактирование выражений, smart-actions — за привязку к событиям и пакетам.
Admin API контроллеры¶
Редактор выражений¶
| Контроллер | Маршрут | Методы | Назначение |
|---|---|---|---|
| SmartExpressionsController | /api/admin/smart/expressions |
GET, POST, DELETE | CRUD смарт-выражений, список, фильтрация |
| SmartExpressionEditorController | /api/admin/smart/expression-editor |
GET, POST | Загрузка/сохранение выражения в визуальном редакторе |
| SmartExpressionConstructorController | /api/admin/smart/expression-constructor |
GET, POST | QueryBuilder-конструктор (визуальное дерево условий) |
| SmartExpressionTestCasesController | /api/admin/smart/expression-test-cases |
GET, POST, DELETE | CRUD тест-кейсов для отладки выражений |
Запросы и конструктор¶
| Контроллер | Маршрут | Методы | Назначение |
|---|---|---|---|
| SmartQueryController | /api/admin/smart/query |
GET, POST | SmartQueries — конфигурации выборок для виджетов |
| QueryConstructorController | /api/admin/smart/query-constructor |
GET, POST | Конструктор TSQL-запросов |
Детальная карта API-эндпоинтов редактора, включая зависимости от EF6/EDMX, описана в editor-api.md.
Ключевые настройки¶
Создание и редактирование выражений¶
Где настраивается: Admin API -> SmartExpressionEditorController + SmartExpressionsController
Таблица БД: dbo.SmartExpressions
Два способа создания:
1. Визуальный редактор — через TreeBuilder (дерево свойств сущностей) + ToolbarBuilder (операторы/функции)
2. TSQL-режим — прямой ввод SQL-кода в TSqlContent
Поля SmartExpressions (16 в форме general-smart):
| Поле | Тип | Что контролирует |
|---|---|---|
Content |
nvarchar(max) | XML-формула визуального конструктора |
TSqlContent |
nvarchar(max) | TSQL-код (ручной ввод, приоритет над Content) |
Name |
nvarchar | Название выражения |
SubcatID |
int | Привязка к категории (NULL = глобальное) |
IsFilter |
bit | Тип: фильтр (true) или условие правила (false) |
EventID |
int | Событие-триггер (только для условий правил) |
ParameterValue |
nvarchar | Уточнение параметра события |
NoContextMode |
int | Режим без контекста задачи |
AvailAsSmartSearch |
bit | Доступно как смарт-поиск в гридах |
Public |
bit | Публичное (видимо другим администраторам) |
OwnerUserId |
int | Владелец выражения |
QueryBuilderState |
nvarchar(max) | Состояние QueryBuilder (JSON) |
OriginID |
int | Контекст использования (Origin enum) |
IsDeleted |
bit | Мягкое удаление |
GUID |
uniqueidentifier | Уникальный ID для миграции |
ID |
int | Primary key |
Приоритет выполнения:
1. TSqlContent (если задан) — прямой TSQL
2. TSqlCompiled (компилированный ESQL → TSQL)
3. Content (XML → XSLT → ESQL → Entity Framework → TSQL)
Подробности пайплайна трансляции — в backend.md раздел «Два режима работы SmartExpression».
Origin — контекст использования¶
Где настраивается: атрибут originId при создании выражения через API
Enum: Valhalla.Integration/Enums/Smart/Origin.cs
| Значение | Имя | Контекст |
|---|---|---|
| 0 | Почтовые ящики | |
| 1 | CustomPages | Кастомные страницы, виджеты, подписи, отчёты |
| 2 | Subcat | Подкатегории задач (дефолт) |
| 3 | Queue | Очереди |
| 4 | EdocumentLink | Э-документы |
| 5 | EdocumentSbisLink | Э-документы СБИС |
Правило валидации: если задан SubcatId — origin обязан быть Subcat (2). Исключение: legacy-контролы (старая админка) могли создавать выражения с SubcatId и origin=1 (CustomPages) — такие записи существуют в БД, но при пересохранении через SPA origin будет приведён к 2.
Детальный аудит Origin по всем контролам (79 использований в старой админке + 64 в SPA) — в origin-audit.md.
SmartQueries (выборки для виджетов/отчётов)¶
Где настраивается: SPA-страница /administration/rebus-queues (пункт rebus-queues в дереве автоадминки) / Admin API -> SmartQueryController
Таблица БД: dbo.SmartQueries
| Поле | Что контролирует |
|---|---|
Name |
Название выборки |
SmartFilterID |
Смарт-выражение для фильтрации |
RecordsLimit |
Лимит записей |
SubcatID |
Привязка к категории |
XAxisExpressionID |
Выражение для оси X (графики) |
YAxisExpressionID |
Выражение для оси Y |
AggregationTypeID |
Тип агрегации |
SortByXAxis |
Сортировка по X |
SortAsc |
Направление сортировки |
EventID |
Событие (для контекста) |
SmartQueries — связующее звено между смарт-выражениями и UI-виджетами. Каждый SmartQuery ссылается на один или несколько SmartExpressions через SmartFilterID, XAxisExpressionID, YAxisExpressionID.
Редактор выражений (Editor API)¶
Где настраивается: Admin API -> SmartExpressionEditorController
Редактор — ключевой инструмент администратора. Состоит из:
- TreeBuilder — дерево свойств сущности (Task, User, Comment...), строится через рефлексию ORM-модели
- ToolbarBuilder — палитра операторов и функций
- XSLT-рендеринг — визуальное представление формулы (XML → XHTML)
Зависимость от EF6/EDMX: TreeBuilder использует EfModelTraversal для обхода Entity-модели. Детальный аудит зависимостей в editor-api.md — 5 из 9 эндпоинтов зависят от EDMX.
Ключевые эндпоинты:
| # | HTTP | URL | Зависимость от EDMX |
|---|---|---|---|
| 1 | GET | {id}/editor |
Да (TreeBuilder + XSLT) |
| 2 | GET | editor |
Да (TreeBuilder + XSLT) |
| 3 | POST | editor |
Частично (Save + ESQL compile) |
| 4 | POST | editor/execute |
Нет (прямое выполнение) |
| 5 | POST | editor/tree/reload |
Да (EfModelTraversal) |
| 6 | POST | editor/tree/expand |
Да (EfModelTraversal) |
| 7 | POST | editor/tree/propertyinfoincollection |
Да (EfModelTraversal) |
| 8 | POST | editor/toolbar/itemsforcontext |
Нет (ресурсы) |
| 9 | GET | editor/toolbar/objects |
Нет (статика) |
Тестирование выражений через execute (POST editor/execute)¶
Endpoint: POST /api/admin/smart/expressions/editor/execute
Выполняет SE и возвращает результат + execution plan. Работает из Admin UI (кнопка «Тест» в редакторе выражений) и через curl.
URL Admin UI: /spa/noframe/administration/smart-expressions?SubcatId={subcatId}&ID={seId}&EventID={eventId}&ActionsPackID={packId}
Ключевые параметры payload:
| Параметр | Тип | Назначение |
|---|---|---|
expression |
object | Полный объект SE (id, tSql, pgSql, subcatId, isFilter и т.д.) |
context.eventId |
string | Событийный контекст: "AfterTaskCreate", "BeforeTaskChange" и т.д. Позволяет тестировать событийно-зависимые SE |
context.subcatId |
int | Категория контекста |
context.isFilter |
bool | Тип: фильтр или условие |
params.contextId |
int/null | ID задачи-контекста. null → используется dummy (-1) |
generateDummyParams |
bool | Автоподстановка фиктивных параметров (@ContextId = -1 и т.д.) |
getExecutionPlan |
bool | Вернуть план выполнения (EXPLAIN ANALYZE для PG) |
runOnSmartPgConnection |
bool | Ключевой флаг. true → выполняет pgSql на PG через SmartPgConnectionString. false/отсутствует → выполняет tSql на MSSQL |
Ответ (data):
| Поле | Описание |
|---|---|
filterResult |
Результат фильтра (bool) |
objectResult |
Результат для non-filter SE |
tSql |
Итоговый SQL (tSql или pgSql в зависимости от runOnSmartPgConnection) |
executionPlan.executionPlanMsSql |
MSSQL plan (если запрашивался, требует SHOWPLAN permission) |
executionPlan.executionPlanPostgreSql |
PG EXPLAIN ANALYZE JSON (если runOnSmartPgConnection: true) |
matchExpectedResult |
Совпадение с ожидаемым типом |
actualResultType |
Фактический тип результата |
Пример curl (PG):
curl -s -H "1F-Pat: $PAT" -H "Content-Type: application/json" \
-X POST "https://{host}/api/admin/smart/expressions/editor/execute" \
-d '{"expression":{...},"context":{"eventId":"AfterTaskCreate","subcatId":5574,"isFilter":true,...},"params":{"contextId":null,"eventParameters":[]},"getExecutionPlan":true,"generateDummyParams":true,"runOnSmartPgConnection":true}'
Известные ограничения:
- generateDummyParams: true подставляет @ContextId = -1 — SE с JOIN на контекстную задачу вернут пустой результат, но синтаксическая валидация пройдёт
- Execution plan для MSSQL требует SHOWPLAN permission на БД (у PAT-пользователя может не быть)
- ~~Баг сборки 2.268.95: NullReferenceException в BuildDummyTestCase~~ — исправлен
Тест-кейсы для выражений¶
Где настраивается: Admin API -> SmartExpressionTestCasesController
Позволяет создавать тестовые наборы данных для отладки смарт-выражений. Тест-кейс = набор входных параметров + ожидаемый результат.
Параметры и дефолты при выборе выражений¶
Где настраивается: FormsGenerator -> SchemeElementSmartExpressionSelectOptionsAttribute
Контрол выбора смарт-выражения (dropdown) принимает параметры:
| Параметр | Дефолт | Влияние |
|---|---|---|
originId |
2 (Subcat) | Контекст: какие свойства доступны в дереве |
subcatId |
null | Привязка к категории (фильтрует выборку) |
isFilter |
true | Тип: фильтр или условие |
eventId |
null | Событие (для условий правил) |
smartExpressionId |
null | Текущее выбранное выражение |
Полная карта параметров и дефолтов для старой/новой админки — в defaults-reference.md.
Справочник синтаксиса — дополнения к read-data.md¶
Базовый справочник операторов и функций для чтения данных — в read-data.md: числовые/строковые/датовые/логические/агрегатные функции, операторы сравнения, работа со всеми типами ДП (включая Lookup, Multilookup, Таблицу, Файл, Выбор пользователей), реквизиты задачи, ресурсы, FileStorage. Ниже — то, что в нём явно не описано.
Математические функции¶
| Функция | Параметры | Возвращает | Пример / описание |
|---|---|---|---|
ПоМодулю(N) |
Число | Число | Абсолютное значение (модуль) |
Степень(N, M) |
Число (основание N), Число (показатель M) | Число | N в степени M |
УрезатьДоЗнаков(N, Знаков) |
Число, Число (макс. знаков после запятой) | Число | УрезатьДоЗнаков(123.456, 2) = 123.45; УрезатьДоЗнаков(123, 2) = 123 |
СлучЗнач(N) |
Число (seed) | Число | Случайное десятичное от 0 до 1, рассчитанное на основе указанного числа |
ЗнакЧисла(N) |
Число | Целое | 1 для положительных, -1 для отрицательных, 0 для нуля |
Корень(N) |
Число | Число | Квадратный корень |
Базовая арифметика (
+,-,*,/, сравнения),Округлить,МинЦелоеНеМеньше,МаксЦелоеНеБольше,IsNullDecimal,ВСтроку,ВЦелоеЧисло,ВДробноеЧисло— см.read-data.md§ Числовые ДП.
Строковые функции — дополнение¶
| Функция | Параметры | Возвращает | Назначение |
|---|---|---|---|
DateConvert(Дата, СтильЧисло) |
Дата, Целое (стиль формата MS SQL CAST/CONVERT) |
Строка | Преобразование даты в строку по указанному стилю (см. справочник стилей MS SQL date-and-time-styles) |
ПовторитьСтроку(Строка, N) |
Строка, Целое | Строка | Повторяет строку N раз |
Конкатенация(Строка1, Строка2) |
Строка, Строка | Строка | Соединяет две строки (функциональная альтернатива оператору +) |
Остальные строковые функции (
СтрокаСодержит,НачинаетсяС,ЗаканчиваетсяНа,Подстрока,ВернутьСлева/Справа,ВВерхРегистр/ВНижРегистр,ЗаменитьВСтроке,БезПробелов,ДлинаСтроки,IsNullString,ПоискВСтроке,ПоискПоШаблону), а также оператор+для конкатенации — см.read-data.md§ Строковые ДП.
Объект «Текущий пользователь» (раздел дерева «Прочее»)¶
В дереве сущностей редактора раздел «Прочее» содержит объект «Текущий пользователь» — пользователя, под которым выполняется смарт-выражение. Через него доступен полный набор параметров 1F.User (ID, логин, ФИО, email, группы, орг.единица — см. read-data.md § Пользователь (User)).
Применяется для проверки принадлежности к группе/орг.единице, подстановки имени в выражение, отбора задач по исполнителю/заказчику = текущий пользователь. При редактировании глобальных смартов (форма general-smart, без контекста категории/события) обращение к объектам системы возможно только через раздел «Прочее» — это единственный путь к данным пользователя в таком контексте.
Блок «Используется» — параметры события «Во время открытия задач軶
Для отбора задач в блоке «Используется» категории (вкладка, отображающая задачи, ссылающиеся на текущую через Lookup/Multilookup) применяются смарт-фильтры. Особенности дерева сущностей такого фильтра:
- Параметры основной задачи (в карточке которой открыт блок) — через папку «Параметры события "Во время открытия задачи"» в дереве.
- Параметры задач, отображаемых в блоке (ссылающихся) — через объекты вне контекста события, ниже в дереве сущностей.
- ДП основной и зависимых задач — через объекты «Значения ДП».
Ограничения языка смарт-выражений¶
ORDER BYзапрещён в скрипте смарт-фильтра, доступного в смарт-поиске (отбор в табличном представлении категории).- Тип возвращаемого результата должен соответствовать контексту использования: для записи в поле «Дата» —
DateTime; для поля единичного объекта — единичный объект, не список; для смарт-фильтра —Boolean(тип выставляется системой автоматически и не редактируется). - Конвертация TSQL → SMART не предусмотрена. Из режима SMART можно перейти в TSQL (
Конвертировать в режим TSQL), обратный путь отсутствует — кнопка не отображается, если выражение в TSQL. - Список значений в смарт-выражении записывается через фигурные скобки:
{ААА, ВВВ, ССС}. Чтобы единичный объект воспринимался как коллекция, он тоже заключается в{}. - Запись (модификация) ДП через смарт-выражения использует отдельный синтаксис (JSON для SelectUsers/Email, разделители
+/-/=/#/|и]||[для Таблицы и Выбора нескольких задач) — описан в../smart-actions/admin.md. Smart-filters отвечают только за чтение и фильтрацию.
Типичные ошибки настройки¶
| Симптом | Причина | Где проверить | SQL-диагностика |
|---|---|---|---|
| Выражение возвращает пусто | Неверный SubcatID / OriginID | Форма general-smart |
select ID, Name, SubcatID, OriginID, IsFilter from dbo.SmartExpressions where ID = {id} |
| Редактор не показывает свойства | Неверный Origin (не тот контекст) | Origin-audit.md → таблица | select ID, Name, OriginID from dbo.SmartExpressions where Name like '%{name}%' |
| «Выражение удалено» но используется | IsDeleted = 1, но ссылки остались | Поиск по FK | select * from dbo.SmartExpressions where IsDeleted = 1 and ID in (select SmartFilterID from dbo.CustomQueueActions) |
| TSql-выражение не работает, визуальное — да | TSqlContent имеет приоритет, но содержит ошибку | Поле TSqlContent | select ID, Name, left(TSqlContent, 200) from dbo.SmartExpressions where TSqlContent is not null and ID = {id} |
| SmartQuery виджет пустой | SmartFilterID ссылается на несуществующее выражение | Форма rebus-queues |
select sq.*, se.Name as FilterName, se.IsDeleted from dbo.SmartQueries sq left join dbo.SmartExpressions se on sq.SmartFilterID = se.ID where sq.ID = {id} |
| Дерево свойств в редакторе неполное | EfModelTraversal не находит навигации (EF6-зависимость) | editor-api.md, эндпоинт 5-7 | — (код, не SQL) |
Связанные документы¶
docs/domains/smart-filters/backend.md— архитектура пайплайна (XML → ESQL → TSQL), провайдеры параметровdocs/domains/smart-filters/editor-api.md— детальный аудит 9 эндпоинтов редактора с зависимостями от EF6/EDMXdocs/domains/smart-filters/origin-audit.md— аудит параметра Origin (79 мест в старой админке, 64 в SPA, 17 без origin)docs/domains/smart-filters/defaults-reference.md— карта параметров и дефолтов контрола выбора выраженийdocs/domains/smart-filters/read-data.md— справочник чтения данных через выраженияdocs/domains/smart-filters/data-flow.md— E2E диагностикаdocs/domains/smart-actions/admin.md— администрирование правил (событие → пакет), смарт-доступdocs/reference/automation/smart-expression-operators-reference.md— компактный справочник всех операторов и функций (строки/числа/даты/логика/агрегаты/математика)docs/reference/automation/smart-events-catalog.md— реестр всехEventID(197 событий) с C#-именами и параметрами@eventParam*docs/platform/backend/admin-architecture.md— общая архитектура администрированияdocs/reference/database/dbadmin-forms-map.md— карта всех форм автоадминки