iac/apps/control-interface/ENDPOINTS.md

Эндпоинты, с которыми взаимодействует srx-admin

Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается приложение srx-admin (панель администрирования, деплой control-interface).

Как устроено взаимодействие

srx-admin — это монорепозиторий (admin-monorepo) c двумя фронтенд-сервисами и общим пакетом:

• services/admin — хост-приложение (основной админ-интерфейс);
• services/assets — федеративный модуль (Module Federation), встраиваемый в хост;
• packages/app-kit — общий пакет с реестром API-функций и таблицей хостов.

Запросы описаны не единым реестром, а по доменам — в файлах shared/api/fetch/*.api.ts. Каждый домен экспортирует фабрику (например UserApi, AssetApi, ProjectApi), которая принимает httpService и возвращает набор методов. Внутри метода вызывается httpService.getRequest/postRequest/putRequest/patchRequest/deleteRequest со структурой:

• service — логическое имя сервиса (см. таблицу хостов ниже);
• url — путь запроса (с подстановкой параметров прямо в строку или через axiosConfig.params);
• data — тело запроса (для POST/PUT/PATCH);
• axiosConfig, cache, queryKey, controller, isCSRF — опции axios, кеширования, ключа запроса, отмены и CSRF-токена.

httpService создаётся в shared/api/http-service.ts через createHttpService из @sarex-team/sdk-js. Базовый хост подставляется по логическому имени service из packages/app-kit/src/shared/api/hosts.ts в зависимости от окружения сборки __ENDPOINT__ (BUILD_ENV, по умолчанию prod). Итоговый URL = <базовый хост сервиса> + url.

Базовые хосты по сервисам и окружениям

Значения из packages/app-kit/src/shared/api/hosts.ts. Ниже приведены stage и prod; дополнительно определены окружения local, contour и preprod (см. примечание). Сервисы, к которым srx-admin реально обращается, отмечены значком «●» в колонке «Используется».

Сервис (service)	Назначение	Используется	stage	prod
iam	IAM: пользователи, отделы, должности, группы, права	●	https://stage-api.sarex.io/iam	https://api.sarex.io/iam
eavV1	EAV: ассеты, атрибуты, права на ассеты, модули	●	https://stage-api.sarex.io/eav	https://api.sarex.io/eav
gateway	Gateway: ресурсы (проекты) и права на ресурсы	●	https://stage-api.sarex.io/gateway	https://api.sarex.io/gateway
sarex	Локальный сервис данных (/api/core, /api/pm, /api/commons)	●	"" (относительные пути)	""
bimv2	BIM v2: модели статусов	●	https://stage-api.sarex.io/bimv2	https://api.sarex.io/bimv2
premises	Сервис помещений	●	https://stage-api.sarex.io/premises	https://api.sarex.io/premises
notifications	Лямбда уведомлений (email)	●	https://stage-api.sarex.io/lambdas/notification	https://api.sarex.io/lambdas/notification
documentations	Сервис документации		https://stage-api.sarex.io/documentations	https://api.sarex.io/documentations
workspaces	Сервис рабочих областей		https://stage-api.sarex.io/workspaces	https://api.sarex.io/workspaces
workflows	Сервис обработки документов		https://stage-api.sarex.io/workflows	https://api.sarex.io/workflows
comparisons	Сервис сравнений		https://stage-api.sarex.io/comparisons	https://api.sarex.io/comparisons
remarks	Сервис замечаний		https://stage-api.sarex.io/remarks	https://api.sarex.io/remarks
projects	Сервис проектов		https://stage-api.sarex.io/projects	https://api.sarex.io/projects
bim	BIM-API		https://stage-api.sarex.io/bim	https://api.sarex.io/bim
sarexApi	Gateway/API Sarex (корень)		https://stage-api.sarex.io	https://api.sarex.io
google	Временное хранилище (GCS)		https://storage.googleapis.com/srx-tmp	https://storage.googleapis.com/srx-tmp
zitadel	IdP (аутентификация)		https://idp.dev.stage.sarex.io	https://login.sarex.io

В окружении local сервисы проксируются на относительные пути (sarex → /sarex-backend, gateway → /sarex-gateway, eavV1 → /sarex-eav-v1, notifications → /sarex-notifications, iam → /iam, premises → /premises и т. д.). Окружение contour использует относительные пути для изолированного контура. Подключаемые удалённые модули (Module Federation) описаны отдельно в services/*/config/endpoints.ts (см. раздел «Удалённые модули»).

Эндпоинты по сервисам

iam — IAM (пользователи, отделы, должности, группы, права)

