Composition Authoring System Design

1. Краткое резюме

Функция строит отдельный контур работы с композициями как с версионируемыми сборками из фрагментов. Это не просто текстовый редактор, а редактор структуры:

  • ссылки на блоки

  • статический текст

  • разделители

Редактор хранит рабочее состояние отдельно от опубликованной композиции и выпускает новую версию только по явному действию пользователя.

2. Контекст и границы

  • Входит:

  • список композиций

  • поиск

  • просмотр версий

  • редактор фрагментов

  • выпуск новой версии

  • снятие версии с использования

  • удаление

  • Не входит:

  • AI-переписывание блоков как основной способ редактирования

  • автоматическая нормализация без явного действия

  • удалённый серверный API композиции

3. Сводка требований

  • Функциональные требования:

  • загружать композицию и её версии

  • показывать структуру фрагментов

  • позволять добавлять, изменять, удалять и перемещать фрагменты

  • выпускать новую версию композиции

  • Нефункциональные требования:

  • воспроизводимость

  • понятность структуры

  • отсутствие скрытой мутации опубликованных версий

4. Компоненты и интеграции

Компоненты:

  • CompositionsPage.qml - список композиций и версии

  • CompositionsViewModel - выбор, версии, подробности, операции уровня списка

  • CompositionEditorWindow.qml - рабочая область редактора

  • CompositionEditorSidebar.qml - метаданные и редактирование выбранного фрагмента

  • CompositionEditorViewModel - состояние формы, фрагменты, сохранение

  • tf::Engine - загрузка, публикация, обновление, снятие версии с использования и удаление

  • CompositionRepository - постоянное хранение

Связанные сущности:

  • Composition

  • CompositionDraft

  • PublishedComposition

  • Fragment

  • BlockRef

  • StyleProfile

5. Основной сценарий работы

Diagram

6. Подробный поток

6.1 Выбор композиции и версии

  • пользователь выбирает композицию в списке

  • CompositionsViewModel загружает версии и подробности

  • выбранная версия становится основой для просмотра или редактирования

6.2 Создание новой композиции

  • редактор сбрасывает состояние

  • загружает список доступных блоков

  • пользователь собирает набор фрагментов

  • при сохранении создаётся черновик композиции и публикуется первая версия

6.3 Редактирование существующей композиции

  • редактор загружает выбранную опубликованную версию

  • преобразует её фрагменты во внутреннюю модель формы

  • пользователь вносит изменения

  • при сохранении engine публикует новую версию той же композиции

6.4 Работа с фрагментами

Поддерживаются операции:

  • добавить ссылку на блок

  • добавить статический текст

  • добавить разделитель

  • вставить новый фрагмент до или после выбранного

  • изменить выбранный фрагмент

  • удалить фрагмент

  • вырезать и вставить фрагмент

  • переставить фрагмент мышью

  • автоматически вставить переводы строки между соседними фрагментами

  • удалить все разделители

6.5 Связь с блоками

  • ссылка на блок хранит идентификатор, версию и локальные параметры

  • при сохранении проверяется формат версии блока

  • композиция опирается на библиотеку блоков, но не управляет жизненным циклом самих блоков

7. Надёжность и деградация

  • при ошибке загрузки композиции редактор не должен открывать неполное состояние

  • при ошибке публикации пользователь должен сохранить введённые данные формы

  • при ошибке версии блока сохранение должно быть остановлено до записи

  • дополнительные функции вроде нормализации не должны ломать базовый редактор

8. Модель состояния

Ключевые состояния:

  • выбранная композиция

  • выбранная версия

  • режим редактора: создание или редактирование

  • список доступных блоков

  • список фрагментов

  • выбранный фрагмент

  • режим вставки

  • буфер вырезанного фрагмента

  • признак несохранённых изменений

Это важно, потому что композиция редактируется как структурный объект, а не как одно текстовое поле.

9. Операционный итог

  • источник истины по опубликованным версиям — engine и репозиторий композиций

  • источник истины по рабочему состоянию — CompositionEditorViewModel

  • структура композиции важнее, чем её текстовое представление на экране

Связи вверх и вниз

Связи вверх:

Связи вниз: