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