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} ) }