Block Generation Runbook

1. Операционный обзор

Сервисная функция:

  • помогает автору получить AI-generated draft блока;

  • не является критичным runtime path;

  • не должна ломать обычный ручной authoring при сбоях.

Критичность:

  • средняя

Режим поддержки:

  • инженерная поддержка в рабочее время

2. Владение и модель поддержки

Основной владелец:

  • команда, поддерживающая textfoundry_ai

Смежные владельцы:

  • владелец BlockEditorViewModel

  • владелец engine integration для authoring workflow

3. Ключевые сигналы и наблюдаемость

На что смотреть:

  • auth errors провайдера;

  • transport failures;

  • parsing failures provider responses;

  • рост числа user-visible generation errors;

  • массовые случаи невалидных generated ids.

Признаки деградации:

  • пользователи массово видят Configure AI settings first;

  • drafts не загружаются в форму;

  • генерация стала резко хуже по качеству на representative prompts.

4. Типовые сбои

Типовые failure modes:

  • неправильная конфигурация провайдера Запрос не стартует или получает auth/endpoint error.

  • invalid response format Draft нельзя построить или провалена post-validation.

  • id collision Генерация формально завершилась, но результат отклонён engine.

  • low-quality output Пользователь видит suggestion, но не может использовать его без большой ручной переработки.

5. Реакция на инцидент

Порядок действий:

  1. Проверить AI settings: base_url, model, api_key, timeout.

  2. Проверить доступность endpoint.

  3. Проверить, воспроизводится ли ошибка на representative prompt.

  4. Посмотреть, это transport/auth/parsing/validation failure или просто quality issue.

  5. Если функция недоступна, перевести пользователя на manual block authoring.

6. Режимы деградации

Допустимые режимы деградации:

  • полностью отключить AI generation;

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

  • не скрывать деградацию под видом "успешной генерации".

7. Восстановление и проверка

После исправления:

  1. Повторно выполнить генерацию на known-good test prompt.

  2. Убедиться, что draft приходит в форму редактора.

  3. Убедиться, что id проходит validation.

  4. Проверить revision workflow на существующем блоке.

8. Когда эскалировать

Эскалировать нужно, если:

  • provider errors повторяются системно;

  • parsing/validation массово ломаются после изменения prompt policy;

  • GUI показывает успешную генерацию, но форма заполняется некорректно;

  • revision mode неожиданно меняет identity block.

9. Контакты эскалации

  • Team Lead: владелец authoring flow

  • AI owner: владелец generator/prompt policy

  • GUI owner: владелец block editor workflow