admin_ruspet/src/pages/flowNodes/FlowTreeGuidePage.tsx

1198 lines
68 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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 (
<Box style={{ display: 'flex', gap: 32, alignItems: 'flex-start' }}>
{/* ============================================================ */}
{/* Sidebar с навигацией */}
{/* ============================================================ */}
<Box
style={{
width: 260,
flexShrink: 0,
position: 'sticky',
top: 20,
maxHeight: 'calc(100vh - 40px)',
}}
>
<Stack gap={0}>
<Group justify="space-between" mb="md">
<Text size="xs" fw={600} c="dimmed" tt="uppercase" lts={1}>
Документация
</Text>
<ActionIcon
variant="subtle"
size="sm"
onClick={() => navigate('/nodes')}
>
<IconArrowLeft size={16} />
</ActionIcon>
</Group>
<ScrollArea style={{ maxHeight: 'calc(100vh - 120px)' }}>
<Stack gap={2}>
{SECTIONS.map((section) => (
<UnstyledButton
key={section.id}
onClick={() => 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',
}}
>
<Text
size={section.level === 2 ? 'xs' : 'sm'}
c={activeSection === section.id ? 'blue.7' : 'dimmed'}
fw={activeSection === section.id ? 600 : 400}
>
{section.title}
</Text>
</UnstyledButton>
))}
</Stack>
</ScrollArea>
</Stack>
</Box>
{/* ============================================================ */}
{/* Основной контент */}
{/* ============================================================ */}
<Box style={{ flex: 1, maxWidth: 880, minWidth: 0 }}>
<Stack gap={48} pb={120}>
{/* Заголовок документа */}
<Box>
<Group gap="xs" mb="xs">
<Badge variant="light" size="sm">v1.0</Badge>
<Text size="xs" c="dimmed">Обновлено: 22 июня 2026</Text>
</Group>
<Title order={1}>Конструктор деревьев навигации</Title>
<Text c="dimmed" mt="sm" size="lg">
Техническая документация по настройке деревьев навигации для системы
согласования заявок. Описывает архитектуру, модель данных, синтаксис
шаблонов и примеры конфигураций.
</Text>
</Box>
<Divider />
{/* ============================================================ */}
{/* 1. ОБЗОР */}
{/* ============================================================ */}
<DocSection id="overview" title="1. Обзор" />
<Text>
Дерево навигации — иерархическая структура узлов, определяющая последовательность
шагов, которые проходит пользователь при создании заявки в Telegram-боте. Каждый
узел дерева представляет собой либо кнопку выбора значения, либо поле ввода
произвольного текста.
</Text>
<Text>
Система предназначена для конфигурирования произвольных бизнес-процессов
согласования без изменения исходного кода сервиса. Администратор создаёт дерево
через веб-интерфейс, а бот динамически строит интерфейс на основе этой
конфигурации.
</Text>
<Callout title="Область применения">
Деревья используются для тем согласования: отпуска, внебюджетные расходы,
возвраты, изменения клиентов и прочие бизнес-процессы, требующие сбора
структурированных данных от пользователя перед отправкой на согласование.
</Callout>
{/* ============================================================ */}
{/* 2. АРХИТЕКТУРА */}
{/* ============================================================ */}
<DocSection id="architecture" title="2. Архитектура" />
<Text>
Система состоит из трёх уровней сущностей:
</Text>
<Table withTableBorder withColumnBorders mt="md">
<Table.Thead>
<Table.Tr>
<Table.Th style={{ width: 180 }}>Уровень</Table.Th>
<Table.Th>Сущность</Table.Th>
<Table.Th>Назначение</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td>
<Code>approval_topic_categories</Code>
</Table.Td>
<Table.Td>Категория</Table.Td>
<Table.Td>
Группировка тем. Отображается как кнопка первого уровня в меню бота.
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>
<Code>approval_topics</Code>
</Table.Td>
<Table.Td>Тема</Table.Td>
<Table.Td>
Конкретный тип согласования. Содержит настройки, шаблоны сообщений
и код для идентификации.
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>
<Code>approval_flow_nodes</Code>
</Table.Td>
<Table.Td>Узел дерева</Table.Td>
<Table.Td>
Отдельный шаг навигации: кнопка, поле ввода или мультиселект.
Связан с темой через <Code>topic_id</Code>.
</Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<Text mt="md">
Узлы образуют древовидную структуру через поле <Code>parent_id</Code>. Корневой
узел имеет <Code>parent_id = NULL</Code>. Порядок отображения узлов одного
уровня определяется полем <Code>sort_order</Code>.
</Text>
<CodeBlock
title="Схема связей"
code={`approval_topic_categories (1) ──< (N) approval_topics (1) ──< (N) approval_flow_nodes
│
└── self-referencing: parent_id → id`}
/>
{/* ============================================================ */}
{/* 3. МОДЕЛЬ ДАННЫХ */}
{/* ============================================================ */}
<DocSection id="data-model" title="3. Модель данных" />
<Text>
Структура таблицы <Code>approval_flow_nodes</Code>:
</Text>
<Table withTableBorder withColumnBorders mt="md" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th style={{ width: 180 }}>Поле</Table.Th>
<Table.Th style={{ width: 100 }}>Тип</Table.Th>
<Table.Th>Описание</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td><Code>id</Code></Table.Td>
<Table.Td>BIGINT PK</Table.Td>
<Table.Td>Уникальный идентификатор узла</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>topic_id</Code></Table.Td>
<Table.Td>BIGINT FK</Table.Td>
<Table.Td>Ссылка на тему согласования</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>parent_id</Code></Table.Td>
<Table.Td>BIGINT FK NULL</Table.Td>
<Table.Td>Ссылка на родительский узел. NULL для корня</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>key</Code></Table.Td>
<Table.Td>TEXT NOT NULL</Table.Td>
<Table.Td>
Уникальный в рамках темы идентификатор узла. Используется
системой для навигации
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>label</Code></Table.Td>
<Table.Td>TEXT NOT NULL</Table.Td>
<Table.Td>Текст, отображаемый пользователю</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>data_key</Code></Table.Td>
<Table.Td>TEXT NULL</Table.Td>
<Table.Td>
Имя переменной, в которую сохраняется <Code>data_value</Code> при
выборе узла
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>data_value</Code></Table.Td>
<Table.Td>TEXT NULL</Table.Td>
<Table.Td>Значение, сохраняемое в <Code>data_key</Code></Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>is_input</Code></Table.Td>
<Table.Td>BOOLEAN</Table.Td>
<Table.Td>Признак узла текстового ввода</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>input_key</Code></Table.Td>
<Table.Td>TEXT NULL</Table.Td>
<Table.Td>Ключ для сохранения введённого текста (обычно <Code>content</Code>)</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>input_hint</Code></Table.Td>
<Table.Td>TEXT NULL</Table.Td>
<Table.Td>Подсказка-шаблон для пользователя</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>is_multi_select</Code></Table.Td>
<Table.Td>BOOLEAN</Table.Td>
<Table.Td>Признак узла мультиселекта</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>multi_select_key</Code></Table.Td>
<Table.Td>TEXT NULL</Table.Td>
<Table.Td>Ключ для сохранения выбранных значений</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>multi_select_value</Code></Table.Td>
<Table.Td>TEXT NULL</Table.Td>
<Table.Td>Значение данного варианта мультиселекта</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>topic_code</Code></Table.Td>
<Table.Td>TEXT NULL</Table.Td>
<Table.Td>
Код темы для проверки прав доступа. Если задан — узел отображается
только пользователям с правом <Code>create</Code> на указанную тему
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>sort_order</Code></Table.Td>
<Table.Td>INTEGER</Table.Td>
<Table.Td>Порядок сортировки среди узлов одного родителя</Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<Callout title="Уникальность ключей" mt="md">
На таблицу наложен уникальный индекс <Code>UNIQUE(topic_id, key)</Code>. Это
гарантирует, что в рамках одной темы не существует двух узлов с одинаковым
<Code>key</Code>. Нарушение этого условия приведёт к ошибке
<Code>SQLSTATE 23505</Code> при сохранении.
</Callout>
{/* ============================================================ */}
{/* 4. ТИПЫ УЗЛОВ */}
{/* ============================================================ */}
<DocSection id="node-types" title="4. Типы узлов" />
<Text>
Система поддерживает три типа узлов, определяемых комбинацией булевых полей
<Code>is_input</Code> и <Code>is_multi_select</Code>.
</Text>
<Table withTableBorder withColumnBorders mt="md" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th>Тип</Table.Th>
<Table.Th>is_input</Table.Th>
<Table.Th>is_multi_select</Table.Th>
<Table.Th>Назначение</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td>Кнопка</Table.Td>
<Table.Td>false</Table.Td>
<Table.Td>false</Table.Td>
<Table.Td>Выбор значения и переход к следующему шагу</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>Текстовый ввод</Table.Td>
<Table.Td>true</Table.Td>
<Table.Td>false</Table.Td>
<Table.Td>Ввод произвольного текста пользователем</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>Мультиселект</Table.Td>
<Table.Td>false</Table.Td>
<Table.Td>true</Table.Td>
<Table.Td>Выбор нескольких значений из списка</Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<DocSection id="node-button" title="4.1. Кнопка" level={2} />
<Text>
Базовый тип узла. При выборе кнопки система записывает в контекст пользователя
пару <Code>data_key = data_value</Code> и переходит к дочерним узлам.
</Text>
<Text fw={600} mt="md">Обязательные поля:</Text>
<Table withTableBorder withColumnBorders mt="xs" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th>Поле</Table.Th>
<Table.Th>Требования</Table.Th>
<Table.Th>Пример</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td><Code>key</Code></Table.Td>
<Table.Td>Уникальный в теме, snake_case</Table.Td>
<Table.Td><Code>crimea</Code></Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>label</Code></Table.Td>
<Table.Td>Непустая строка</Table.Td>
<Table.Td><Code>Крым</Code></Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>data_key</Code></Table.Td>
<Table.Td>snake_case, осмысленное имя</Table.Td>
<Table.Td><Code>region</Code></Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>data_value</Code></Table.Td>
<Table.Td>snake_case, уникальное в рамках data_key</Table.Td>
<Table.Td><Code>crimea</Code></Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<Callout title="Правило одного уровня" mt="md">
Все дочерние узлы одного родителя должны иметь одинаковое значение{' '}
<Code>data_key</Code>, но различные <Code>data_value</Code>. Это необходимо
для корректной работы шаблонизации: система ожидает, что по ключу{' '}
<Code>region</Code> будет получено ровно одно значение.
</Callout>
<DocSection id="node-input" title="4.2. Текстовый ввод" level={2} />
<Text>
Терминальный узел, запрашивающий у пользователя произвольный текст. Введённый
текст сохраняется в контекст по ключу <Code>input_key</Code>.
</Text>
<Text fw={600} mt="md">Обязательные поля:</Text>
<Table withTableBorder withColumnBorders mt="xs" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th>Поле</Table.Th>
<Table.Th>Требования</Table.Th>
<Table.Th>Пример</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td><Code>input_key</Code></Table.Td>
<Table.Td>Обычно <Code>content</Code></Table.Td>
<Table.Td><Code>content</Code></Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>input_hint</Code></Table.Td>
<Table.Td>Конкретный пример заполнения</Table.Td>
<Table.Td><Code>Опишите изменения: текущие → новые</Code></Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<Callout title="Требование терминальности">
Каждый путь от корня до листа дерева должен заканчиваться узлом типа «Текстовый
ввод». Отсутствие такого узла приведёт к невозможности завершения создания
заявки.
</Callout>
<DocSection id="node-multiselect" title="4.3. Мультиселект" level={2} />
<Text>
Специализированный узел, позволяющий пользователю выбрать несколько значений
одновременно. Все выбранные значения сохраняются через запятую в ключ
<Code>multi_select_key</Code>.
</Text>
<Text fw={600} mt="md">Обязательные поля:</Text>
<Table withTableBorder withColumnBorders mt="xs" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th>Поле</Table.Th>
<Table.Th>Требования</Table.Th>
<Table.Th>Пример</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td><Code>multi_select_key</Code></Table.Td>
<Table.Td>Одинаковый для всех дочерних узлов</Table.Td>
<Table.Td><Code>systems</Code></Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>multi_select_value</Code></Table.Td>
<Table.Td>Уникальный для каждого дочернего узла</Table.Td>
<Table.Td><Code>okb</Code>, <Code>1c</Code></Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<Text mt="md">
При выборе нескольких значений формируется строка вида{' '}
<Code>systems = "okb,1c"</Code>. Автоматически создаётся производная
переменная <Code>systems_label</Code>, содержащая человекочитаемые названия
через запятую: <Code>"ОКБ, 1С"</Code>.
</Text>
{/* ============================================================ */}
{/* 5. ПОТОК ДАННЫХ */}
{/* ============================================================ */}
<DocSection id="data-flow" title="5. Поток данных" />
<Text>
При прохождении пользователем дерева навигации формируется контекст
<Code>collected</Code> — ассоциативный массив, аккумулирующий все выбранные
значения. Процесс состоит из следующих этапов:
</Text>
<Stack gap="sm" mt="md">
<FlowStep
step={1}
title="Инициализация"
description="Пользователь выбирает тему в главном меню. Создаётся пустой контекст collected."
/>
<FlowStep
step={2}
title="Навигация по узлам"
description="При выборе каждого узла типа «Кнопка» в collected записывается пара data_key = data_value."
/>
<FlowStep
step={3}
title="Автоматическое обогащение"
description="Для каждого data_key автоматически создаётся производная переменная с суффиксом _label, содержащая значение поля label выбранного узла."
/>
<FlowStep
step={4}
title="Текстовый ввод"
description="На терминальном узле пользователь вводит текст, который сохраняется по ключу input_key (обычно content)."
/>
<FlowStep
step={5}
title="Формирование кода темы"
description="На основе collected и code_template вычисляется итоговый код темы для поиска в БД."
/>
<FlowStep
step={6}
title="Рендеринг сообщения"
description="На основе collected и message_template формируется текст сообщения для согласующего."
/>
<FlowStep
step={7}
title="Создание заявки"
description="Запись сохраняется в таблицу approvals со ссылкой на найденную тему."
/>
</Stack>
{/* ============================================================ */}
{/* 6. СТРУКТУРА COLLECTED */}
{/* ============================================================ */}
<DocSection id="collected" title="6. Структура collected" />
<Text>
Контекст <Code>collected</Code> — это <Code>map[string]string</Code>, содержащий
все данные, собранные в процессе прохождения дерева. Структура формируется
детерминированно на основе конфигурации узлов.
</Text>
<CodeBlock
title="Пример содержимого collected"
code={`{
"absence_type": "vacation",
"absence_type_label": "Отпуск",
"duration_type": "single_day",
"duration_type_label": "На один день",
"payment_type": "own_expense",
"payment_type_label": "За свой счёт",
"content": "22.02.2026"
}`}
/>
<Text mt="md">
Переменные с суффиксом <Code>_label</Code> формируются автоматически и не
требуют явного указания в дереве. Их значения соответствуют полю{' '}
<Code>label</Code> узла, в котором был задан соответствующий{' '}
<Code>data_key</Code>.
</Text>
<Callout title="Специальные ключи">
Ключ <Code>content</Code> зарезервирован для текста заявки, вводимого
пользователем. Ключ <Code>instructions</Code> заполняется автоматически из
поля <Code>instructions</Code> темы, если оно задано.
</Callout>
{/* ============================================================ */}
{/* 7. ШАБЛОНИЗАЦИЯ */}
{/* ============================================================ */}
<DocSection id="templates" title="7. Шаблонизация" />
<Text>
Шаблоны используют синтаксис <Code>text/template</Code> стандартной библиотеки
Go. Шаблоны хранятся в таблице <Code>approval_topics</Code> в полях
<Code>message_template</Code> и <Code>code_template</Code>.
</Text>
<DocSection id="message-template" title="7.1. message_template" level={2} />
<Text>
Определяет формат сообщения, отправляемого согласующему в Telegram. Поддерживает
HTML-разметку (<Code>&lt;b&gt;</Code>, <Code>&lt;i&gt;</Code>,{' '}
<Code>&lt;code&gt;</Code>).
</Text>
<CodeBlock
title="Пример"
code={`📋 <b>Менеджерские расходы — {{.region_label}}</b>
<b>{{.initiator_name}}</b>:
{{.content}}`}
/>
<DocSection id="code-template" title="7.2. code_template" level={2} />
<Text>
Определяет алгоритм формирования кода темы на основе <Code>collected</Code>.
Полученный код используется для поиска записи в таблице{' '}
<Code>approval_topics</Code>. Если шаблон не задан, код формируется
автоматически конкатенацией всех значений <Code>collected</Code> через
символ подчёркивания.
</Text>
<CodeBlock
title="Пример"
code={`{{if .pp_required}}non_budget_expenses_{{.branch}}_{{.expense_type}}_pp_{{.pp_required}}{{else}}non_budget_expenses_{{.branch}}_{{.expense_type}}{{end}}`}
/>
<Callout title="Согласованность с БД" mt="md">
Результат применения <Code>code_template</Code> должен точно соответствовать
значению поля <Code>code</Code> существующей записи в{' '}
<Code>approval_topics</Code>. В противном случае система вернёт ошибку
<Code>approval topic not found</Code>.
</Callout>
{/* ============================================================ */}
{/* 8. СИНТАКСИС */}
{/* ============================================================ */}
<DocSection id="syntax" title="8. Синтаксис шаблонов" />
<Text>
Доступные конструкции языка шаблонов:
</Text>
<Table withTableBorder withColumnBorders mt="md" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th style={{ width: 280 }}>Конструкция</Table.Th>
<Table.Th>Семантика</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td><Code>{`{{.key}}`}</Code></Table.Td>
<Table.Td>Вывод значения переменной</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>{`{{if .key}}...{{end}}`}</Code></Table.Td>
<Table.Td>Условный вывод (проверяется непустота)</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>
<Code>{`{{if eq .key "val"}}A{{else}}B{{end}}`}</Code>
</Table.Td>
<Table.Td>Ветвление по значению</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>
<Code>{`{{if ...}}...{{else if ...}}...{{else}}...{{end}}`}</Code>
</Table.Td>
<Table.Td>Множественное ветвление</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>{`{{trimPrefix .key "prefix"}}`}</Code></Table.Td>
<Table.Td>Удаление префикса из значения</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>{`{{trimSuffix .key "suffix"}}`}</Code></Table.Td>
<Table.Td>Удаление суффикса из значения</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>{`{{toUpper .key}}`}</Code></Table.Td>
<Table.Td>Приведение к верхнему регистру</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>{`{{toLower .key}}`}</Code></Table.Td>
<Table.Td>Приведение к нижнему регистру</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>{`{{contains .key "substr"}}`}</Code></Table.Td>
<Table.Td>Проверка вхождения подстроки</Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<Callout title="Отсутствие значения" mt="md">
При обращении к несуществующему ключу шаблонизатор выводит строку{' '}
<Code>&lt;no value&gt;</Code>. Это признак ошибки конфигурации: либо в дереве
отсутствует узел с соответствующим <Code>data_key</Code>, либо пользователь
не прошёл необходимый шаг.
</Callout>
{/* ============================================================ */}
{/* 9. СПРАВОЧНИК ПЕРЕМЕННЫХ */}
{/* ============================================================ */}
<DocSection id="variables" title="9. Справочник переменных" />
<Text>
Переменные, доступные в шаблонах, делятся на две категории: встроенные
(предоставляются системой) и пользовательские (формируются из дерева).
</Text>
<Text fw={600} mt="md">Встроенные переменные</Text>
<Table withTableBorder withColumnBorders mt="xs" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th style={{ width: 200 }}>Переменная</Table.Th>
<Table.Th>Источник</Table.Th>
<Table.Th>Описание</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td><Code>initiator_name</Code></Table.Td>
<Table.Td>Таблица <Code>users</Code></Table.Td>
<Table.Td>ФИО пользователя, создавшего заявку</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>topic_name</Code></Table.Td>
<Table.Td>Таблица <Code>approval_topics</Code></Table.Td>
<Table.Td>Название темы</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>content</Code></Table.Td>
<Table.Td>Текстовый ввод пользователя</Table.Td>
<Table.Td>Основной текст заявки</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>instructions</Code></Table.Td>
<Table.Td>Поле <Code>instructions</Code> темы</Table.Td>
<Table.Td>Инструкция для согласующего</Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
<Text fw={600} mt="md">Пользовательские переменные</Text>
<Text>
Формируются на основе <Code>data_key</Code> узлов дерева. Для каждого
<Code>data_key</Code> автоматически создаётся производная переменная с суффиксом
<Code>_label</Code>.
</Text>
<Table withTableBorder withColumnBorders mt="xs" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th style={{ width: 200 }}>Переменная</Table.Th>
<Table.Th>Типичное значение</Table.Th>
<Table.Th>Описание</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td><Code>region</Code></Table.Td>
<Table.Td><Code>crimea</Code>, <Code>krasnodar</Code></Table.Td>
<Table.Td>Идентификатор региона</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>region_label</Code></Table.Td>
<Table.Td><Code>Крым</Code>, <Code>Краснодар</Code></Table.Td>
<Table.Td>Человекочитаемое название региона</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>branch</Code></Table.Td>
<Table.Td><Code>f1</Code>, <Code>f2</Code></Table.Td>
<Table.Td>Идентификатор филиала</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>payment_type</Code></Table.Td>
<Table.Td><Code>own_expense</Code></Table.Td>
<Table.Td>Тип оплаты</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>systems</Code></Table.Td>
<Table.Td><Code>okb,1c</Code></Table.Td>
<Table.Td>Выбранные системы (мультиселект)</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td><Code>systems_label</Code></Table.Td>
<Table.Td><Code>ОКБ, 1С</Code></Table.Td>
<Table.Td>Названия выбранных систем</Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
{/* ============================================================ */}
{/* 10. ПРИМЕРЫ */}
{/* ============================================================ */}
<DocSection id="examples" title="10. Примеры конфигураций" />
<Text>
Ниже приведены типовые конфигурации для различных сценариев. Шаблоны могут
быть скопированы и адаптированы под конкретные требования.
</Text>
{/* Пример 1 */}
<Text fw={600} mt="xl">10.1. Простая тема с выбором региона</Text>
<Text size="sm" c="dimmed">
Сценарий: пользователь выбирает регион, затем вводит текст заявки.
</Text>
<CodeBlock
title="Структура дерева"
code={`Менеджерские расходы (корень, key=manager_expenses)
├── Крым (key=crimea, data_key=region, data_value=crimea)
│ └── Ввод (is_input=true, input_key=content)
└── Краснодар (key=krasnodar, data_key=region, data_value=krasnodar)
└── Ввод (is_input=true, input_key=content)`}
/>
<CodeBlock
title="message_template"
code={`📋 <b>Менеджерские расходы — {{.region_label}}</b>
<b>{{.initiator_name}}</b>:
{{.content}}`}
/>
<CodeBlock
title="code_template"
code={`manager_expenses_{{.region}}`}
/>
{/* Пример 2 */}
<Text fw={600} mt="xl">10.2. Многоуровневая тема с условной логикой</Text>
<Text size="sm" c="dimmed">
Сценарий: филиал → тип расхода → признак ПП → ввод. Формат кода темы
зависит от наличия признака ПП.
</Text>
<CodeBlock
title="Структура дерева"
code={`Внебюджетные расходы (корень)
├── Ф1 (data_key=branch, data_value=f1)
│ ├── ТМЦ (data_key=expense_type, data_value=tmc)
│ │ ├── Нужна ПП (data_key=pp_required, data_value=yes)
│ │ │ └── Ввод
│ │ └── Не нужна ПП (data_key=pp_required, data_value=no)
│ │ └── Ввод
│ └── Расход (data_key=expense_type, data_value=expense)
│ └── ...
└── Ф2 (data_key=branch, data_value=f2)
└── ... (без признака ПП)`}
/>
<CodeBlock
title="message_template"
code={`📋 <b>Внебюджетные расходы — {{.branch_label}} ({{.expense_type_label}})</b>
{{if .pp_required}}💳 <b>ПП:</b> {{.pp_required_label}}{{end}}
<b>{{.initiator_name}}</b>:
{{.content}}`}
/>
<CodeBlock
title="code_template"
code={`{{if .pp_required}}non_budget_expenses_{{.branch}}_{{.expense_type}}_pp_{{.pp_required}}{{else}}non_budget_expenses_{{.branch}}_{{.expense_type}}{{end}}`}
/>
{/* Пример 3 */}
<Text fw={600} mt="xl">10.3. Тема с мультиселектом</Text>
<Text size="sm" c="dimmed">
Сценарий: пользователь выбирает несколько систем одновременно.
</Text>
<CodeBlock
title="Структура дерева"
code={`Изменение клиента (корень)
├── Поменять название (data_key=change_type, data_value=rename)
│ └── Крым (data_key=region, data_value=crimea)
│ ├── ОКБ (is_multi_select=true, multi_select_key=systems, multi_select_value=okb)
│ │ └── Ввод
│ └── 1С (is_multi_select=true, multi_select_key=systems, multi_select_value=1c)
│ └── Ввод
└── ...`}
/>
<CodeBlock
title="message_template"
code={`📋 <b>Изменение клиентов: {{.change_type_label}}</b>
🖥 <b>Системы:</b> {{.systems_label}}
📍 <b>Регион:</b> {{.region_label}}
<b>{{.initiator_name}}</b>:
{{.content}}`}
/>
<CodeBlock
title="code_template"
code={`client_changes_{{.change_type}}_{{.region}}`}
/>
{/* Пример 4 */}
<Text fw={600} mt="xl">10.4. Составная тема с множественными сценариями</Text>
<Text size="sm" c="dimmed">
Сценарий: единая тема объединяет несколько подтипов (отпуск, отгул,
больничный) с различным форматированием сообщений.
</Text>
<CodeBlock
title="message_template"
code={`{{if eq .absence_type "timeoff"}}📋 <b>Тип: Отгул</b>
<b>{{.initiator_name}}</b>: прошу согласовать отгул
{{.content}}
<i>{{.payment_type_label}}</i>
{{else if eq .absence_type "vacation"}}📋 <b>Тип: Отпуск</b>
<b>{{.initiator_name}}</b>: прошу согласовать отпуск
{{.content}}
<i>{{.payment_type_label}}</i>
{{else if eq .absence_type "sickleave"}}📋 <b>Тип: Официальный больничный</b>
<b>{{.initiator_name}}</b>: прошу согласовать больничный
{{if .open_date}}Дата открытия: {{.open_date}}.
{{end}}{{.content}}
<i>{{.payment_type_label}}</i>
{{end}}`}
/>
<CodeBlock
title="code_template"
code={`{{if eq .absence_type "timeoff"}}timeoff_{{.duration_type}}_{{.time_type}}_{{.payment_type}}{{else if eq .absence_type "vacation"}}vacation_{{.duration_type}}_full_day_{{.payment_type}}{{else if eq .absence_type "sickleave"}}sickleave_{{trimPrefix .duration_type "sl_"}}_full_day_{{.payment_type}}{{end}}`}
/>
{/* ============================================================ */}
{/* 11. ОГРАНИЧЕНИЯ */}
{/* ============================================================ */}
<DocSection id="constraints" title="11. Ограничения и валидация" />
<Text>
При конфигурации деревьев необходимо соблюдать следующие ограничения:
</Text>
<Table withTableBorder withColumnBorders mt="md" fontSize="sm">
<Table.Thead>
<Table.Tr>
<Table.Th style={{ width: 60 }}>№</Table.Th>
<Table.Th style={{ width: 280 }}>Ограничение</Table.Th>
<Table.Th>Обоснование</Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
<Table.Tr>
<Table.Td>1</Table.Td>
<Table.Td>Уникальность <Code>key</Code> в рамках темы</Table.Td>
<Table.Td>
Обеспечивается уникальным индексом <Code>(topic_id, key)</Code>.
Нарушение приводит к ошибке <Code>SQLSTATE 23505</Code>.
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>2</Table.Td>
<Table.Td>
Единообразие <Code>data_key</Code> на одном уровне
</Table.Td>
<Table.Td>
Все дочерние узлы одного родителя должны иметь одинаковый{' '}
<Code>data_key</Code>. В противном случае в <Code>collected</Code>{' '}
появятся конфликтующие значения.
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>3</Table.Td>
<Table.Td>
Уникальность <Code>data_value</Code> среди братьев
</Table.Td>
<Table.Td>
Система не сможет различить узлы с одинаковыми <Code>data_key</Code>{' '}
и <Code>data_value</Code>.
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>4</Table.Td>
<Table.Td>Терминальность путей</Table.Td>
<Table.Td>
Каждый путь от корня до листа должен заканчиваться узлом типа
«Текстовый ввод».
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>5</Table.Td>
<Table.Td>Отсутствие циклов</Table.Td>
<Table.Td>
<Code>parent_id</Code> не может указывать на собственный узел или
его потомка. Проверяется при операциях перемещения.
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>6</Table.Td>
<Table.Td>Формат <Code>key</Code>, <Code>data_key</Code>, <Code>data_value</Code></Table.Td>
<Table.Td>
Только строчные латинские буквы, цифры и символ подчёркивания
(snake_case).
</Table.Td>
</Table.Tr>
<Table.Tr>
<Table.Td>7</Table.Td>
<Table.Td>Согласованность <Code>code_template</Code> с БД</Table.Td>
<Table.Td>
Результат применения шаблона должен соответствовать существующей
записи в <Code>approval_topics</Code>.
</Table.Td>
</Table.Tr>
</Table.Tbody>
</Table>
{/* ============================================================ */}
{/* 12. ДИАГНОСТИКА */}
{/* ============================================================ */}
<DocSection id="troubleshooting" title="12. Диагностика ошибок" />
<Text>
Типовые ошибки и методы их устранения:
</Text>
<Stack gap="md" mt="md">
<ErrorEntry
code="approval topic not found: &lt;code&gt;"
description="Сформированный code_template не соответствует ни одной записи в approval_topics."
resolution="Проверить, что в approval_topics существует тема с указанным code. Проверить корректность code_template."
/>
<ErrorEntry
code="function &quot;...&quot; not defined"
description="В шаблоне используется несуществующая функция."
resolution="Проверить синтаксис шаблона. Доступные функции: trimPrefix, trimSuffix, toUpper, toLower, eq, ne, contains, hasPrefix, hasSuffix."
/>
<ErrorEntry
code="&lt;no value&gt;"
description="Шаблон обращается к переменной, отсутствующей в collected."
resolution="Проверить, что в дереве существует узел с соответствующим data_key, и пользователь проходит через него."
/>
<ErrorEntry
code="duplicate key value violates unique constraint idx_flow_nodes_topic_key"
description="Попытка создать узел с key, уже существующим в данной теме."
resolution="Изменить key на уникальное значение. Проверить существующие узлы через SQL-запрос к approval_flow_nodes."
/>
<ErrorEntry
code="cyclic reference detected"
description="Попытка переместить узел под его собственного потомка."
resolution="Выбрать другого родителя, не являющегося потомком перемещаемого узла."
/>
<ErrorEntry
code="category not found for code=..."
description="В Registry загружены темы, для которых не найдена категория."
resolution="Проверить, что для каждой активной темы существует соответствующая категория. Удалить или деактивировать темы без категорий."
/>
</Stack>
<Divider mt="xl" />
<Text size="sm" c="dimmed" ta="center">
Конец документации. По вопросам конфигурации обращаться к разработчикам системы.
</Text>
</Stack>
</Box>
</Box>
)
}
// ================================================================
// Вспомогательные компоненты
// ================================================================
function DocSection({ id, title, level = 1 }: { id: string; title: string; level?: number }) {
return (
<Box id={id} pt={8}>
{level === 1 ? (
<Title order={2}>{title}</Title>
) : (
<Title order={3} c="dimmed">{title}</Title>
)}
</Box>
)
}
function CodeBlock({ title, code }: { title: string; code: string }) {
return (
<Paper withBorder mt="md">
<Group justify="space-between" px="sm" py={6} style={{ borderBottom: '1px solid var(--mantine-color-gray-3)' }}>
<Text size="xs" fw={600} c="dimmed" tt="uppercase" lts={0.5}>{title}</Text>
<CopyButton value={code}>
{({ copied, copy }) => (
<Tooltip label={copied ? 'Скопировано' : 'Копировать'}>
<ActionIcon
size="xs"
variant="subtle"
color={copied ? 'teal' : 'gray'}
onClick={copy}
>
{copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
</ActionIcon>
</Tooltip>
)}
</CopyButton>
</Group>
<Box p="sm">
<Code block style={{ fontSize: 12, whiteSpace: 'pre-wrap', lineHeight: 1.5 }}>
{code}
</Code>
</Box>
</Paper>
)
}
function Callout({ title, children, mt = 'md' }: { title: string; children: React.ReactNode; mt?: string }) {
return (
<Alert
variant="light"
color="gray"
title={title}
mt={mt}
styles={{
root: { borderLeft: '3px solid var(--mantine-color-gray-5)' },
title: { fontSize: 13, fontWeight: 600 },
message: { fontSize: 13 },
}}
>
{children}
</Alert>
)
}
function FlowStep({ step, title, description }: { step: number; title: string; description: string }) {
return (
<Group gap="md" align="flex-start">
<Box
style={{
width: 28,
height: 28,
borderRadius: '50%',
backgroundColor: 'var(--mantine-color-gray-1)',
border: '1px solid var(--mantine-color-gray-4)',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
}}
>
<Text size="xs" fw={700} c="dimmed">{step}</Text>
</Box>
<Box style={{ flex: 1 }}>
<Text size="sm" fw={600}>{title}</Text>
<Text size="sm" c="dimmed">{description}</Text>
</Box>
</Group>
)
}
function ErrorEntry({ code, description, resolution }: { code: string; description: string; resolution: string }) {
return (
<Paper withBorder p="sm">
<Code block style={{ fontSize: 12, marginBottom: 8 }}>{code}</Code>
<Text size="sm">{description}</Text>
<Text size="sm" mt={4}>
<Text span fw={600}>Решение: </Text>
<Text span c="dimmed">{resolution}</Text>
</Text>
</Paper>
)
}