# Эндпоинты, с которыми взаимодействует workspace-v2-frontend

Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается микрофронтенд `workspace-v2-frontend`, а также способ конфигурирования базовых хостов на этапе сборки.

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

Все запросы описаны декларативно в реестре `module/networking/endpoints.ts` (объект `endpoints`). Каждый эндпоинт задаётся структурой `Endpoint`:

- `service` — логическое имя сервиса (enum `EServices` из `module/httpService/hosts.ts`);
- `method` — HTTP-метод (`EMethod`: `GET`/`POST`/`PUT`/`PATCH`/`DELETE`);
- `auth` — требуется ли авторизация;
- `path(args)` — функция, возвращающая путь запроса (с подстановкой параметров/query);
- `body(args)` — опционально, формирование тела запроса.

Запрос выполняется единой функцией `fetch(endpoint, params)` (`module/networking/endpoints.ts`), которая вызывает `httpService.getRequest(...)` (`module/httpService/httpService.tsx`, поверх `@sarex-team/sdk-js`). Базовый хост подставляется `resolveHost(service)` из `module/httpService/hosts.ts` — обёрткой над `resolveHost` из SDK, которая по `buildEnv` выбирает набор хостов из `allHosts`. Подключаемые удалённые модули (module federation) описаны отдельно в `module/config/module-hosts.ts`.

## Конфигурирование (базовые хосты, `BUILD_ENV`)

Фронтенд конфигурируется **только на этапе сборки** — переменной окружения `BUILD_ENV`. Рантайм-переменных окружения у собранного бандла нет.

Значение подставляется в бандл через `webpack.DefinePlugin` как константа `__BUILD_ENV__` (`webpack/config.build.js`, `config.serve.js`, `config.start.js`). Модуль `module/httpService/buildEnv.ts` читает её: `buildEnv = __BUILD_ENV__ || EBuildEnv.prod` — **по умолчанию `prod`**. Допустимые значения проверяются в `webpack/env.js` (`BUILD_ENV = process.env.BUILD_ENV || "prod"`).

| Переменная | Где задаётся | Назначение |
| --- | --- | --- |
| `BUILD_ENV` | build-arg в `.gitlab-ci.yml` → `ARG BUILD_ENV` в `Dockerfile` → `npm run build` | Окружение сборки; определяет набор базовых хостов. Значение по умолчанию — `prod` |
| `NPM_NEXUS_TOKEN` | build-arg в `.gitlab-ci.yml` → `ARG NPM_NEXUS_TOKEN` в `Dockerfile` (`.npmrc`) | Токен доступа к приватному npm-реестру `nexus.infra.sarex.io` при установке зависимостей |

Допустимые значения `BUILD_ENV` (`EBuildEnv` в `module/httpService/buildEnv.ts` / `webpack/env.js`): `local`, `stage`, `prod`, `preprod`, `contour`, `severstal`, `uralchem`. В CI (`.gitlab-ci.yml`) собираются стадии `preprod`, `stage`, `prod`. Локальные npm-скрипты: `start` → `local`, `serve` → `stage`, `storybook` → `local`.

> Замечание: окружения `severstal` и `uralchem` в коде помечены комментариями «уточнить в будущем используется ли».

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

Значения из `module/httpService/hosts.ts` (`allHosts`). Итоговый URL = `<базовый хост сервиса>` + `path` эндпоинта. Ниже приведены основные окружения `stage` и `prod`; полный набор (`local`, `preprod`, `contour`, `severstal`, `uralchem`) — в `allHosts`.

