POST /api/spaces/:id/layers/:layerId — Переопределить слой
Сгенерировано из матриц + кода. Правки вносить в источники (
docs/matrices/,server/routes/), не здесь.
| Поле | Значение |
|---|---|
| HTTP | POST /api/spaces/:id/layers/:layerId |
| Auth | — |
| Scope токена | read_write |
| PG-функции | — |
| Таблицы | — |
| SRM | — (вне SRM, документировано по коду) |
| RP (права) | — |
| Файл роута | server/routes/spaces.js |
| Статус | по коду (вне SRM) |
Аргументы запроса (best-effort из хендлера; путь-параметры опущены):
аргументов не обнаружено (подтвердить вручную по server/routes/spaces.js)
Коды ответов/ошибок (из хендлера): 200 — уточнить причины вручную
Для человека
Как открыть: верхняя панель → «Спейсы» → карточка спейса → вкладка «Слои». Дальше либо правьте поле у существующего слоя (рядом появится пометка «изменено»), либо нажмите «Добавить» — создаётся свой, кастомный слой.
Операция переопределения слоя поверх коллекции. Сама коллекция не меняется: правки складываются в оверлей спейса. Здесь у метода две роли:
- переопределить базовый слой — задать в этом спейсе своё отображаемое имя, цвет, позицию, порядок, описание или заголовок раздела документа (
doc_title), не трогая коллекцию. Переопределённое поле помечается «изменено» и в любой момент откатывается к исходному (снять переопределение); - добавить свой слой — если слоя с таким id в коллекции нет, заводится кастомный (
is_custom), живущий только в этом спейсе.
Заголовок раздела документа стоит пояснить отдельно: это то, как этап назовётся в готовом документе. Если поле пустое, берётся отображаемое имя слоя.
Не путайте с «вернуть исходное» (откат поля к коллекции) и «вернуть» (возврат ранее скрытого слоя).
Кто может. Менеджер своего спейса или администратор организации (RP-128 для переопределения, RP-134 для своего слоя). Сотрудник и наблюдатель оверлей не настраивают.
Для агента
Запись — токен со scope read_write (см. Конвенции). Доступ проверяет тот же guard, что в UI (requireSpacemanOrOrgAdmin): спейсмен этого спейса или администратор его организации, иначе 403. В agent-gate путь занесён в write-allowlist точным шаблоном — он и есть граница безопасности (server/auth/agentGate.js).
POST и PUT ведут к одному обработчику (upsertLayer): «создать-или-обновить». Путь-параметры — :id (спейс) и :layerId (слой коллекции или новый кастомный id).
Тело запроса (JSON, все поля опциональны — переопределяются только переданные):
| Поле | Тип | Назначение |
|---|---|---|
display_name | string | Отображаемое имя слоя |
color | string | Цвет дорожки |
base_y | number | Базовая вертикальная позиция |
sort_order | number | Порядок |
is_custom | bool | true для своего слоя, которого нет в коллекции |
description | string | Описание |
doc_title | string | Заголовок раздела документа (пусто → берётся display_name) |
Пример запроса:
curl -X POST https://specbuilder.vnimanie.ai/api/spaces/{id}/layers/{layerId} \ -H "Authorization: Bearer tak_..." \ -H "Content-Type: application/json" \ -d '{"display_name":"Подготовка данных","doc_title":"Сбор и очистка данных"}'Ответ 200: { "ok": true }. Тело плоское — Markdown-зеркала и ETag у мутации нет; результат смотрите в списке слоёв.