Версіонування сценаріїв: навіщо і як це працює

Навіщо потрібна історія версій

Сценарій бота — це живий документ. Команда редагує його регулярно: додає нові гілки, змінює тексти повідомлень, переробляє логіку клавіатур. З часом стає важко відповісти на прості запитання:

• «Хто прибрав кнопку "Повернутися в меню" на минулому тижні?»
• «Як виглядав сценарій до того, як ми запустили акцію?»
• «Чи можемо ми повернутися до версії, яка нормально працювала?»

Версіонування вирішує ці проблеми. Кожне збереження — це знімок стану, до якого можна звернутися будь-коли.

Що таке версія

Версія — це незмінний зліпок усього сценарію: всіх секцій, вузлів, переходів між ними і перекладів. Новий знімок з’являється після публікації сценарію (кнопка «Опублікувати» та діалог збереження).

Версія не займає помітного місця в порівнянні з основними даними — зберігається лише diff і компактна копія структури графа.

Що зберігається у версії

Життєвий цикл версій

Зміна сценарію
     ↓
Публікація (кнопка «Опублікувати») з діалогом коментаря
     ↓
Engine фіксує новий запис у журналі збережень сценарію
     │
     ├── description (коментар, якщо вказаний)
     ├── constructor_user_email (автор)
     ├── createdAt (час)
     └── json_layout (повний граф у форматі нового конструктора)
     ↓
Версія стає доступною в «Історії версій»

Важливо: новий запис у історії з’являється після публікації сценарію через діалог збереження, а не «на льоту» під час кожного кліку в редакторі.

Як версії пов'язані з поточним сценарієм

Завжди є тільки одна «жива» версія — та, що завантажується під час роботи в Scenario Builder. Всі інші версії зберігаються в архіві і не впливають на виконання сценарію ботом.

Коли ви відновлюєте стару версію, відбувається таке:

1. Система завантажує граф обраної версії.
2. Публікує його як новий поточний стан.
3. Автоматично зберігає новий запис в архіві з позначкою «Відновлено з версії X».

Таким чином, попередній поточний стан не зникає — він залишається в архіві, і ви завжди можете «скасувати скасування».

Хто бачить версії

Доступ до перегляду та відновлення версій контролюється правами на збереження сценарію (scenario.sections.scenario.canSave). Якщо у вас є право зберігати сценарій — ви також можете переглядати версії і відновлювати їх.

Рекомендації для команд

Завжди пишіть коментар при публікації

Пустий коментар — це втрачений контекст. Навіть короткий запис «Оновив тексти привітання» допомагає колегам орієнтуватися без потреби переглядати граф.

Хороші коментарі:

• «Додав секцію для обробки скарг»
• «Прибрав кнопку "Назад" з вузла 55»
• «Виправив логіку умови: тепер перевіряємо статус замовлення правильно»

Погані коментарі:

• «Зміни»
• «Fix»
• (пусто)

Робіть «контрольні точки» перед великими змінами

Якщо плануєте суттєво переробити сценарій — спочатку збережіть поточний стан з коментарем «Контрольна точка перед редизайном FAQ». Це дає страховку: якщо щось піде не так, ви одразу знаєте, до чого відкочуватися.

Переглядайте версії, а не просто відновлюйте

Перед відновленням завжди використовуйте режим перегляду, щоб переконатися, що обрана версія — саме та, яка потрібна. Відновлення само по собі нешкідливе (попередній стан збережеться), але зайві операції захаращують архів.

Технічні деталі (для адміністраторів)

• Записи історії зберігаються в базі даних інстанції (технічна колекція kw_save_bots_logs).
• Щоб версія з’являлася у вікні Історія версій нового конструктора, у записі має бути повний граф у форматі нового редактора. Якщо адміністратор ще не вмикав відповідне збереження для інстанції, старі записи можуть містити лише попередній формат даних і не показуватися в цьому списку.
• За один запит інтерфейс підвантажує обмежену кількість записів; подальші з’являються під час прокрутки.