| Сервис (`EServices`) | Назначение | `stage` | `prod` |
| --- | --- | --- | --- |
| `workspaces` | Сервис рабочих областей | `https://stage-api.sarex.io/workspaces` | `https://api.sarex.io/workspaces` |
| `documentations` | Сервис документации | `https://stage-api.sarex.io/documentations` | `https://api.sarex.io/documentations` |
| `workflows` | Сервис обработки документов | `https://stage-api.sarex.io/workflows` | `https://api.sarex.io/workflows` |
| `sarexApi` | Gateway/API Sarex (`/gateway`, `/files`, `/issues`, `/notes`, `/mapper`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
| `gateway` | Gateway Sarex | `https://stage-api.sarex.io/gateway` | `https://api.sarex.io/gateway` |
| `sarex` | Локальный сервис данных (ядро/ЛК) | `/` | `/` |
| `bim` | BIM-API (v1) | `https://stage-api.sarex.io/bim` | `https://api.sarex.io/bim` |
| `bimv2` | BIM-API (v2) | `https://stage-api.sarex.io/bimv2` | `https://api.sarex.io/bimv2` |
| `comparisons` | Сервис сравнений | `https://stage-api.sarex.io/comparisons` | `https://api.sarex.io/comparisons` |
| `checklists` | Сервис чек-листов | `https://stage-api.sarex.io/checklists` | `https://api.sarex.io/checklists` |
| `remarks` | Сервис замечаний | `https://stage-api.sarex.io/remarks` | `https://api.sarex.io/remarks` |
| `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` |
| `sarexAgents` | Сервис агентов | `https://sarex-agents.dev.stage.sarex.io` | `https://agents.sarex.tech` |
| `eavV4` | EAV API v4 | `https://stage-api.sarex.io/eav/api/v4` | `https://api.sarex.io/eav/api/v4` |
| `premises` | Сервис помещений | `https://stage-api.sarex.io/premises/api/v1` | `https://api.sarex.io/premises/api/v1` |
| `absolute` | Пустой хост (относительные/полные URL) | `""` | `""` |

> В `local` сервис `sarex` проксируется на `https://localhost:9000/sarex-backend`, остальные — на `https://localhost:9000/sarex-api-backend/...`. В `contour` используются относительные пути (`/workspaces`, `/documentations` и т.д.). Сервисы `checklists`, `remarks` (помечен в коде как «не используется»), `google`, `zitadel`, `sarexAgents`, `eavV4`, `premises` объявлены в хостах, но в текущем реестре `endpoints.ts` эндпоинтов к ним нет.

## Подключаемые модули (module federation)

Хосты remoteEntry для микрофронтендов (`module/config/module-hosts.ts`, выбор по `buildEnv`):

| Модуль | `stage` | `prod` |
| --- | --- | --- |
| `documentations` | `https://stage-modules.sarex.io/documentations/static/module/remoteEntry.js` | `https://modules.sarex.io/documentations/static/module/remoteEntry.js` |
| `assistant` | `https://stage-modules.sarex.io/assistant/static/module/remoteEntry.js` | `https://modules.sarex.io/assistant/static/module/remoteEntry.js` |

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

### `workspaces` — Сервис рабочих областей

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getWorkspaceStates` | GET | да | `/api/v1/workspaces/{uuid}/states` | Список состояний рабочей области |
| `getWorkspaceStatesActual` | GET | да | `/api/v1/workspaces/{uuid}?version={currentStateIdState}` | Актуальное состояние по версии |
| `saveWorkspaceState` | POST | да | `/api/v1/workspaces/{uuid}/states` | Сохранить состояние (тело — объект `state`) |
| `editWorkspaceState` | PATCH | да | `/api/v1/states/{uuid}` | Изменить состояние (`name`/`data`) |
| `putDefaultState` | PATCH | да | `/api/v1/states/{uuid}` | Пометить состояние как дефолтное (`is_default`) |
| `deleteWorkspaceState` | DELETE | да | `/api/v1/states/{uuid}` | Удалить состояние |
| `getCompanyApps` | GET | да | `/api/v1/company/{companyId}/apps` | Приложения компании |
| `createAppInstance` | POST | да | `/api/v1/workspaces/{workspaceId}/apps/{appId}/instances` | Создать инстанс приложения |
| `postDocument` | POST | да | `/api/v1/workspaces/{uuid}/documents` | Привязать документ к рабочей области (`document_id`) |
| `deleteDocument` | DELETE | да | `/api/v1/workspaces/{workspaceId}/documents/{documentId}` | Отвязать документ от рабочей области |

### `documentations` — Сервис документации

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getDocumet` | GET | да | `/api/v1/documents/{docId}?extend=bundles` | Документ с бандлами |
| `deleteWorkspace` | DELETE | да | `/api/v1/documents/{id}` | Удалить документ |
| `getCompanyIdByDocId` | GET | да | `/api/v1/documents/{docId}/company` | Компания документа |
| `getDocumentTypes` | GET | да | `/api/v1/documents/types` | Типы документов |
| `getDocumentPermissions` | GET | да | `/api/v1/documents/{id}/permissions` | Права доступа документа |
| `getDisks` | GET | да | `/api/v1/disks` | Список дисков |
| `getDocumentsByDisk` | GET | да | `/api/v1/disks/{diskId}/documents` | Документы диска |
| `fetchReviewDocuments` | POST | да | `/api/v1/disks/{diskId}/documents` | Документы по набору id (`document_ids`) |
| `getFile` | GET | да | `/api/v1/bundles/{bundleId}/pdf/download` | Скачать PDF бандла |
| `downloadFile` | GET | да | `/api/v1/bundles/{bundleId}/{key}/download` | Скачать файл бандла |
| `downloadAllFiles` | GET | да | `/api/v1/bundles/{bundleId}/download` | Скачать все файлы бандла |
| `updateBundle` | PATCH | да | `/api/v1/bundles/{bundleId}` | Обновить бандл (`attributes`) |
| `restartWorkflow` | POST | да | `/api/v1/bundles/{bundleId}/restart` | Перезапустить workflow бандла |

### `sarexApi` — Gateway/API Sarex

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getDocuments` | GET | да | `/gateway/api/v1/disks/{diskId}/documents?parent_id=&child_id=&search=` | Документы диска (фильтры) |
| `loadFile` | GET | да | `/files/api/v1/bundles/{bundleId}/{key}` | Файл бандла |
| `getPagePdf` | GET | да | `{url}` | PDF-страница по произвольному URL |
| `getRemarksByDocument` | POST | да | `/issues/api/issues/filter/?limit=&offset=` | Замечания документа (фильтр) |
| `getRemark` | GET | да | `/issues/api/issues/{uuid}/` | Замечание по uuid |
| `getCustomStatuses` | GET | да | `/issues/api/companies/{companyId}/status-model/v2/?issue_type_id={issueType}` | Модель статусов замечаний компании |
| `getIssueTypes` | GET | да | `/issues/api/issue-types/?company_id={companyId}` | Типы замечаний компании |
| `getNotes` | GET | да | `/mapper/api/v1/notes/workspace/workspace/{instanceId}/?{query}` | Заметки рабочей области |
| `createLinkNote` | POST | да | `/notes/api/v1/links/` | Привязать ссылку к заметке (`link_id`, `note_id`) |
| `updateLinkNote` | POST | да | `/notes/api/v1/links/` | Обновить привязку ссылки к заметке |

### `sarex` — Локальный сервис данных (ядро/PM)

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getUsers` | GET | да | `/api/core/users` | Список пользователей |
| `getUser` | GET | да | `/api/core/users/{id}/` | Пользователь по id |
| `getUsersByIDs` | GET | да | `/api/core/users/?id={ids}` | Пользователи по набору id |
| `getTarget` | GET | да | `/api/core/targets/{targetId}/` | Таргет по id |
| `getCoordinates` | GET | да | `/api/commons/cs/` | Системы координат |
| `createLink` | POST | да | `/api/core/target-links/` | Создать ссылку таргета |
| `updateLink` | PUT | да | `/api/core/target-links/{id}/` | Обновить ссылку таргета |
| `deleteLink` | DELETE | да | `/api/core/target-links/{id}/` | Удалить ссылку таргета |
| `getProject` | GET | да | `/api/pm/msp/projects/?bundle_id={bundleID}&schema=tiny` | Проект по бандлу |
| `getProjectStates` | GET | да | `/api/pm/msp/projects/{projectID}/states/` | Состояния проекта |
| `getResources` | GET | да | `/api/pm/msp/resources/?parent=&type=&projects=&limit=&offset=` | Список ресурсов |
| `getResourceById` | GET | да | `/api/pm/msp/resources/{id}/` | Ресурс по id |
| `getInstancesResources` | GET | да | `/api/pm/msp/resources/?{query}&model={model}` | Ресурсы по инстансам/модели |
| `getResourcesTasks` | GET | да | `/api/pm/msp/resources-tasks/?{query}` | Задачи ресурсов |
| `getResourcesByElementAndDocumentId` | GET | да | `/api/pm/msp/resources/?limit=50000&offset=0&{instance}&model=&{path}&{projects}&documents={document}` | Ресурсы по элементу и документу |
| `createResource` | POST | да | `/api/pm/msp/resources/` | Создать ресурс |
| `updateResource` | PATCH | да | `/api/pm/msp/resources/{id}/` | Обновить ресурс |
| `deleteResource` | DELETE | да | `/api/pm/msp/resources/{id}/` | Удалить ресурс |
| `bulkCreate` | POST | да | `/api/pm/msp/resources/bulk_create/` | Массовое создание ресурсов |
| `createResourceConnection` | POST | да | `/api/pm/msp/resources/{resourceId}/bind_elements/` | Привязать элементы к ресурсу |
| `getResourceConnection` | GET | да | `/api/pm/msp/resources-elements/?resources=&instances=&path=` | Связи ресурс–элемент |
| `deleteResourceConnection` | DELETE | да | `/api/pm/msp/resources-elements/{connectionId}/` | Удалить связь ресурс–элемент |

### `gateway` — Gateway Sarex

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getThumbnails` | POST | да | `/api/v1/disks/{diskId}/thumbnails` | Превью документов (`document_ids`) |
| `getWorkspaceState` | GET | да | `/api/v1/workspace/states/{uuid}` | Состояние рабочей области |
| `getScreenShot` | GET | да | `/api/v1/workspace/{wsId}` | Скриншот/данные рабочей области |
| `getRelatedDocuments` | GET | да | `/api/v1/documents/related_documents?scope_id={bimId}&entity_id={bimElementId}` | Связанные документы элемента |
| `bindRelatedDocuments` | POST | да | `/api/v1/documents/related_documents` | Привязать связанные документы |
| `unbindRelatedDocuments` | POST | да | `/api/v1/documents/related_documents/bulk_delete` | Отвязать связанные документы (по `ids`) |

### `workflows` — Сервис обработки документов

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getWorkflow` | GET | да | `/api/v1/workflows/{id}` | Workflow по id |

### `bim` — BIM-API (v1)

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getElementsByIds` | GET | да | `/api/v1/bims/{id}/sarexid/{elementSarexIds}` | Элементы по sarex-id |
| `getElements` | GET | да | `{url}` | Элементы по произвольному URL |
| `postElementsStatus` | POST | да | `/api/v1/changes` | Обновить статус элементов |

### `bimv2` — BIM-API (v2)

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getBimElementById` | GET | да | `/api/v1/bims/{bimId}` | BIM-модель по id |
| `getElementsByIdsV2` | POST | да | `/api/v1/bims/{id}/sarexid?with_hierarchy={isHierarchy}` | Элементы по sarex-id (`sarex_ids`) |
| `getElementsV2` | GET | да | `{url}` | Элементы по произвольному URL |
| `getElementsAsCsv` | POST | да | `/api/v1/bims/{bundleBimId}/csv_properties` | Выгрузка свойств элементов в CSV |
| `getElementPropertiesById` | GET | да | `/api/v1/bims/{bimId}/elements/{elementSarexId}/properties` | Свойства элемента |
| `getElementStatusesById` | GET | да | `/api/v1/bims/{bimId}/status_models` | Модели статусов |
| `getElementsFilterFields` | GET | да | `/api/v1/bims/{bimId}/filter_fields` | Поля фильтрации элементов |
| `postFilterElements` | POST | да | `/api/v1/bims/{bimId}/elements` | Фильтрация элементов (`filters`) |
| `postElementsStatusV2` | POST | да | `/api/v1/changes` | Обновить статус элементов |
| `updateElementsStatuses` | POST | да | `/api/v1/bims/{bimId}/changes?with_hierarchy={isHierarchy}` | Обновить статусы (`new_status_type/value`) |
| `fetchChangeLogs` | GET | да | `/api/v1/bims/{bimId}/changes?sarex_ids=&status_type=&offset=&limit=` | Журнал изменений статусов |
| `fetchElementsStatuses` | GET | да | `/api/v1/bims/{bimId}/statuses` | Статусы элементов |
| `fetchElementsStatusColor` | GET | да | `/api/v1/bims/{bimId}/statuses_color` | Цвета статусов |

### `comparisons` — Сервис сравнений

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getComparisonElements` | GET | да | `/api/v1/elements?{params}` | Элементы сравнения |
| `getFilterFields` | GET | да | `/api/v1/filter_fields?doc_id={id}` | Поля фильтрации |
| `getTolerance` | GET | да | `/api/v1/tolerance?bundle_id={id}` | Допуски по бандлу |
| `updateElementField` | PATCH | да | `/api/v1/elements/{elementId}` | Обновить поле элемента |

### `absolute` — Пустой хост (произвольные URL)

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `cloudJS` | GET | нет | `{path}` | Загрузка ресурса по пути без авторизации |
| `cloudJSWithAuth` | GET | да | `{path}` | То же, с авторизацией |
| `getLoadElements` | GET | да | `{path}` | Загрузка элементов по произвольному пути |

## Обработка ошибок

Запросы проходят через `fetch` (`module/networking/endpoints.ts`): при ошибке она логируется в консоль (`console.error`) и возвращается объект ошибки вызывающему коду. Централизованного маппинга кодов ответов в человекочитаемые сообщения (как в v1-фронтенде) в реестре нет — обработка ошибок выполняется на уровне вызывающих модулей/`httpService`.