Ключ	Метод	Путь	Назначение
fetchUsers	GET	/api/admin/v0/users/?{query}	Список пользователей компании (пагинация, поиск, фильтры)
fetchCreateUser	POST	/api/admin/v0/users/	Создать пользователя
fetchUpdateUser	PATCH	/api/admin/v0/users/{id}/	Обновить пользователя
fetchBulkUpdateUsers	PATCH	/api/admin/v0/users/	Массовое обновление пользователей
fetchBulkUpdateUsersActivation	POST	/api/admin/v0/users/activation/	Массовая активация/деактивация пользователей
fetchDepartments	GET	/api/admin/v0/departments/	Список отделов (пагинация, поиск, фильтр по компании)
fetchCreateDepartment	POST	/api/admin/v0/departments/	Создать отдел (CSRF)
fetchUpdateDepartment	PUT	/api/admin/v0/departments/{id}/	Обновить отдел (CSRF)
fetchDeleteDepartment	DELETE	/api/admin/v0/departments/{id}/	Удалить отдел (CSRF)
fetchPositions	GET	/api/admin/v0/positions	Список должностей (пагинация, поиск, фильтр по компании)
fetchCreatePosition	POST	/api/admin/v0/positions/	Создать должность (CSRF)
fetchUpdatePosition	PUT	/api/admin/v0/positions/{id}/	Обновить должность (CSRF)
fetchDeletePosition	DELETE	/api/admin/v0/positions/{id}/	Удалить должность (CSRF)
fetchGroups	POST	/api/admin/v0/groups/search/	Поиск функциональных групп (фильтры, пагинация, сортировка)
createGroup	POST	/api/admin/v0/groups	Создать группу
updateGroup	PATCH	/api/admin/v0/groups/{id}	Обновить группу
deleteGroup	DELETE	/api/admin/v0/groups/{id}	Удалить группу
fetchPermissions	POST	/api/admin/v0/permissions/search/	Поиск прав (фильтры, пагинация, сортировка)
createPermission	POST	/api/admin/v0/permissions	Создать право
deletePermission	DELETE	/api/admin/v0/permissions/{id}	Удалить право

eavV1 — EAV (ассеты, атрибуты, права на ассеты, модули)

Ключ	Метод	Путь	Назначение
fetchGetAssetsV4	GET	/api/v4/assets/	Список ассетов (v4, параметры фильтрации)
fetchGetAssetsV5	GET	/api/v2/assets/	Список ассетов (v5)
fetchCreateBulkAssetsV4	POST	/api/v4/assets/	Массовое создание ассетов (v4)
fetchCreateBulkAssetsV5	POST	/api/v2/assets/	Массовое создание ассетов (v5)
fetchUpdateBulkAssetsV4	PATCH	/api/v4/assets/	Массовое обновление ассетов (v4)
fetchUpdateBulkAssetsV5	PATCH	/api/v2/assets/	Массовое обновление ассетов (v5)
fetchDeleteAssetV4	DELETE	/api/v4/assets/{assetId}/	Удалить ассет (v4)
fetchDeleteAssetV5	DELETE	/api/v2/assets/{assetId}/	Удалить ассет (v5)
fetchCopyRootAsset	POST	/api/v4/assets/{asset_id}/copy/	Копировать корневой ассет
fetchCopyAssets	POST	/api/v2/assets/copy-to-destination-bulk/	Массовое копирование ассетов в назначения
fecthGetAssetPermissions	GET	/api/v4/permissions/?asset_id={id}&service_account_id={id}	Права доступа ассета
fetchPostCreateAssetPermissions	POST	/api/v4/permissions/	Создать права на ассет
fetchPostUpdateAssetPermissions	PATCH	/api/v4/permissions/	Обновить права на ассет
fetchDeleteAssetPermissions	DELETE	/api/v4/permissions/{permissionId}/	Удалить права на ассет
fetchGetAssetPermissionsTree	GET	/api/v4/permissions/relative/?asset_id={id}	Дерево наследуемых прав ассета
fetchAttributes	GET	/api/v1/attribute/	Список атрибутов компании (пагинация, поиск, фильтр по id)
createAttribute	POST	/api/v1/attribute/	Создать атрибут
updateAttribute	PUT	/api/v1/attribute/{id}/	Обновить атрибут
deleteAttribute	DELETE	/api/v1/attribute/{attributeId}/	Удалить атрибут
fetchModules	GET	/api/v1/modules/	Список модулей (CSRF)

gateway — Gateway (ресурсы/проекты, права на ресурсы)

