GET /api/projects/:id/export/design-doc — Экспорт дизайн-дока

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

Поле	Значение
HTTP	`GET /api/projects/:id/export/design-doc`
Auth	`optionalAuth, requireProjectAccess` — гость + авторизованный, доступ к проекту (read/write)
Scope токена	`read`
PG-функции	`api.get_design_doc_data`
Таблицы	`project`, `project_node`, `content_item`, `space_layer`, `project_node_role`
SRM	SRM-028, SRM-029, SRM-030, SRM-031
RP (права)	RP-040, RP-041, RP-047, RP-048, RP-117
Файл роута	`server/routes/projects.js`
Статус	done

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

Аргумент	Где	Заметка
`format`	query	подтвердить
`role`	query	подтвердить
`roles`	query	подтвердить

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

Для человека

Как открыть: откройте проект → вкладка «Doc» (▧) → в верхней панели документа нажмите «Скачать документ .md». Файл сохранится на диск.

Собирает весь дизайн-док в один Markdown-файл. Документ строится по разделам (обзор, требования, подход, реализация, данные, инфраструктура) и в порядке зависимостей блоков. Где у блока есть написанный текст — попадает он; где текста ещё нет — раздел заполняется заготовкой-чек-листом из артефактов блока, чтобы документ не зиял пустотами.

Можно выгрузить документ с учётом выбранных специальностей — тогда в файл попадут только их задачи (то же, что фильтр в панели документа). В шапке файла указываются формулировка задачи проекта, дата, а при фильтре — список ролей. Скачать документ может любой, у кого есть доступ к проекту; гость — только свой. Точные правила — RP-117.

Для агента

Чтение — токен со scope read (см. Конвенции). Тела нет; всё управление — через query-параметры.

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

Параметр	Значения	Назначение
`format`	`file`	С `file` отдаётся готовый `.md`-файл (заголовки `Content-Disposition: attachment`, `text/markdown`); без него — JSON с собранным Markdown в поле
`roles`	список id через запятую	Фильтр по специальностям: в документ попадут только их задачи
`role`	один id	То же, что `roles`, но для одной роли

Пример запроса (JSON):

curl https://specbuilder.vnimanie.ai/api/projects/a1b2c3d4-.../export/design-doc \
  -H "Authorization: Bearer tak_..."

Ответ 200 (без format=file):

{
  "markdown": "# ML Design Doc: Аналитика продаж\n> **Задача:** ...\n---\n## 1. Overview\n...",
  "roles": [ { "id": "ds", "name": "Data Scientist" } ],
  "sections": [ { "id": "overview", "title": "1. Overview" } ]
}

С ?format=file тело — сам Markdown-документ (не обёрнутый в JSON), с именем вложения design-doc-<8 символов id>.md. В отличие от doc-content, это не зеркало ресурса, а готовый собранный документ: разделы по слоям, топологический порядок блоков, артефакты как подразделы, fallback на чек-лист для незаполненных блоков (server/services/designDocExport.js). Поэтому Accept: text/markdown и ETag/304 тут не применяются — формат выбирается через ?format. Если проекта нет — 404.

Эндпоинт фигурирует и как UI-выгрузка («Скачать .md»), и как агентный способ забрать весь документ одним вызовом, не обходя блоки по очереди.

Связанные

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