POST /api/projects/:id/generate — Сгенерировать граф (SSE)

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

Поле	Значение
HTTP	`POST /api/projects/:id/generate`
Auth	`optionalAuth, requireProjectAccess` — гость + авторизованный, доступ к проекту (read/write)
Scope токена	`read_write`
PG-функции	`api.update_project_status`, `api.replace_project_graph`
Таблицы	`project`, `space_block`, `collection_prompt`, `space_specialty`, `project_node`, `project_edge`, `project_node_role`, `content_item`
SRM	SRM-011, SRM-012, SRM-013, SRM-014
RP (права)	RP-001, RP-002, RP-014
Файл роута	`server/routes/projects.js`
Статус	done

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

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

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

Для человека

Как открыть: из списка проектов откройте проект — попадёте на экран графа. Если граф ещё пуст, на нём есть кнопка генерации; если граф уже построен — кнопка перегенерации. Здесь же при необходимости задают подсказку и выбирают качество.

Раскладывает описание задачи на граф: продукт подбирает нужные блоки коллекции, пишет к каждому описание с ролями и проставляет связи между ними. Прогресс виден сразу — этапы (подбор блоков, описания, связи) сменяют друг друга, узлы и стрелки появляются на холсте по мере готовности, а не все разом в конце.

Перегенерация полностью заменяет текущий граф. Можно задать подсказку — короткое пожелание к этому прогону (например «упор на безопасность» или «без этапа деплоя»), до 10000 символов; длиннее — ошибка 400.

Качество:

Быстрое — один проход, дешевле и быстрее.
Pro — режим повышенного качества: продукт строит несколько вариантов и выбирает лучший с доработкой. Точнее, но заметно дольше и дороже.

Кто может. Перегенерировать граф может тот, кто вправе его менять: владелец проекта (write-доступ) или гость — но только свой проект в гостевом спейсе. Наблюдатель и читатель без права записи получат 403.

Для агента

Запись — нужен токен со scope read_write (см. Конвенции). Вызов идёт под ролью владельца токена: гость генерирует только свой проект в гостевом спейсе (заголовок X-Guest-Projects с id проекта), владелец — при write-доступе. Иначе — 403.

Это не обычный JSON/Markdown-ресурс. Ответ — поток Server-Sent Events (Content-Type: text/event-stream), а не одно тело. Соединение держится открытым до конца генерации; контент-негоциация (Accept: text/markdown, ETag/304) к этому методу не применяется.

Тело запроса (JSON):

Поле	Тип	Обяз.	Назначение
`instruction`	string	нет	Подсказка к этому прогону, прокидывается во все 3 этапа. ≤ 10000 символов, иначе `400`
`quality`	string	нет	`fast` (по умолчанию) или `pro` — Pro-режим, дороже

Пример запроса:

curl -N -X POST https://specbuilder.vnimanie.ai/api/projects/a1b2c3d4-.../generate \
  -H "Authorization: Bearer tak_..." \
  -H "Content-Type: application/json" \
  -d '{"quality":"fast"}'

-N (--no-buffer) обязателен — иначе curl придержит поток и события не будут видны в реальном времени.

Поток событий: каждое событие — строки event: <stage> и data: <json>, разделённые пустой строкой. Этапы идут по порядку decomposition → descriptions → dependencies; внутри каждого приходят granular-события (decomp-block, node, edge), а в pro — ещё quality_phase. В конце — complete с id проекта; при сбое этапа — error (генерация падает в шаблонный fallback, а не обрывается).

event: stage
data: {"stage":"decomposition","status":"started"}

event: decomp-block
data: {"block_id":"data-collection","name":"Сбор данных","count":1}

event: stage
data: {"stage":"decomposition","status":"complete","count":6}

event: stage
data: {"stage":"descriptions","status":"started"}

event: node
data: {"block_id":"data-collection","roles":["ml-engineer"]}

event: stage
data: {"stage":"dependencies","status":"complete","count":7}

event: complete
data: {"project_id":"a1b2c3d4-..."}

Сохранённый граф читается после complete обычными read-методами набора project (см. создание проекта): GET /api/projects/{id}/graph.

Связанные

Экраны: Создание проекта
Конвенции · Роли · Ошибки · Глоссарий