import { useState, useEffect } from 'react'
import {
Stack,
Text,
Code,
Paper,
Group,
Box,
Title,
Table,
Divider,
Anchor,
ActionIcon,
Tooltip,
CopyButton,
ScrollArea,
Badge,
Alert,
UnstyledButton,
} from '@mantine/core'
import {
IconArrowLeft,
IconCopy,
IconCheck,
IconChevronRight,
} from '@tabler/icons-react'
import { useNavigate } from 'react-router-dom'
// ================================================================
// Структура документации
// ================================================================
interface DocSection {
id: string
title: string
level: number
}
const SECTIONS: DocSection[] = [
{ id: 'overview', title: 'Обзор', level: 1 },
{ id: 'architecture', title: 'Архитектура', level: 1 },
{ id: 'data-model', title: 'Модель данных', level: 1 },
{ id: 'node-types', title: 'Типы узлов', level: 1 },
{ id: 'node-button', title: ' Кнопка', level: 2 },
{ id: 'node-input', title: ' Текстовый ввод', level: 2 },
{ id: 'node-multiselect', title: ' Мультиселект', level: 2 },
{ id: 'data-flow', title: 'Поток данных', level: 1 },
{ id: 'collected', title: 'Структура collected', level: 1 },
{ id: 'templates', title: 'Шаблонизация', level: 1 },
{ id: 'message-template', title: ' message_template', level: 2 },
{ id: 'code-template', title: ' code_template', level: 2 },
{ id: 'syntax', title: 'Синтаксис шаблонов', level: 1 },
{ id: 'variables', title: 'Справочник переменных', level: 1 },
{ id: 'examples', title: 'Примеры конфигураций', level: 1 },
{ id: 'constraints', title: 'Ограничения и валидация', level: 1 },
{ id: 'troubleshooting', title: 'Диагностика ошибок', level: 1 },
]
export default function FlowTreeGuidePage() {
const navigate = useNavigate()
const [activeSection, setActiveSection] = useState('overview')
// Отслеживание активной секции при скролле
useEffect(() => {
const handleScroll = () => {
const scrollPosition = window.scrollY + 100
for (const section of [...SECTIONS].reverse()) {
const element = document.getElementById(section.id)
if (element && element.offsetTop <= scrollPosition) {
setActiveSection(section.id)
break
}
}
}
window.addEventListener('scroll', handleScroll)
return () => window.removeEventListener('scroll', handleScroll)
}, [])
const scrollTo = (id: string) => {
document.getElementById(id)?.scrollIntoView({ behavior: 'smooth', block: 'start' })
setActiveSection(id)
}
return (
{/* ============================================================ */}
{/* Sidebar с навигацией */}
{/* ============================================================ */}
Документация
navigate('/nodes')}
>
{SECTIONS.map((section) => (
scrollTo(section.id)}
px={section.level === 2 ? 20 : 12}
py={6}
style={{
borderRadius: 4,
backgroundColor:
activeSection === section.id
? 'var(--mantine-color-blue-0)'
: 'transparent',
borderLeft:
activeSection === section.id
? '2px solid var(--mantine-color-blue-6)'
: '2px solid transparent',
}}
>
{section.title}
))}
{/* ============================================================ */}
{/* Основной контент */}
{/* ============================================================ */}
{/* Заголовок документа */}
v1.0
Обновлено: 22 июня 2026
Конструктор деревьев навигации
Техническая документация по настройке деревьев навигации для системы
согласования заявок. Описывает архитектуру, модель данных, синтаксис
шаблонов и примеры конфигураций.
{/* ============================================================ */}
{/* 1. ОБЗОР */}
{/* ============================================================ */}
Дерево навигации — иерархическая структура узлов, определяющая последовательность
шагов, которые проходит пользователь при создании заявки в Telegram-боте. Каждый
узел дерева представляет собой либо кнопку выбора значения, либо поле ввода
произвольного текста.
Система предназначена для конфигурирования произвольных бизнес-процессов
согласования без изменения исходного кода сервиса. Администратор создаёт дерево
через веб-интерфейс, а бот динамически строит интерфейс на основе этой
конфигурации.
Деревья используются для тем согласования: отпуска, внебюджетные расходы,
возвраты, изменения клиентов и прочие бизнес-процессы, требующие сбора
структурированных данных от пользователя перед отправкой на согласование.
{/* ============================================================ */}
{/* 2. АРХИТЕКТУРА */}
{/* ============================================================ */}
Система состоит из трёх уровней сущностей:
Уровень
Сущность
Назначение
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. СИНТАКСИС */}
{/* ============================================================ */}
Доступные конструкции языка шаблонов:
Конструкция
Семантика
{`{{.key}}`}
Вывод значения переменной
{`{{if .key}}...{{end}}`}
Условный вывод (проверяется непустота)
{`{{if eq .key "val"}}A{{else}}B{{end}}`}
Ветвление по значению
{`{{if ...}}...{{else if ...}}...{{else}}...{{end}}`}
Множественное ветвление
{`{{trimPrefix .key "prefix"}}`}
Удаление префикса из значения
{`{{trimSuffix .key "suffix"}}`}
Удаление суффикса из значения
{`{{toUpper .key}}`}
Приведение к верхнему регистру
{`{{toLower .key}}`}
Приведение к нижнему регистру
{`{{contains .key "substr"}}`}
Проверка вхождения подстроки
При обращении к несуществующему ключу шаблонизатор выводит строку{' '}
<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.
{/* ============================================================ */}
{/* 12. ДИАГНОСТИКА */}
{/* ============================================================ */}
Типовые ошибки и методы их устранения:
Конец документации. По вопросам конфигурации обращаться к разработчикам системы.
)
}
// ================================================================
// Вспомогательные компоненты
// ================================================================
function DocSection({ id, title, level = 1 }: { id: string; title: string; level?: number }) {
return (
{level === 1 ? (
{title}
) : (
{title}
)}
)
}
function CodeBlock({ title, code }: { title: string; code: string }) {
return (
{title}
{({ copied, copy }) => (
{copied ? : }
)}
{code}
)
}
function Callout({ title, children, mt = 'md' }: { title: string; children: React.ReactNode; mt?: string }) {
return (
{children}
)
}
function FlowStep({ step, title, description }: { step: number; title: string; description: string }) {
return (
{step}
{title}
{description}
)
}
function ErrorEntry({ code, description, resolution }: { code: string; description: string; resolution: string }) {
return (
{code}
{description}
Решение:
{resolution}
)
}