+
+
+ Уровень
+ Сущность
+ Назначение
+
+
+
+
+
+ approval_topic_categories
+
+ Категория
+
+ Группировка тем. Отображается как кнопка первого уровня в меню бота.
+
+
+
+
+ approval_topics
+
+ Тема
+
+ Конкретный тип согласования. Содержит настройки, шаблоны сообщений
+ и код для идентификации.
+
+
+
+
+ approval_flow_nodes
+
+ Узел дерева
+
+ Отдельный шаг навигации: кнопка, поле ввода или мультиселект.
+ Связан с темой через topic_id.
+
+
+
+
+
+
+ Узлы образуют древовидную структуру через поле parent_id. Корневой
+ узел имеет parent_id = NULL. Порядок отображения узлов одного
+ уровня определяется полем sort_order.
+
+
+
+
+ {/* ============================================================ */}
+ {/* 3. МОДЕЛЬ ДАННЫХ */}
+ {/* ============================================================ */}
+
+
+
+ Структура таблицы approval_flow_nodes:
+
+
+
+
+
+ Поле
+ Тип
+ Описание
+
+
+
+
+ id
+ BIGINT PK
+ Уникальный идентификатор узла
+
+
+ topic_id
+ BIGINT FK
+ Ссылка на тему согласования
+
+
+ parent_id
+ BIGINT FK NULL
+ Ссылка на родительский узел. NULL для корня
+
+
+ key
+ TEXT NOT NULL
+
+ Уникальный в рамках темы идентификатор узла. Используется
+ системой для навигации
+
+
+
+ label
+ TEXT NOT NULL
+ Текст, отображаемый пользователю
+
+
+ data_key
+ TEXT NULL
+
+ Имя переменной, в которую сохраняется data_value при
+ выборе узла
+
+
+
+ data_value
+ TEXT NULL
+ Значение, сохраняемое в data_key
+
+
+ is_input
+ BOOLEAN
+ Признак узла текстового ввода
+
+
+ input_key
+ TEXT NULL
+ Ключ для сохранения введённого текста (обычно content)
+
+
+ input_hint
+ TEXT NULL
+ Подсказка-шаблон для пользователя
+
+
+ is_multi_select
+ BOOLEAN
+ Признак узла мультиселекта
+
+
+ multi_select_key
+ TEXT NULL
+ Ключ для сохранения выбранных значений
+
+
+ multi_select_value
+ TEXT NULL
+ Значение данного варианта мультиселекта
+
+
+ topic_code
+ TEXT NULL
+
+ Код темы для проверки прав доступа. Если задан — узел отображается
+ только пользователям с правом create на указанную тему
+
+
+
+ sort_order
+ INTEGER
+ Порядок сортировки среди узлов одного родителя
+
+
+
+
+
+ На таблицу наложен уникальный индекс UNIQUE(topic_id, key). Это
+ гарантирует, что в рамках одной темы не существует двух узлов с одинаковым
+ key. Нарушение этого условия приведёт к ошибке
+ SQLSTATE 23505 при сохранении.
+
+
+ {/* ============================================================ */}
+ {/* 4. ТИПЫ УЗЛОВ */}
+ {/* ============================================================ */}
+
+
+
+ Система поддерживает три типа узлов, определяемых комбинацией булевых полей
+ is_input и is_multi_select.
+
+
+
+
+
+ Тип
+ is_input
+ is_multi_select
+ Назначение
+
+
+
+
+ Кнопка
+ false
+ false
+ Выбор значения и переход к следующему шагу
+
+
+ Текстовый ввод
+ true
+ false
+ Ввод произвольного текста пользователем
+
+
+ Мультиселект
+ false
+ true
+ Выбор нескольких значений из списка
+
+
+
+
+
+
+
+ Базовый тип узла. При выборе кнопки система записывает в контекст пользователя
+ пару data_key = data_value и переходит к дочерним узлам.
+
+
+ Обязательные поля:
+
+
+
+ Поле
+ Требования
+ Пример
+
+
+
+
+ key
+ Уникальный в теме, snake_case
+ crimea
+
+
+ label
+ Непустая строка
+ Крым
+
+
+ data_key
+ snake_case, осмысленное имя
+ region
+
+
+ data_value
+ snake_case, уникальное в рамках data_key
+ crimea
+
+
+
+
+
+ Все дочерние узлы одного родителя должны иметь одинаковое значение{' '}
+ data_key, но различные data_value. Это необходимо
+ для корректной работы шаблонизации: система ожидает, что по ключу{' '}
+ region будет получено ровно одно значение.
+
+
+
+
+
+ Терминальный узел, запрашивающий у пользователя произвольный текст. Введённый
+ текст сохраняется в контекст по ключу input_key.
+
+
+ Обязательные поля:
+
+
+
+ Поле
+ Требования
+ Пример
+
+
+
+
+ input_key
+ Обычно content
+ content
+
+
+ input_hint
+ Конкретный пример заполнения
+ Опишите изменения: текущие → новые
+
+
+
+
+
+ Каждый путь от корня до листа дерева должен заканчиваться узлом типа «Текстовый
+ ввод». Отсутствие такого узла приведёт к невозможности завершения создания
+ заявки.
+
+
+
+
+
+ Специализированный узел, позволяющий пользователю выбрать несколько значений
+ одновременно. Все выбранные значения сохраняются через запятую в ключ
+ multi_select_key.
+
+
+ Обязательные поля:
+
+
+
+ Поле
+ Требования
+ Пример
+
+
+
+
+ multi_select_key
+ Одинаковый для всех дочерних узлов
+ systems
+
+
+ multi_select_value
+ Уникальный для каждого дочернего узла
+ okb, 1c
+
+
+
+
+
+ При выборе нескольких значений формируется строка вида{' '}
+ systems = "okb,1c". Автоматически создаётся производная
+ переменная systems_label, содержащая человекочитаемые названия
+ через запятую: "ОКБ, 1С".
+
+
+ {/* ============================================================ */}
+ {/* 5. ПОТОК ДАННЫХ */}
+ {/* ============================================================ */}
+
+
+
+ При прохождении пользователем дерева навигации формируется контекст
+ collected — ассоциативный массив, аккумулирующий все выбранные
+ значения. Процесс состоит из следующих этапов:
+
+
+
+
+
+
+
+
+
+
+
+
+ {/* ============================================================ */}
+ {/* 6. СТРУКТУРА COLLECTED */}
+ {/* ============================================================ */}
+
+
+
+ Контекст collected — это map[string]string, содержащий
+ все данные, собранные в процессе прохождения дерева. Структура формируется
+ детерминированно на основе конфигурации узлов.
+
+
+
+
+
+ Переменные с суффиксом _label формируются автоматически и не
+ требуют явного указания в дереве. Их значения соответствуют полю{' '}
+ label узла, в котором был задан соответствующий{' '}
+ data_key.
+
+
+
+ Ключ content зарезервирован для текста заявки, вводимого
+ пользователем. Ключ instructions заполняется автоматически из
+ поля instructions темы, если оно задано.
+
+
+ {/* ============================================================ */}
+ {/* 7. ШАБЛОНИЗАЦИЯ */}
+ {/* ============================================================ */}
+
+
+
+ Шаблоны используют синтаксис text/template стандартной библиотеки
+ Go. Шаблоны хранятся в таблице approval_topics в полях
+ message_template и code_template.
+
+
+
+
+
+ Определяет формат сообщения, отправляемого согласующему в Telegram. Поддерживает
+ HTML-разметку (<b>, <i>,{' '}
+ <code>).
+
+
+ Менеджерские расходы — {{.region_label}}
+
+{{.initiator_name}}:
+{{.content}}`}
+ />
+
+
+
+
+ Определяет алгоритм формирования кода темы на основе collected.
+ Полученный код используется для поиска записи в таблице{' '}
+ approval_topics. Если шаблон не задан, код формируется
+ автоматически конкатенацией всех значений collected через
+ символ подчёркивания.
+
+
+
+
+
+ Результат применения code_template должен точно соответствовать
+ значению поля code существующей записи в{' '}
+ approval_topics. В противном случае система вернёт ошибку
+ approval topic not found.
+
+
+ {/* ============================================================ */}
+ {/* 8. СИНТАКСИС */}
+ {/* ============================================================ */}
+
+
+
+ Доступные конструкции языка шаблонов:
+
+
+
+
+
+ При обращении к несуществующему ключу шаблонизатор выводит строку{' '}
+ <no value>. Это признак ошибки конфигурации: либо в дереве
+ отсутствует узел с соответствующим data_key, либо пользователь
+ не прошёл необходимый шаг.
+
+
+ {/* ============================================================ */}
+ {/* 9. СПРАВОЧНИК ПЕРЕМЕННЫХ */}
+ {/* ============================================================ */}
+
+
+
+ Переменные, доступные в шаблонах, делятся на две категории: встроенные
+ (предоставляются системой) и пользовательские (формируются из дерева).
+
+
+ Встроенные переменные
+
+
+
+ Переменная
+ Источник
+ Описание
+
+
+
+
+ initiator_name
+ Таблица users
+ ФИО пользователя, создавшего заявку
+
+
+ topic_name
+ Таблица approval_topics
+ Название темы
+
+
+ content
+ Текстовый ввод пользователя
+ Основной текст заявки
+
+
+ instructions
+ Поле instructions темы
+ Инструкция для согласующего
+
+
+
+
+ Пользовательские переменные
+
+ Формируются на основе data_key узлов дерева. Для каждого
+ data_key автоматически создаётся производная переменная с суффиксом
+ _label.
+
+
+
+
+
+ Переменная
+ Типичное значение
+ Описание
+
+
+
+
+ region
+ crimea, krasnodar
+ Идентификатор региона
+
+
+ region_label
+ Крым, Краснодар
+ Человекочитаемое название региона
+
+
+ branch
+ f1, f2
+ Идентификатор филиала
+
+
+ payment_type
+ own_expense
+ Тип оплаты
+
+
+ systems
+ okb,1c
+ Выбранные системы (мультиселект)
+
+
+ systems_label
+ ОКБ, 1С
+ Названия выбранных систем
+
+
+
+
+ {/* ============================================================ */}
+ {/* 10. ПРИМЕРЫ */}
+ {/* ============================================================ */}
+
+
+
+ Ниже приведены типовые конфигурации для различных сценариев. Шаблоны могут
+ быть скопированы и адаптированы под конкретные требования.
+
+
+ {/* Пример 1 */}
+ 10.1. Простая тема с выбором региона
+
+ Сценарий: пользователь выбирает регион, затем вводит текст заявки.
+
+
+
+
+ Менеджерские расходы — {{.region_label}}
+
+{{.initiator_name}}:
+{{.content}}`}
+ />
+
+
+
+ {/* Пример 2 */}
+ 10.2. Многоуровневая тема с условной логикой
+
+ Сценарий: филиал → тип расхода → признак ПП → ввод. Формат кода темы
+ зависит от наличия признака ПП.
+
+
+
+
+ Внебюджетные расходы — {{.branch_label}} ({{.expense_type_label}})
+{{if .pp_required}}💳 ПП: {{.pp_required_label}}{{end}}
+
+{{.initiator_name}}:
+{{.content}}`}
+ />
+
+
+
+ {/* Пример 3 */}
+ 10.3. Тема с мультиселектом
+
+ Сценарий: пользователь выбирает несколько систем одновременно.
+
+
+
+
+ Изменение клиентов: {{.change_type_label}}
+🖥 Системы: {{.systems_label}}
+📍 Регион: {{.region_label}}
+
+{{.initiator_name}}:
+{{.content}}`}
+ />
+
+
+
+ {/* Пример 4 */}
+ 10.4. Составная тема с множественными сценариями
+
+ Сценарий: единая тема объединяет несколько подтипов (отпуск, отгул,
+ больничный) с различным форматированием сообщений.
+
+
+ Тип: Отгул
+
+{{.initiator_name}}: прошу согласовать отгул
+{{.content}}
+{{.payment_type_label}}
+{{else if eq .absence_type "vacation"}}📋 Тип: Отпуск
+
+{{.initiator_name}}: прошу согласовать отпуск
+{{.content}}
+{{.payment_type_label}}
+{{else if eq .absence_type "sickleave"}}📋 Тип: Официальный больничный
+
+{{.initiator_name}}: прошу согласовать больничный
+{{if .open_date}}Дата открытия: {{.open_date}}.
+{{end}}{{.content}}
+{{.payment_type_label}}
+{{end}}`}
+ />
+
+
+
+ {/* ============================================================ */}
+ {/* 11. ОГРАНИЧЕНИЯ */}
+ {/* ============================================================ */}
+
+
+
+ При конфигурации деревьев необходимо соблюдать следующие ограничения:
+
+
+
+
+
+ №
+ Ограничение
+ Обоснование
+
+
+
+
+ 1
+ Уникальность key в рамках темы
+
+ Обеспечивается уникальным индексом (topic_id, key).
+ Нарушение приводит к ошибке SQLSTATE 23505.
+
+
+
+ 2
+
+ Единообразие data_key на одном уровне
+
+
+ Все дочерние узлы одного родителя должны иметь одинаковый{' '}
+ data_key. В противном случае в collected{' '}
+ появятся конфликтующие значения.
+
+
+
+ 3
+
+ Уникальность data_value среди братьев
+
+
+ Система не сможет различить узлы с одинаковыми data_key{' '}
+ и data_value.
+
+
+
+ 4
+ Терминальность путей
+
+ Каждый путь от корня до листа должен заканчиваться узлом типа
+ «Текстовый ввод».
+
+
+
+ 5
+ Отсутствие циклов
+
+ parent_id не может указывать на собственный узел или
+ его потомка. Проверяется при операциях перемещения.
+
+
+
+ 6
+ Формат key, data_key, data_value
+
+ Только строчные латинские буквы, цифры и символ подчёркивания
+ (snake_case).
+
+
+
+ 7
+ Согласованность code_template с БД
+
+ Результат применения шаблона должен соответствовать существующей
+ записи в approval_topics.
+
+
+
+
+
+ Что такое DataKey и DataValue?
+
+
+ Краткое объяснение — нажми, чтобы узнать больше
+
+
+
+ setShowDetails(!showDetails)}
+ >
+ {showDetails ? (
+
+ ) : (
+
+ )}
+
+
+
+ {/* Краткое объяснение (всегда видно) */}
+
+
+ DataKey и DataValue — это пара "ключ-значение", которая
+ сохраняется в память пользователя, когда он нажимает на этот узел.
+
+
+ Позже эти значения используются для:
+
+
+ }>
+ Формирования кода темы
+
+ }>
+ Сообщения согласующему
+
+ }>
+ Сохранения в заявке
+
+
+
+
+ {/* Интерактивный превью */}
+ {dataKey && dataValue && (
+
+
+ 📊 Что произойдёт, когда пользователь нажмёт "{label || 'этот узел'}":
+
+
+ {/* Поток данных */}
+
+ {/* Шаг 1: Нажатие */}
+
+
+ 1
+
+
+ Пользователь нажимает "{label || '...'}"
+
+
+
+
+
+
+
+ {/* Шаг 2: Сохранение */}
+
+
+ 2
+
+
+ В память сохраняется:{' '}
+ {dataKey} = "{dataValue}"
+
+
+
+
+
+
+
+ {/* Шаг 3: Автоматический label */}
+
+
+ 3
+
+
+ Автоматически добавляется:{' '}
+ {dataKey}_label = "{label || '...'}"
+
+
+
+
+
+
+
+ {/* Шаг 4: Использование */}
+
+
+ 4
+
+
+ Эти значения можно использовать в шаблонах темы:
+
+
+
+
+
+ {`В message_template:
+ "{{.${dataKey}}}" → "${dataValue}"
+ "{{.${dataKey}_label}}" → "${label || '...'}"
+
+В code_template:
+ "{{.${dataKey}}}" → "${dataValue}"`}
+
+
+
+
+ )}
+
+ {/* Развёрнутое объяснение */}
+
+
+
+
+ {/* Зачем это нужно */}
+
+
+ 🎯 Зачем это нужно?
+
+
+ Представьте, что пользователь создаёт заявку "Отпуск на один день за свой счёт".
+ Система должна понять, какую именно тему использовать и как отформатировать
+ сообщение для согласующего. Для этого она собирает "память" пользователя —
+ map collected, куда по пути попадают все DataKey/DataValue.
+
+
+
+ {/* Реальный пример */}
+
+
+ 📖 Реальный пример (тема "Отпуск")
+
+
+ Пользователь проходит путь: Отпуск → На один день → За свой счёт → Ввод текста
+
+
+
+
+
+ Шаг
+ Узел (Label)
+ DataKey
+ DataValue
+
+
+
+
+ 1
+ Отпуск
+ absence_type
+ vacation
+
+
+ 2
+ На один день
+ duration_type
+ single_day
+
+
+ 3
+ За свой счёт
+ payment_type
+ own_expense
+
+
+ 4
+ Ввод текста
+ content
+ (текст пользователя)
+
+
+
+
+
+ Итоговый collected:
+
+
+ {`{
+ "absence_type": "vacation",
+ "absence_type_label": "Отпуск", ← автоматически из Label
+ "duration_type": "single_day",
+ "duration_type_label": "На один день", ← автоматически
+ "payment_type": "own_expense",
+ "payment_type_label": "За свой счёт", ← автоматически
+ "content": "22.02.2026"
+}`}
+
+
+
+ {/* Как это используется */}
+
+
+ 🔧 Как это используется?
+
+
+
+ 1. Формирование кода темы (code_template):
+
+
+ {`Шаблон: vacation_{{.duration_type}}_full_day_{{.payment_type}}
+Результат: vacation_single_day_full_day_own_expense
+
+Этот код ищет в БД конкретную тему для заявки.`}
+
+
+
+ 2. Сообщение согласующему (message_template):
+
+
+ {`Шаблон:
+📋 Тип: Отпуск
+{{.initiator_name}}: прошу согласовать отпуск
+{{.content}}
+{{.payment_type_label}}
+
+Результат:
+📋 Тип: Отпуск
+Иванов И.И.: прошу согласовать отпуск
+22.02.2026
+За свой счёт`}
+
+
+
+ {/* Правила */}
+ } color="yellow" variant="light">
+
+ ⚠️ Правила, которые нужно соблюдать:
+
+
+
+ 1. DataKey должен быть осмысленным. Используйте понятные имена:{' '}
+ region, branch, payment_type.
+ Не используйте x, val, data.
+
+
+ 2. DataValue должен быть уникальным в рамках одного DataKey.{' '}
+ Если у вас есть два узла с region=crimea и{' '}
+ region=krasnodar — это правильно. Но если оба будут{' '}
+ region=crimea — система не сможет их различить.
+
+
+ 3. Используйте snake_case. Только lowercase, цифры и подчёркивания:{' '}
+ own_expense ✅, OwnExpense ❌,{' '}
+ own-expense ❌.
+
+
+ 4. Один DataKey на одном уровне дерева. Если на одном уровне
+ несколько кнопок — у всех должен быть одинаковый DataKey, но разные DataValue.
+ Например, три кнопки "Крым/Краснодар/Беларусь" — все с region,
+ но с разными значениями.
+
+
+ 5. Label — это то, что видит пользователь. DataValue — техническое
+ значение. Они могут отличаться: Label="За свой счёт", DataValue="own_expense".
+
+
+
+
+ {/* Типичные ошибки */}
+
+
+ ❌ Типичные ошибки:
+
+
+
+
+ Ошибка: Два узла на одном уровне с одинаковыми DataKey и DataValue
+
+
+ Последствие: система не сможет различить, какую ветку выбрал пользователь
+
+
+
+
+ Ошибка: Разные DataKey на одном уровне (например, у одной кнопки{' '}
+ region, у другой area)
+
+
+ Последствие: в collected появятся два разных ключа, что сломает шаблоны
+
+
+
+
+ Ошибка: DataValue с пробелами или заглавными буквами
+
+
+ Последствие: код темы будет некорректным, заявка не создастся
+
+
+
+
+ Ошибка: Пустой DataKey или DataValue у кнопки
+
+
+ Последствие: данные не сохранятся, шаблон не сможет их использовать
+
+
+
+
+
+ {/* Правильные примеры */}
+
+
+ ✅ Правильные примеры из реальных тем:
+
+