diff --git a/src/pages/flowNodes/FlowTreeGuidePage.tsx b/src/pages/flowNodes/FlowTreeGuidePage.tsx index 4d8cacc..6ecd9b7 100644 --- a/src/pages/flowNodes/FlowTreeGuidePage.tsx +++ b/src/pages/flowNodes/FlowTreeGuidePage.tsx @@ -7,15 +7,31 @@ import { Group, Box, Title, + Table, Divider, ActionIcon, + Tooltip, + CopyButton, ScrollArea, + Badge, Alert, UnstyledButton, + Timeline, + ThemeIcon, } from '@mantine/core' -import { IconArrowLeft, IconBulb, IconAlertTriangle } from '@tabler/icons-react' +import { + IconArrowLeft, + IconCopy, + IconCheck, + IconBulb, + IconAlertTriangle, +} from '@tabler/icons-react' import { useNavigate } from 'react-router-dom' +// ================================================================ +// Структура документации +// ================================================================ + interface DocSection { id: string title: string @@ -24,11 +40,19 @@ interface DocSection { const SECTIONS: DocSection[] = [ { id: 'overview', title: 'Что это такое', level: 1 }, - { id: 'principle-1', title: '1. Чтобы кнопка появилась в боте', level: 1 }, - { id: 'principle-2', title: '2. Как создать новую тему', level: 1 }, - { id: 'principle-3', title: '3. Как изменить существующую тему', level: 1 }, - { id: 'templates', title: 'Сообщение согласующему — важное правило', level: 1 }, - { id: 'check', title: 'Как проверить, что всё работает', level: 1 }, + { id: 'terms', title: 'Три простых понятия', level: 1 }, + { id: 'howto', title: 'Как создать дерево — по шагам', level: 1 }, + { id: 'step-1', title: ' 1. Выбрать категорию', level: 2 }, + { id: 'step-2', title: ' 2. Создать первый узел', level: 2 }, + { id: 'step-3', title: ' 3. Добавить варианты (ветки)', level: 2 }, + { id: 'step-4', title: ' 4. Завершить ветку вводом текста', level: 2 }, + { id: 'step-5', title: ' 5. Настроить сообщение согласующему', level: 2 }, + { id: 'step-6', title: ' 6. Проверить результат', level: 2 }, + { id: 'node-types', title: 'Три типа узлов', level: 1 }, + { id: 'example-1', title: 'Пример: «Отпуска»', level: 1 }, + { id: 'example-2', title: 'Пример: выбор из нескольких списков', level: 1 }, + { id: 'template-basics', title: 'Как писать сообщение согласующему', level: 1 }, + { id: 'tips', title: 'Советы и правила', level: 1 }, { id: 'troubleshooting', title: 'Если что-то не работает', level: 1 }, ] @@ -58,28 +82,43 @@ export default function FlowTreeGuidePage() { return ( - + Руководство - navigate('/nodes')}> + navigate('/nodes')} + > + {SECTIONS.map((section) => ( scrollTo(section.id)} - px={12} + px={section.level === 2 ? 20 : 12} py={6} style={{ borderRadius: 4, backgroundColor: - activeSection === section.id ? 'var(--mantine-color-blue-0)' : 'transparent', + activeSection === section.id + ? 'var(--mantine-color-blue-0)' + : 'transparent', borderLeft: activeSection === section.id ? '2px solid var(--mantine-color-blue-6)' @@ -87,7 +126,7 @@ export default function FlowTreeGuidePage() { }} > @@ -100,164 +139,531 @@ export default function FlowTreeGuidePage() { + {/* ============================================================ */} + {/* Основной контент */} + {/* ============================================================ */} + {/* Заголовок */} - Как настроить дерево заявок + Как настроить дерево согласования - Когда сотрудник создаёт заявку в боте, тот задаёт вопросы по очереди и предлагает - варианты ответа кнопками: «Какой регион?» → «Какая причина?» → «Опишите заявку». Эта - цепочка вопросов и есть дерево, и вы его собираете здесь — без программирования. + Это руководство для тех, кто настраивает бота — без программирования. + Здесь пошагово показано, как собрать «дерево» вопросов, которые бот задаёт + сотруднику, когда тот создаёт заявку: например, «Какой регион?» → + «Какая причина?» → «Опишите заявку». + {/* ============================================================ */} + {/* ОБЗОР */} + {/* ============================================================ */} + - Каждый раздел заявок («Отпуска», «Возвраты» и т.д.) — это отдельное дерево вопросов. - Каждый вопрос или кнопка внутри дерева — это шаг. Путь, который сотрудник проходит от - первого вопроса до текстового поля, в конце превращается в конкретную тему заявки со своими - согласующими. + Когда сотрудник создаёт заявку в Telegram-боте, бот задаёт ему вопросы по + очереди и предлагает варианты ответов кнопками. Например: «Выберите + регион» → «Крым» или «Краснодар» → «Опишите заявку текстом». Эта + последовательность вопросов и есть дерево. - - 🔘 Кнопка — сотрудник выбирает один из вариантов. 📝 Текстовый ввод — сотрудник - пишет заявку своими словами (этим всегда заканчивается путь). ☑️{' '} - Несколько вариантов сразу — как кнопка, но можно отметить сразу несколько пунктов. - - - Три условия, все должны выполняться одновременно: - - - а) Раздел, в котором лежит дерево, должен быть создан и активен — если раздела - ещё нет, нажмите «Новый раздел» прямо на странице конструктора. - - - б) От первого вопроса до этой кнопки должен существовать полный путь без обрывов - — то есть у каждого шага на пути есть родитель, а сама кнопка либо ведёт дальше, либо - заканчивается текстовым вводом. - - - в) Сотруднику должно быть выдано право видеть этот раздел. Это отдельная - настройка прав доступа — она делается ПОСЛЕ того, как дерево готово, в другом разделе - системы, не здесь. - - - - Сначала проверьте (а) и (б) — они настраиваются прямо в конструкторе. Если с деревом всё в - порядке — дело в правах доступа (в), обратитесь к тому, кто их настраивает. - - - - Порядок действий с нуля: - - - Шаг 1. На странице конструктора нажмите «Новый раздел», если подходящего ещё - нет — впишите название, технический код заполнится сам. - - - Шаг 2. Нажмите «Добавить первый вопрос» — это то, что сотрудник увидит первым. - - - Шаг 3. Наведите на созданный шаг, нажмите «+» и добавьте варианты ответа. У всех - кнопок одного вопроса поле «что запомнить» должно совпадать — конструктор подставляет - его сам, начиная со второй кнопки. - - - Шаг 4. Каждую ветку обязательно завершите шагом «Текстовый ввод» — без него - сотрудник не сможет закончить заявку. - - - Шаг 5. В окне редактирования любого шага есть кнопка «Проверить» — она покажет, - появилась ли для этого пути настроенная тема в системе. Если её ещё нет — рядом - появится кнопка «Создать тему», нажмите её, ничего искать в других разделах не нужно. - - - Шаг 6. На самом первом (корневом) шаге дерева настройте текст сообщения - согласующему — см. следующий раздел, это важно. - - - - - Найдите нужный раздел в выпадающем списке, разверните дерево и нажмите ✏️ на шаге, который - хотите поменять. Можно переименовать шаг, поменять подсказку для текстового ввода, добавить - новые варианты ответа или переставить шаги местами кнопками ↑ ↓ (среди соседних) и стрелками - с отступом (поднять/опустить на другой уровень вложенности). Все изменения сохраняются - сразу, отдельной кнопки «Сохранить» нет. + Вы настраиваете это дерево в разделе «Конструктор деревьев» — без единой + строчки кода. Каждый вопрос и каждая кнопка — это отдельный «узел», который + вы добавляете через простую форму. - - Удаление шага удаляет и все шаги, которые находятся под ним. Система переспросит перед - удалением. + + + Так настраиваются любые сценарии: отпуска, больничные, внебюджетные + расходы, возвраты и любые другие заявки. Если появится новый вид заявки — + не нужно ничего программировать, достаточно собрать новое дерево здесь. - - } color="orange" variant="light"> - - Текст сообщения и код темы настраиваются ОДИН РАЗ — на самом первом (корневом) шаге - дерева, а не на каждой отдельной ветке. - - + {/* ============================================================ */} + {/* ТРИ ПОНЯТИЯ */} + {/* ============================================================ */} + + + + Прежде чем начать, важно понимать всего три вещи: + + + + + + Понятие + Что это простыми словами + + + + + Категория + + Раздел заявок, который вы выбираете вверху страницы («Отпуска», + «Внебюджетные расходы» и т.д.). Одно дерево всегда строится + внутри одной категории. + + + + Узел + + Один шаг в дереве: кнопка с вариантом ответа, поле ввода текста + или список для множественного выбора. Узлы соединяются друг с + другом — у каждого может быть несколько «детей» (следующих + шагов). + + + + Тема заявки + + То, во что в итоге превращается пройденный сотрудником путь по + дереву. Например, путь «Крым → За свой счёт» превращается в + конкретную тему заявки со своими согласующими. + + + +
+ + + Дерево — это как схема метро: от начальной станции (первого вопроса) до + конечной (поля ввода текста) должен существовать путь через любые + промежуточные станции (кнопки-варианты). Ваша задача — построить эти пути. + + + {/* ============================================================ */} + {/* ПОРЯДОК СОЗДАНИЯ */} + {/* ============================================================ */} + + + + Ниже — точный порядок действий от пустой категории до готового, + работающего дерева. + + + + + + Откройте страницу «Конструктор деревьев» и в выпадающем списке «Категория» + выберите нужный раздел. Если подходящей категории ещё нет — обратитесь к + администратору, чтобы её создали (это отдельная настройка, не относится к + дереву). + + + + Если дерево для этой категории уже существует, вы увидите его сразу после + выбора. Можно смело редактировать — все изменения сохраняются + автоматически, ничего не потеряется. + + + + + + Нажмите кнопку «Добавить корневой узел». Это будет самый первый вопрос, + который увидит сотрудник. Откроется окно с тремя полями: + + + + + + Поле + Что писать + + + + + Тип узла + Оставьте «Кнопка» — для первого шага почти всегда нужна кнопка + + + Название + То, что увидит сотрудник, например «Отпуска» + + + Ключ + + Не трогайте — заполняется автоматически из названия + + + +
+ - Если раньше вы пытались настроить отдельное сообщение на каком-то шаге в середине дерева и - оно «не сохранялось» или не действовало — вот почему: система всегда смотрит только на - самый первый шаг. Чтобы сообщение отличалось в зависимости от выбора сотрудника, в тексте - используются условия — но настраивается это тоже на первом шаге, одним общим текстом. + Нажмите «Создать». Узел появится в дереве — с него всё и начинается. + + + + + Наведите на созданный узел — рядом появятся кнопки. Нажмите «+», чтобы + добавить к нему дочерний узел — следующий шаг вопроса. Повторяйте это для + каждого варианта ответа. + + + + Например, если первый узел — «Тип отпуска», добавьте к нему детей: + «Отпуск», «Отгул», «Больничный». Каждый из них — отдельная кнопка, которую + увидит сотрудник после выбора первого шага. + + + + Для узлов-кнопок в форме есть два поля: DataKey — название того, что + мы запоминаем (например «тип отпуска»), и DataValue — конкретное + значение этой кнопки (например «отпуск»). У всех кнопок-веток одного и того + же вопроса DataKey должен быть одинаковым, а DataValue — у каждой свой. + Смотрите готовый пример ниже — там всё видно на конкретных значениях. + + + + + + Каждая ветка дерева обязательно должна заканчиваться узлом «Текстовый + ввод» — это последний шаг, где сотрудник пишет саму заявку своими словами. + Добавьте такой узел к каждому «листу» дерева (к узлу, у которого больше нет + вариантов выбора). + + + + В форме выберите тип узла «Текстовый ввод» и заполните поле «Подсказка» — + это пример того, что должен написать сотрудник, чтобы ему было понятнее. + + + + Пройдите мысленно (или на бумаге) каждый путь от первого узла до конца. + Если какой-то путь обрывается на кнопке, не доходя до текстового ввода — + сотрудник не сможет завершить заявку. Добавьте туда узел ввода. + + + + + + На узле, где заявка «превращается» в конкретную тему (обычно это последний + узел-кнопка перед вводом текста), можно раскрыть блок «Шаблоны сообщения и + кода темы» и задать, как будет выглядеть уведомление у согласующего в + Telegram. Подробно про это — в разделе{' '} + «Как писать сообщение согласующему»{' '} + ниже. Если ничего не менять — сработает оформление по умолчанию. + + + + + + Дерево сохраняется автоматически после каждого действия — отдельной кнопки + «Сохранить всё» нажимать не нужно. Лучший способ проверить готовое дерево — + попросить коллегу создать тестовую заявку через бота и убедиться, что все + вопросы задаются в правильном порядке, а итоговое сообщение согласующему + выглядит понятно. + + + {/* ============================================================ */} + {/* ТИПЫ УЗЛОВ */} + {/* ============================================================ */} + + + + При создании или редактировании узла вы выбираете один из трёх типов: + + + + + + 🔘 + Кнопка + + + Сотрудник нажимает и переходит к следующему шагу. Используется для + любого выбора из вариантов: регион, тип заявки, филиал и т.д. + Требует заполнения DataKey и DataValue. + + + + + 📝 + Текстовый ввод + + + Сотрудник печатает текст. Всегда завершает ветку дерева — после + него бот создаёт заявку. Требует заполнения «Подсказки» — + примера того, что нужно написать. + + + + + ☑️ + Мультивыбор + + + Сотрудник может отметить сразу несколько вариантов (например, + несколько систем: «ОКБ» и «1С»). Все отмеченные варианты + сохранятся вместе, через запятую. + + + + + {/* ============================================================ */} + {/* ПРИМЕР 1 */} + {/* ============================================================ */} + + + + Разберём готовый пример целиком — от первого узла до отправки заявки. + Сценарий: сотрудник выбирает тип отсутствия, затем способ оплаты, затем + пишет причину. + + + + + + Название: Тип отсутствия. Тип узла: Кнопка. Это + «заголовок» дерева — сам по себе кнопкой сотруднику не показывается, + но от него отходят первые варианты. + + + + + Добавляем к корню три узла: Отпуск, Отгул,{' '} + Больничный. У всех трёх DataKey одинаковый —{' '} + absence_type, а DataValue разный: vacation,{' '} + timeoff, sickleave. + + + + + К узлу «Отпуск» добавляем два дочерних узла: За свой счёт{' '} + и В счёт отпуска. DataKey у обоих —{' '} + payment_type, DataValue — own_expense и{' '} + vacation_account соответственно. Аналогично поступаем с + ветками «Отгул» и «Больничный». + + + + + К каждому из узлов способа оплаты добавляем узел «Текстовый ввод» с + подсказкой: Укажите даты отпуска, например: 22.02.2026 — 25.02.2026. + + + + + На узле способа оплаты (там, где заявка уже точно определена) + открываем «Шаблоны сообщения и кода темы» и вписываем текст — см. + пример ниже. + + + + {{if eq .branch "f1"}}Филиал 1{{else}}Филиал 2{{end}} + title="Дерево целиком выглядит так" + code={`Тип отсутствия +├── Отпуск (absence_type = vacation) +│ ├── За свой счёт (payment_type = own_expense) → Ввод текста +│ └── В счёт отпуска (payment_type = vacation_account) → Ввод текста +├── Отгул (absence_type = timeoff) +│ ├── За свой счёт (payment_type = own_expense) → Ввод текста +│ └── В счёт отпуска (payment_type = vacation_account) → Ввод текста +└── Больничный (absence_type = sickleave) + └── Официальный (payment_type = official) → Ввод текста`} + /> + + + Что увидит сотрудник в боте: сначала кнопки «Отпуск / Отгул / + Больничный», затем — «За свой счёт / В счёт отпуска», затем поле для + ввода дат. Три нажатия и один текст — заявка готова. + + + Тип: {{.absence_type_label}} + +{{.initiator_name}} просит согласовать: {{.payment_type_label}} +{{.content}}`} + /> + + + Всё, что в фигурных скобках — подставится автоматически: название узла, + который выбрал сотрудник, его имя и текст, который он написал. Про этот + синтаксис подробнее — в разделе ниже. + + + {/* ============================================================ */} + {/* ПРИМЕР 2 */} + {/* ============================================================ */} + + + + Более сложный, но частый случай: нужно спросить у сотрудника два + независимых параметра подряд — например, филиал и тип расхода. + + + + + + Обратите внимание: узел «ТМЦ» повторяется дважды — под «Филиал 1» и под + «Филиал 2». Это нормально: узлы с одинаковым названием на разных ветках + дерева — это разные, независимые узлы, у каждого свой ключ (система + добавляет к ключу префикс родителя автоматически). + + + Внебюджетные расходы — {{.branch_label}} ({{.expense_type_label}}) {{.initiator_name}}: {{.content}}`} /> - - Не нужно запоминать этот синтаксис — на первом шаге дерева есть кнопка «Сформировать - черновик», которая сама подставит условия на основе первого вопроса дерева. Дальше можно - поправить текст руками и сразу посмотреть, как он будет выглядеть, через «Проверить готовую - ветку» в том же окне. - - - Поле «Код темы» почти всегда можно оставить пустым — тогда код соберётся сам из всех - выборов сотрудника. - - + {/* ============================================================ */} + {/* ШАБЛОНЫ */} + {/* ============================================================ */} + + - Под деревом есть блок «Проверка дерева» с кнопкой «Проверить все ветки» — он пройдёт по - каждому возможному пути и покажет, для всех ли есть настроенная тема. Это быстрее, чем - вручную проходить весь сценарий в Telegram, и находит проблему до того, как её найдёт - сотрудник. + В блоке «Шаблоны сообщения и кода темы» вы пишете обычный текст с + HTML-разметкой (<b>жирный</b>,{' '} + <i>курсив</i>) — так, как хотите видеть уведомление + у согласующего. В нужных местах вставляете «плейсхолдеры» в фигурных + скобках — они подставляются автоматически. + + + + Что написать + Что подставится + + + + + {`{{.initiator_name}}`} + Имя сотрудника, который создал заявку + + + {`{{.content}}`} + Текст, который сотрудник ввёл на последнем шаге + + + {`{{.название_кнопки_label}}`} + + Название выбранной сотрудником кнопки. Например, если DataKey + кнопки — region, пишите{' '} + {`{{.region_label}}`}, и туда подставится «Крым» или + «Краснодар» — смотря что выбрал сотрудник + + + +
+ + + Не нужно запоминать синтаксис. Откройте похожий уже настроенный узел (в + этой же или другой категории), скопируйте оттуда шаблон и замените + плейсхолдеры на DataKey ваших узлов. + + + + Дополнительно доступны несколько простых условий — пригодятся, если + сообщение должно немного отличаться в зависимости от выбора: + + + + + + + + Поле «Шаблон кода темы» обычно можно не трогать — если оставить пустым, + система сама соберёт код заявки из всех выборов сотрудника. Заполняйте его + только если вам явно сказали, что для этой темы нужен особый код + (например, если это уже настроенная в системе тема с заранее заданным + названием). + + + {/* ============================================================ */} + {/* СОВЕТЫ */} + {/* ============================================================ */} + + + + + + + + + + + + {/* ============================================================ */} + {/* ДИАГНОСТИКА */} + {/* ============================================================ */} + + + Частые ситуации и что с ними делать: + + + + - Остались вопросы — обратитесь к тому, кто настраивал вам эту систему. + Остались вопросы — обратитесь к администратору системы согласований.
@@ -265,10 +671,18 @@ export default function FlowTreeGuidePage() { ) } -function DocSection({ id, title }: { id: string; title: string }) { +// ================================================================ +// Вспомогательные компоненты +// ================================================================ + +function DocSection({ id, title, level = 1 }: { id: string; title: string; level?: number }) { return ( - {title} + {level === 1 ? ( + {title} + ) : ( + {title} + )} ) } @@ -276,11 +690,23 @@ function DocSection({ id, title }: { id: string; title: string }) { function CodeBlock({ title, code }: { title: string; code: string }) { return ( - - - {title} - - + + {title} + + {({ copied, copy }) => ( + + + {copied ? : } + + + )} + + {code} @@ -290,33 +716,51 @@ function CodeBlock({ title, code }: { title: string; code: string }) { ) } -function Callout({ title, children }: { title: string; children: React.ReactNode }) { +function Callout({ title, children, mt = 'md' }: { title: string; children: React.ReactNode; mt?: string }) { return ( - } title={title} mt="md"> + } + title={title} + mt={mt} + styles={{ + title: { fontSize: 13, fontWeight: 600 }, + message: { fontSize: 13 }, + }} + > {children} ) } +function TipEntry({ title, text }: { title: string; text: string }) { + return ( + + + + + + {title} + {text} + + + ) +} + function ErrorEntry({ title, description, resolution }: { title: string; description: string; resolution: string }) { return ( - - - {title} - + + + + {title} - - {description} - + {description} - - Что делать:{' '} - - - {resolution} - + Что делать: + {resolution} )