История изменений и откат версий

Зачем это нужно

Страница документации живёт долго — и часто. Через месяц кто-то
перепишет абзац, через три — удалит половину, через полгода —
переименует. Когда в команде 10 человек, важно уметь ответить на
вопросы:

• «Кто и когда это написал?»

• «А что тут было до того, как Петя всё переделал?»

• «Можно ли откатиться на вчерашнюю версию?»

История Nextdocs даёт это всё автоматически. Никаких ручных «снимков»
делать не надо — каждое содержательное изменение сохраняется.

Где посмотреть

В редакторе страницы справа — три вкладки. Одна из них History.

Список показывает:

• Тип события — страница создана, переименована, перемещена в
  дереве, отредактирована, восстановлена, сгенерирована AI-агентом,
  обновлена AI-агентом.

• Кто сделал — имя пользователя или пометка «Agent», если
  изменение пришло от AI-генератора.

• Когда — относительное время («5 минут назад», «2 дня назад»)
  плюс точная дата по ховеру.

• Длительность сессии редактирования (для content edit) — например,
  «редактировалось 12 минут»: если человек правил текст полчаса с
  паузами, это будет одна запись, а не тридцать.

Что считается «одной записью»

Nextdocs не сохраняет снепшот после каждой нажатой клавиши — это
раздуло бы историю до тысяч бесполезных записей. Вместо этого:

• Пауза в 5+ минут закрывает текущий сеанс редактирования. Если
  вы печатали 20 минут без пауз — это один history entry,
  показывающий полный результат сеанса.

• Смена автора тоже завершает сеанс. Если коллега сохранил
  правку через 30 секунд после вас — это будут две записи.

• Переименование страницы — всегда отдельная запись, даже если
  случилось внутри сеанса редактирования.

• Перемещение в дереве — отдельная запись.

• Удаление страницы — единственный способ «потерять» страницу. В
  истории проекта запись останется, но восстановление идёт через
  otдельный механизм (см. «Восстановление удалённых»).

Как посмотреть старую версию

1. Откройте вкладку History.

2. Кликните по интересующей записи в списке.

3. Текст страницы в основном окне заменится на содержимое той
   версии. Это preview — вы её просматриваете, а не
   редактируете.

4. В верхней части появится баннер «Preview of version from
   22.04.2026 14:32» с кнопками:

   • Rollback to this version — сделать эту версию текущей.
     Откат не удаляет историю — в ней появится новая запись «Petr
     restored version from …».

   • Cancel — вернуться к актуальной версии без изменений.

Откат и его последствия

Когда вы делаете rollback:

• Текущее содержимое страницы не теряется — оно уходит в
  историю как предыдущая версия.

• Появляется новая запись: «Петя откатил страницу к версии
  22.04.2026». В её метаданных записано, какую именно версию
  восстановили.

• Коллеги, у которых страница открыта прямо сейчас, моментально
  видят обновлённый контент. Им может прийти toast-уведомление,
  что страница была откачена.

То есть rollback безопасен: «потерять» правки невозможно, всегда
можно откатиться обратно.

Восстановление удалённой страницы

Если кто-то удалил страницу целиком — она уходит в history проекта
со статусом deleted. Чтобы вернуть:

1. Откройте меню проекта (шестерёнка рядом с названием проекта в
   хедере страницы).

2. Project history → список всех событий в проекте.

3. Найдите запись page_deleted для нужной страницы.

4. Кнопка Restore — страница возвращается в дерево на то же
   место, где была; содержимое — последнее перед удалением.

Восстановление возможно в течение 90 дней с момента удаления.
После этого удалённые страницы полностью физически стираются.

Diff между версиями

Клик по записи в истории открывает preview. Если хочется сравнить
две версии построчно:

1. Кликните первую версию (она подсветится зелёным).

2. Shift-клик по второй (подсветится красным).

3. В основном окне появится diff: добавленное — зелёным,
   удалённое — красным, переименованные блоки — синим.

Активность агента

Если проект связан с репозиторием и был запущен AI-генератор
документации — записи от него выделены отдельным типом (agent_generate,
agent_update) и иконкой робота. Эти записи — ровно такие же, как
человеческие: по ним можно делать rollback, diff, preview.

Это полезно, если агент сгенерировал что-то не то — можно быстро
откатиться к последней «человеческой» версии.

Ограничения

• Полная глубина истории хранится 1 год, потом старые записи
  «схлопываются» в точки вида «контент на начало месяца».

• Одновременное редактирование через Yjs генерирует много
  micro-updates внутри сессии — они не хранятся отдельно. История
  это high-level записи, не CRDT-лог.

• История не включает изменения комментариев и прав доступа (для
  них — отдельные ленты в Activity).

• Diff работает по plain-text — в сложных диаграммах может выглядеть
  странно (JSON-дифф). Для визуального сравнения диаграмм пока
  удобнее открыть две версии в двух вкладках.

Типовые сценарии

«Коллега сломал страницу». Откройте History, найдите
последнюю «хорошую» запись, preview, убедитесь, rollback. Делу
минута.

«Хочу понять, почему мы пришли к такой формулировке». Откройте
старые версии подряд — увидите, как менялся раздел. Иногда в
метаданных есть ссылка на PR (если изменение пришло через AI-агента
при обновлении кода).

«Агент сгенерировал фигню поверх наших правок». Откройте историю
— последняя запись от человека перед агентом. Rollback. Затем в
настройках проекта можно явно сказать агенту не перегенерировать
этот раздел.