Block Authoring System Design

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

Функция строит полноценный пользовательский контур управления блоками:

  • просмотр дерева блоков

  • поиск по содержимому

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

  • редактирование в нескольких вкладках

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

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

  • удаление при соблюдении ограничений

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

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

  • Входит:

  • представление библиотеки блоков

  • выбор версии

  • чтение и отображение свойств блока

  • создание и редактирование блоков

  • сохранение новой версии

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

  • удаление блока

  • AI-черновик и AI-ревизия как вспомогательные потоки

  • Не входит:

  • редактирование композиций

  • пакетная генерация множества блоков

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

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

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

  • показывать дерево блоков по пространствам имён

  • показывать список версий выбранного блока

  • открывать редактор для нового или существующего блока

  • публиковать новую версию блока

  • блокировать удаление, если блок используется

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

  • предсказуемость состояния вкладок

  • читаемые ошибки

  • отсутствие скрытых изменений в хранилище

  • отделение AI-подсказки от публикации

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

Компоненты:

  • BlocksPage.qml - экран библиотеки блоков

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

  • BlockEditorViewModel - вкладки, состояние формы, сохранение, AI-сценарии

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

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

  • IBlockGenerator - необязательный источник AI-подсказок

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

  • Block

  • BlockDraft

  • PublishedBlock

  • Version

  • BlockType

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

Diagram

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

6.1 Просмотр и поиск

  • BlocksModel.reload() перечитывает библиотеку блоков

  • блоки раскладываются по дереву папок на основе идентификатора

  • поиск работает не только по имени блока, но и по описанию, шаблону, языку, тегам и значениям по умолчанию

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

6.2 Создание нового блока

  • пользователь открывает пустую вкладку создания

  • редактор хранит поля формы отдельно от хранилища

  • при сохранении создаётся BlockDraft

  • engine публикует первую или следующую версию

  • после успеха форма остаётся открытой, но переходит в режим редактирования уже существующего блока

6.3 Редактирование существующего блока

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

  • пользователь меняет поля формы

  • сохранение не перезаписывает прежнюю версию, а создаёт новую опубликованную версию через UpdateBlock

6.4 Снятие с использования и удаление

  • снятие с использования меняет состояние версии, но не удаляет запись

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

  • проверка зависимости выполняется в engine до удаления

6.5 AI-сценарии

  • generate() строит новый черновик на основе пользовательской инструкции

  • revise() строит новую подсказку на основе существующего блока и инструкции

  • в обоих случаях AI-результат только заполняет форму

  • окончательное решение о публикации принимает пользователь

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

  • при отсутствии AI-настроек ручной сценарий должен полностью работать

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

  • при ошибке генерации пользователь остаётся в редакторе без изменения хранилища

  • при невозможности удалить блок система должна явно объяснять причину

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

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

  • выбранный блок в дереве

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

  • набор открытых вкладок редактора

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

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

  • статус сохранения

  • статус AI-генерации

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

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

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

  • источник истины по опубликованным версиям - engine и хранилище

  • форма редактора - временное рабочее состояние

  • AI-подсказка - вспомогательный источник черновика, а не источник истины

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

Связи вверх:

Связи вниз: