POST /api/admin/blocks — Создать справочный блок
Сгенерировано из матриц + кода. Правки вносить в источники (
docs/matrices/,server/routes/), не здесь.
| Поле | Значение |
|---|---|
| HTTP | POST /api/admin/blocks |
| Auth | requireSiteAdmin — только site-admin |
| Scope токена | read_write |
| PG-функции | api.upsert_template_block |
| Таблицы | — |
| SRM | — (вне SRM, документировано по коду) |
| RP (права) | — |
| Файл роута | server/routes/admin.js |
| Статус | по коду (вне SRM) |
Аргументы запроса (best-effort из хендлера; путь-параметры опущены):
| Аргумент | Где | Обяз. | Заметка |
|---|---|---|---|
default_roles | body | подтвердить | |
description | body | подтвердить | |
id | body | подтвердить | |
layer | body | подтвердить | |
layer_code | body | подтвердить | |
name | body | подтвердить | |
sort_order | body | подтвердить |
Коды ответов/ошибок (из хендлера): 201, 400, 500 (+ 200) — уточнить причины вручную
Для человека
Как открыть: войдите как site-admin (отдельная авторизация с TOTP, см. Вход в Admin Panel) → откройте Admin Panel → раздел справочника платформы → добавьте справочный блок и сохраните.
Заводит новый эталонный блок в глобальном справочнике — кирпичик, из которого потом собираются коллекции по умолчанию. У блока задаются имя, описание, набор ролей по умолчанию, слой (уровень на графе) и порядок сортировки.
Технически это операция upsert: если указать id уже существующего блока, поля перезапишутся, а новая запись не создастся. Слой указывается кодом (layer_code); если кода такого слоя в системе нет — операция отклоняется с ошибкой 400.
Кто может. Только site-admin. Справочник один на всю платформу, поэтому правки в нём видны во всех организациях.
Для агента
Токену недоступно ни на каком scope. Это site-admin-операция: маршрут защищён requireSiteAdmin (нужна активная TOTP-сессия), а агентный шлюз не пускает токены к /api/admin/* (server/auth/agentGate.js). Запрос с Authorization: Bearer tak_... → 403. Выполнять только под cookie-сессией site-admin, не под Bearer.
Тело запроса (JSON):
| Поле | Тип | Обяз. | Назначение |
|---|---|---|---|
id | string | да | Системный ключ блока (PK); существующий → перезапись (upsert) |
name | string | да | Отображаемое имя |
description | string | нет | Описание; пусто → '' |
default_roles | string[] | нет | Роли по умолчанию (id справочных ролей); пусто → [] |
layer_code | string | нет | Код слоя; нет → IMPLEMENTATION. Принимается также синоним layer. Неизвестный код → 400 |
sort_order | int | нет | Порядок; нет → 0 |
Пример (cookie-сессия site-admin):
curl -X POST https://specbuilder.vnimanie.ai/api/admin/blocks \ -b cookies.txt \ -H "Content-Type: application/json" \ -d '{"id":"feature-store","name":"Feature Store","layer_code":"IMPLEMENTATION","default_roles":["data-engineer"]}'Ответ 201:
{ "id": "feature-store" }Markdown-зеркала/affordances у ресурса нет.