Ключ	Метод	Путь	Назначение
fetchProjects	GET	/api/v2/resources?show_all=true&limit=10000&company_id={id}	Список проектов компании (кешируется)
fetchGetProjectByProjectId	GET	/api/v2/resources/{projectId}	Проект по id (кешируется)
fetchCreateProject	POST	/api/v2/resources	Создать проект/ресурс
fetchUpdateProjectByProjectId	PATCH	/api/v2/resources/{projectId}	Обновить проект
fetchDeleteProjectByProjectId	DELETE	/api/v2/resources/{projectId}	Удалить проект
fetchParentDocumentByResourceId	GET	/api/v1/resources-rpc/parent-document-by-resource-id/{resourceId}	Родительский документ по resource id
fetchResources	GET	/api/v1/resources/?company_id={id}	Список ресурсов компании (кешируется)
fetchCreatePermission	POST	/api/v1/resource-permissions/	Выдать права на ресурсы сервисному аккаунту
fetchResourcesByUsersId	POST	/api/v1/resources/users-with-resources/	Ресурсы по набору пользователей
fetchBulkUpdateUsersPermissions	PATCH	/api/v1/resources/permissions-bulk/	Массовое обновление прав на ресурсы
fetchBulkUpdateUsersCompanyResourcesPermission	POST	/api/v1/company-resource-permissions/bulk/	Массовая выдача прав на ресурсы компании

sarex — Локальный сервис данных

Ключ	Метод	Путь	Назначение
fetchCoordinates	GET	/api/commons/cs/	Справочник систем координат (кешируется)
fetchLinksToPlanningByProjectId	GET	/api/pm/msp/projects/?resource_id={projectId}&strict=true	Связи проекта с планированием (кешируется)
fetchBulkUpdateUserNotifications	PATCH	/api/core/users/bulk/notifications/	Массовое переключение уведомлений пользователей
getMrpas	POST	/api/core/mrpa/list/	Список МРПА (пагинация, фильтры, агрегации)
createMrpa	POST	/api/core/mrpa/	Загрузить МРПА (multipart/form-data)
deleteMrpa	DELETE	/api/core/mrpa/{id}/	Удалить МРПА

bimv2 — BIM v2 (модели статусов)

Ключ	Метод	Путь	Назначение
fetchCreateCompanyStatusModel	POST	/api/v1/companies/{companyId}/status_model	Создать модель статусов компании
fetchGetCompanyStatusModels	GET	/api/v1/companies/{companyId}/status_model	Модели статусов компании
fetchGetBIMStatusModels	GET	/api/v1/bims/{bimId}/status_models	Модели статусов BIM
fetchUpdateBIMStatusModel	POST	/api/v1/bims/{bimId}/status_model	Обновить модель статусов BIM
fetchGetBIMStatuses	POST	/api/v1/bims/{bimId}/statuses?{search}	Статусы BIM (с фильтром)

premises — Сервис помещений

Ключ	Метод	Путь	Назначение
getPremises	POST	/api/v1/premises/filter/	Помещения по локациям и ресурсу

notifications — Лямбда уведомлений

Ключ	Метод	Путь	Назначение
fetchSendEmail	POST	/	Отправить email-уведомление (from hello@sarex.io)

Удалённые модули (Module Federation)

Помимо HTTP-API, srx-admin подгружает удалённые микрофронтенды через remoteEntry.js. Адреса заданы в services/admin/config/endpoints.ts и services/assets/config/endpoints.ts (объект moduleEndpoints).

Модуль	stage / local	prod	contour
documentations	https://stage-modules.sarex.io/documentations/static/module/remoteEntry.js	https://modules.sarex.io/documentations/static/module/remoteEntry.js	/documentations/static/module/remoteEntry.js
assets	https://stage-modules.sarex.io/control-interface/modules/assets/remoteEntry.js	https://modules.sarex.io/control-interface/modules/assets/remoteEntry.js	/control-interface/modules/assets/remoteEntry.js

В preprod используются хосты вида https://modules.preprod.sarex.io/....

Обработка ошибок и авторизация

Запросы выполняются через httpService (@sarex-team/sdk-js поверх axios). Для части эндпоинтов (iam: отделы, должности, создание пользователей/групп; eavV1: модули) передаётся флаг isCSRF: true — добавляется CSRF-токен. Ошибки обрабатываются на уровне SDK и сторов приложения; человекочитаемые сообщения задаются в сторах (errorMessage), например «Произошла ошибка при запросе пользователей» / «мест работы» / «ролей» / «функциональных групп».