POST /api/projects/:id/doc-content/:nodeId/generate — Сгенерировать блок (SSE)

Сгенерировано из матриц + кода. Правки вносить в источники (docs/matrices/, server/routes/), не здесь.

Поле	Значение
HTTP	`POST /api/projects/:id/doc-content/:nodeId/generate`
Auth	`optionalAuth, requireProjectAccess` — гость + авторизованный, доступ к проекту (read/write)
Scope токена	`read_write`
PG-функции	`api.upsert_block_doc_content`, `api.get_block_prerequisites_content`
Таблицы	`block_doc_content`, `block_doc_content_history`, `collection_prompt`, `project_edge`, `project_node`, `content_item`
SRM	SRM-033, SRM-198
RP (права)	RP-111
Файл роута	`server/routes/projects.js`
Статус	partial, done

Аргументы запроса (best-effort из хендлера; путь-параметры опущены):

Аргумент	Где	Обяз.	Заметка
`mode`	query		подтвердить
`quality`	query		подтвердить

Коды ответов/ошибок (из хендлера): 403 (+ 200) — уточнить причины вручную

Для человека

Как открыть: откройте проект → вкладка «Doc» (▧) → у нужного блока нажмите «Сгенерировать». Текст начнёт появляться прямо в блоке по мере написания; рядом есть кнопка «Стоп», чтобы прервать.

Пишет текст одного блока за вас. В контекст идёт описание самого блока, его артефакты и — что важно — полный текст блоков-предшественников по графу зависимостей: раздел получается согласованным с тем, что уже написано «выше по течению».

Текст течёт потоком: вы видите его по мере генерации, а не ждёте готовый кусок целиком. Нажали «Стоп» — то, что успело написаться, сохраняется (не пропадает). По завершении блок остаётся открытым в режиме правки, чтобы можно было сразу поправить. Предыдущая версия уходит в историю — генерацию всегда можно откатить.

Запускать генерацию может владелец проекта (и гость — в своём проекте). На чужом документе, открытом только на чтение, кнопки нет. Точные правила — RP-111.

Для агента

Запись — токен со scope read_write (см. Конвенции); под ролью владельца, write-доступ к проекту обязателен. Ответ — поток text/event-stream (SSE), а не один JSON: события приходят по мере генерации.

Параметры (query):

Параметр	Значения	Назначение
`mode`	`full` (дефолт) · `outline`	Полный текст блока или только оглавление
`quality`	`fast` (дефолт) · `pro`	`pro` генерирует несколько вариантов, выбирает лучший и шлифует — дольше, но качественнее

Пример запроса (-N — не буферизовать поток):

curl -N -X POST "https://specbuilder.vnimanie.ai/api/projects/a1b2c3d4-.../doc-content/node-7/generate?mode=full&quality=fast" \
  -H "Authorization: Bearer tak_..."

Пример потока (имена событий — из server/services/docGenerator.js):

event: generating
data: {"nodeId":"node-7","label":"Сбор данных","phase":"full"}

event: chunk
data: {"nodeId":"node-7","text":"## Источники данных\n"}

event: chunk
data: {"nodeId":"node-7","text":"Витрина продаж, выгрузка CRM...\n"}

event: saved
data: {"nodeId":"node-7","version":4,"contentLength":1820,"tokenEstimate":540}

event: done
data: {"nodeId":"node-7","phase":"full"}

Текст копится из chunk-событий; saved означает, что результат записан в block_doc_content (предыдущая версия ушла в историю), done — поток закрыт. В режиме quality=pro дополнительно идут события quality_phase (генерация кандидатов → выбор → шлифовка). При обрыве соединения сервер прерывает генерацию (AbortController), уже накопленный текст сохраняется. Ошибки приходят событием error. Формат потока одинаков для cookie- и токен-клиента: SSE, не JSON и не Markdown-зеркало.

Прочитать готовый блок обратно — GET блока; сгенерировать сразу весь документ — генерация всего документа.

Связанные

Экраны: Design Doc
Конвенции · Роли · Ошибки · Глоссарий