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