Block Authoring ADR
1. Контекст
Для блоков в TextFoundry было важно выбрать не просто способ редактирования
текста, а способ управления библиотекой как версионируемым набором переиспользуемых
строительных элементов.
К моменту принятия решения в коде уже сложился следующий образ работы:
-
блоки хранятся как версии
-
пользователь видит дерево по пространствам имён
-
редактирование идёт через вкладки
-
сохранение создаёт новую версию
-
AI может предложить черновик, но не публикует его сам
Нужно зафиксировать, почему функция устроена именно так, а не как простая одностраничная форма редактирования текущего текста блока.
2. Проблема
Если рассматривать блок как обычную запись с полями, очень легко принять слишком простые решения:
-
открыть один редактор и всегда перезаписывать текущую запись
-
смешать просмотр, редактирование и публикацию в одно действие
-
позволить AI напрямую менять библиотеку
-
удалить блок без анализа того, используется ли он где-то ещё
Эти упрощения уменьшают объём кода в краткосрочной перспективе, но создают серьёзные архитектурные проблемы:
-
теряется воспроизводимость старых версий
-
композиции начинают зависеть от неявно изменившихся блоков
-
библиотека блоков перестаёт быть надёжным активом
-
AI начинает подменять собой авторское решение вместо помощи автору
3. Движущие силы решения
-
блок должен быть переиспользуемым и ссылочно стабильным элементом
-
старая версия должна оставаться доступной для существующих композиций
-
пользователь должен видеть несколько блоков одновременно и не терять несохранённые изменения
-
AI должен ускорять работу, но не обходить ручную проверку
-
удаление не должно ломать связанные композиции
4. Рассмотренные варианты
Вариант A: одна форма и перезапись текущего блока
Описание:
-
пользователь открывает блок
-
редактирует поля
-
нажимает сохранить
-
старая запись заменяется новой
Плюсы:
-
просто объяснить
-
проще реализовать на уровне пользовательского интерфейса
Минусы:
-
исчезает история изменений как отдельные версии
-
существующие композиции могут начать вести себя иначе без явного обновления
-
невозможно надёжно сравнивать версии и откатываться к предыдущему состоянию
Итог:
-
отклонено, потому что это противоречит самой идее библиотеки блоков как долговременного набора версионируемых артефактов.
Вариант B: одна активная вкладка редактора
Описание:
-
пользователь всегда работает только с одним блоком
-
при переключении на другой блок текущее состояние либо закрывается, либо перетирается
Плюсы:
-
проще модель интерфейса
-
меньше внутреннего состояния
Минусы:
-
неудобно сравнивать и править несколько блоков подряд
-
выше риск потери несохранённых изменений
-
неудобно совмещать ручное редактирование и AI-подсказки
Итог:
-
отклонено, потому что пользовательская задача авторинга библиотеки естественно многозадачна: нужно переключаться между блоками, не теряя контекст.
Вариант C: вкладочный редактор, версионирование и ручная публикация
Описание:
-
блоки просматриваются через дерево и список версий
-
каждый редактируемый блок открывается во вкладке
-
форма хранит временное рабочее состояние
-
сохранение публикует новую версию
-
AI только заполняет форму и предлагает черновик
Плюсы:
-
сохраняется история версий
-
пользователь контролирует публикацию
-
удобно работать с несколькими блоками параллельно
-
проще удерживать архитектурную границу между библиотекой и AI
Минусы:
-
интерфейс и состояние заметно сложнее
-
нужно отдельно управлять «грязным» состоянием вкладок
-
требуется больше проверки при закрытии и переключении
Итог:
-
выбранный вариант.
5. Принятое решение
Принято решение оформлять авторинг блоков как самостоятельный рабочий процесс с тремя ключевыми принципами:
-
блок редактируется через выпуск новой версии, а не через перезапись
-
форма редактора является временным рабочим состоянием, а не опубликованным источником истины
-
AI-черновик и AI-ревизия допускаются только как помощь пользователю и никогда не обходят ручную публикацию
Это решение включает следующие практические правила:
-
пользователь может открыть несколько блоков во вкладках
-
вкладки хранят собственные признаки несохранённых изменений
-
создание нового блока и редактирование существующего различаются явно
-
удаление разрешено только при отсутствии зависимостей в композициях
-
снятие версии с использования мягче, чем удаление, и не разрушает историю
6. Выбранный архитектурный срез
Распределение ответственности:
-
BlocksModel: -
дерево блоков
-
поиск
-
выбор версии
-
снятие с использования
-
удаление
-
BlockEditorViewModel: -
вкладки
-
состояние формы
-
сохранение
-
AI-режимы
-
tf::Engine: -
публикация новой версии
-
обновление существующего блока
-
проверка ограничений удаления
7. Последствия решения
Положительные:
-
библиотека блоков становится устойчивой и проверяемой
-
старые версии не исчезают
-
пользователь может безопасно редактировать несколько блоков
-
AI помогает, но не размывает границы ответственности
Отрицательные:
-
интерфейс сложнее и требует больше проверок состояния
-
пользователю нужно понимать разницу между формой, черновиком и опубликованной версией
-
код редактора и модели содержит больше внутреннего состояния
Операционные последствия:
-
ошибки надо делить на ошибки просмотра, публикации, удаления и AI-подсказки
-
тестирование должно отдельно покрывать версии, вкладки и ограничения удаления
8. Риски и меры
-
Риск: пользователь не поймёт, что сохранение создаёт новую версию, а не меняет старую. Мера: явно показывать текущую версию и использовать отдельный режим создания и редактирования.
-
Риск: AI-результат будет воспринят как «готовый правильный блок». Мера: AI только заполняет форму; публикация остаётся отдельным ручным шагом.
-
Риск: удаление разрушит связанные композиции. Мера: engine запрещает удаление блока, если он используется в композиции.
-
Риск: пользователь потеряет несохранённые изменения. Мера: вкладки отслеживают состояние изменений и интерфейс запрашивает явное подтверждение перед закрытием.
9. Что сознательно не делаем
-
не даём AI автоматически публиковать блок
-
не перезаписываем старую версию блока
-
не разрешаем безусловное удаление
-
не превращаем экран просмотра блоков в массовый редактор композиций
10. Влияние на будущие решения
Если позже появятся:
-
совместное редактирование
-
удалённый сервер библиотеки блоков
-
пакетные операции по блокам
то нельзя размывать базовые принципы этого решения:
-
версия важнее текущей формы
-
публикация важнее простого сохранения текста
-
AI остаётся вспомогательным инструментом
-
ссылочная целостность важнее удобства жёсткого удаления