Block Authoring PRD

1. Цель и продуктовый контекст

  • Бизнес-проблема: библиотека блоков является основой всей системы, и без удобного сценария авторинга пользователю трудно поддерживать её в актуальном, структурированном и повторно используемом состоянии.

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

  • Почему это важно сейчас: кодовая база уже содержит зрелый сценарий работы с блоками, но он не был оформлен как самостоятельная крупная функция.

  • Ожидаемый эффект: быстрее пополнять библиотеку блоков, проще поддерживать версии и меньше ошибаться при ручном редактировании.

2. Формулировка проблемы

  • Текущее состояние: блоки уже можно просматривать, искать, редактировать, версионировать и частично автоматизировать через AI-подсказки.

  • Проблемы без формализации:

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

  • не зафиксирована граница между ручным редактированием и AI-черновиком

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

  • почему недостаточно общей документации: страницы архитектуры описывают только общий контур, но не фиксируют пользовательские сценарии, ограничения и ожидания к жизненному циклу блока.

3. Пользователи и сценарии использования

  • Основные пользователи: авторы промптов, редакторы библиотек блоков, разработчики, поддерживающие наборы системных и доменных блоков.

  • Вторичные пользователи: архитектор prompt library, QA, проверяющий устойчивость сценариев редактирования и версионирования.

  • Основные сценарии:

  • найти существующий блок через дерево или поиск

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

  • создать новый блок с нуля

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

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

  • удалить блок, если на него никто не ссылается

  • получить AI-черновик нового блока

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

4. Область охвата и то, что не входит

Входит в область

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

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

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

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

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

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

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

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

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

Не входит в область

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

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

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

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

5. Критерии успеха

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

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

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

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

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

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

  • Система должна хранить блоки в виде версий и публиковать новую версию вместо перезаписи старой.

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

  • Система должна валидировать формат значений по умолчанию.

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

  • Система должна не позволять удалить блок, если он используется в композициях.

  • AI-подсказка должна попадать в форму редактирования, а не в хранилище.

7. Допущения и ограничения

  • библиотека блоков хранится локально в ObjectBox через engine

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

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

  • AI-генерация доступна только при настроенном провайдере

8. Зависимости и заинтересованные стороны

  • Зависимости:

  • BlocksModel

  • BlockEditorViewModel

  • tf::Engine

  • BlockRepository

  • IBlockGenerator

  • Заинтересованные стороны:

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

  • автор блоков

  • владелец настольного интерфейса

  • владелец AI-слоя

  • владелец ядра и механизма версионирования

9. Приёмка пилота и релиза

  • Пилот:

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

  • дерево, поиск и список версий работают согласованно

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

  • Релиз:

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

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

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