Block Generation System Design

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

Block Generation реализует AI-assisted authoring workflow для одного блока. Архитектурно функция отделяет:

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

  • provider-specific generation;

  • engine-level validation;

  • ручную публикацию итогового результата.

Главный принцип: AI помогает получить draft, но не становится частью deterministic rendering и не обходит обычный lifecycle блока.

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

В области охвата:

  • single-block generation;

  • AI revision существующего блока;

  • структурная валидация результата;

  • загрузка результата в редактор блока;

  • ручное сохранение новой версии.

Вне области охвата:

  • batch slicing;

  • автоматическая публикация;

  • hidden invocation из render path;

  • quality ranking нескольких кандидатов;

  • server-side orchestration.

3. Архитектурные требования

Функция должна:

  • вызываться только по explicit user action;

  • зависеть в core только от IBlockGenerator;

  • не изменять storage без отдельного Save;

  • валидировать generated data до попадания в authoring flow;

  • поддерживать graceful degradation при отсутствии AI-конфигурации;

  • быть совместимой с versioned block lifecycle.

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

Основные компоненты:

  • BlockEditorViewModel Управляет формой, режимами generate и revise, статусами и загрузкой результата в UI.

  • tf::Engine Вызывает generator, валидирует результат, обеспечивает единый orchestration layer.

  • IBlockGenerator Порт для AI-assisted block generation.

  • OpenAiCompatibleBlockGenerator Конкретная реализация провайдера.

  • QtHttpTransport Сетевой транспорт для AI adapter layer.

  • SessionViewModel Пересобирает engine при изменении AI-конфигурации и подключает generator.

5. Данные и контракты

Входной контракт:

  • BlockGenerationRequest Содержит prompt, optional hints и список существующих block_id.

Выходной контракт:

  • GeneratedBlockData Содержит id, type, language, description, templ, defaults, tags.

Связанные доменные ограничения:

  • id должен быть валидным и стабильным;

  • template не должен быть пустым;

  • коллизии с уже существующими id недопустимы, кроме контролируемого revision сценария.

6. Основной сценарий

Diagram

Шаги:

  1. Пользователь вводит AI instruction.

  2. GUI собирает BlockGenerationRequest.

  3. Engine вызывает IBlockGenerator.

  4. Ответ модели проходит engine-level validation.

  5. Валидный результат загружается в форму.

  6. Пользователь вручную редактирует и сохраняет новую версию.

7. Режим ревизии существующего блока

Для revise используется тот же базовый генератор, но другой orchestration:

  • в prompt включается текущий блок;

  • identity блока должна сохраняться;

  • allow_id_collision = true, потому что обновляется тот же id;

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

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

Это позволяет не плодить отдельный AI service contract для revision, но сохранять другой policy.

8. Обработка ошибок и деградация

При отсутствии generator:

  • engine возвращает explicit error;

  • GUI сообщает о необходимости настроить AI settings.

При ошибке провайдера:

  • storage не меняется;

  • пользователь остаётся в обычном ручном authoring workflow.

При невалидном результате:

  • engine отклоняет его до попадания в form state.

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

Функция:

  • explicit и opt-in;

  • не меняет deterministic render behavior;

  • зависит от конфигурации base_url, model, api_key, timeout;

  • пересобирается через session layer при изменении AI settings.

10. Связанные документы

Upstream:

Downstream: