---
id: design-doc-generate-block
title: "POST /api/projects/:id/doc-content/:nodeId/generate — Сгенерировать блок (SSE)"
domain: design-doc
kind: api-method
http: "POST /api/projects/:id/doc-content/:nodeId/generate"
---

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

## Сводка

| Поле | Значение |
|---|---|
| **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 | | _подтвердить_ |

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

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

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

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

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

```bash
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 блока](get-block-content.md#design-doc-get-block-content); сгенерировать сразу весь документ — [генерация всего документа](generate-all.md#design-doc-generate-all).

<!-- gen:start:related -->
## Связанные
- Экраны: [Design Doc](../screens/design-doc.md#design-doc-screen-design-doc)
- [Конвенции](../../../shared/conventions.md#conventions) · [Роли](../../../shared/roles.md#roles) · [Ошибки](../../../shared/errors.md#errors) · [Глоссарий](../../../shared/glossary.md#glossary)
<!-- gen:end:related -->

---

Human view: https://docs.vnimanie.ai/specbuilder/v1/domains/design-doc/api/generate-block/