163 lines
16 KiB
Markdown
163 lines
16 KiB
Markdown
# Эндпоинты, с которыми взаимодействует 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`), например «Произошла ошибка при запросе пользователей» / «мест работы» / «ролей» / «функциональных групп».
|