POST /api/collections/:id/layers — Добавить слой
Сгенерировано из матриц + кода. Правки вносить в источники (
docs/matrices/,server/routes/), не здесь.
| Поле | Значение |
|---|---|
| HTTP | POST /api/collections/:id/layers |
| Auth | — |
| Scope токена | read_write |
| PG-функции | api.upsert_collection_layer |
| Таблицы | — |
| SRM | — (вне SRM, документировано по коду) |
| RP (права) | — |
| Файл роута | server/routes/collections.js |
| Статус | по коду (вне SRM) |
Аргументы запроса (best-effort из хендлера; путь-параметры опущены):
| Аргумент | Где | Обяз. | Заметка |
|---|---|---|---|
base_y | body | подтвердить | |
color | body | подтвердить | |
description | body | подтвердить | |
display_name | body | подтвердить | |
doc_title | body | подтвердить | |
id | body | подтвердить | |
sort_order | body | подтвердить |
Коды ответов/ошибок (из хендлера): 201 (+ 200) — уточнить причины вручную
Для человека
Как открыть: «Коллекции» → откройте коллекцию → в редакторе коллекции добавьте слой (на графе слои отображаются горизонтальными полосами; новый создаётся из панели управления слоями).
Слой — это этап будущего документа: блоки коллекции раскладываются по слоям, и каждый слой даёт свою полосу на графе и свой раздел в готовом документе. Задаёте надпись, цвет полосы и порядок сверху вниз.
У слоя есть ключ (id) — он задаётся при создании и дальше не меняется. Описание (description) можно не заполнять. Заголовок раздела документа (doc_title) необязателен: если оставить пустым, в документе используется надпись слоя.
Коллекция должна быть активной — добавить слой в коллекцию из корзины нельзя (404).
Кто может. Редактировать состав коллекции может администратор организации-владельца (и администратор площадки). Сотрудник и наблюдатель содержимое коллекции не меняют.
Для агента
Запись — нужен токен со scope read_write (см. Конвенции). У роута нет route-middleware; права досматривает PG-функция: редактировать содержимое коллекции может только org-admin владеющей организации (или site-admin), под чьей ролью идёт токен.
Insert-or-update по паре (collection_id, id): тот же эндпоинт обновит существующий слой, если передать занятый id. Для явного изменения по ключу из пути используйте PUT.
Тело запроса (JSON):
| Поле | Тип | Обяз. | Назначение |
|---|---|---|---|
id | string | да | Ключ слоя (системный, неизменяемый) |
display_name | string | да | Отображаемая надпись слоя |
color | string | да | Цвет полосы слоя (hex) |
base_y | number | нет | Вертикальная позиция полосы; по умолчанию 0 |
sort_order | integer | нет | Порядок слоёв; по умолчанию 0 |
description | string | нет | Описание этапа; по умолчанию "" |
doc_title | string | нет | Заголовок раздела документа; пустая строка → null (тогда берётся display_name) |
Пример запроса:
curl -X POST https://specbuilder.vnimanie.ai/api/collections/0660b640-86b0-42c5-8e22-93973848bb56/layers \ -H "Authorization: Bearer tak_..." \ -H "Content-Type: application/json" \ -d '{"id":"requirements","display_name":"Требования","color":"#0ea5e9","sort_order":2,"doc_title":"Функциональные требования"}'Ответ 201:
{ "ok": true }Коллекция в корзине → 404 (COLLECTION_NOT_FOUND). Cookie-клиент получает JSON; Markdown-зеркало отдаётся только токену с Accept: text/markdown (server/agent/negotiate.js).