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

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

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

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

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

Запрос выполняется единой функцией `fetch(endpoint, params)` (`module/networking/endpoints.ts`): итоговый URL = `resolveHost(service)` + `path(params)`. Базовый хост подставляется `resolveHost(service)` из `module/networking/hosts.ts`. Ошибки маппируются в человекочитаемые сообщения в `module/networking/errors.ts`.

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

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

Значения хостов «зашиваются» в бандл через `webpack.DefinePlugin` (`webpack.config.js`): плагин получает объект `hosts` из `networking.config.js`, где функция `extractHosts` по `process.env.BUILD_ENV` выбирает набор хостов и превращает его в define-константы вида `__<service>_host`. Затем `module/networking/hosts.ts` читает эти константы (`__workspaces_host`, `__google_host`, `__bim_host`, `__sarex_host`, `__sarexS3_host`).

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

Значения `BUILD_ENV` по стадиям CI (`.gitlab-ci.yml`): `preprod`, `stage`, `prod`.

> Замечание: в `build.config.js` определён режим сборки для `local`, но в `networking.config.js` набор хостов для `local` **не задан** — при `BUILD_ENV=local` `extractHosts` бросит `Cannot get hosts for BUILD_ENV=local`. Также в `networking.config.js` для `prod`/`preprod` дополнительно объявлены хосты `documentations` и `workflows`, но `module/networking/hosts.ts` их не читает и в эндпоинтах они не используются.

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

Значения из `networking.config.js`. Итоговый URL = `<базовый хост сервиса>` + `path` эндпоинта. Сервис `absolute` всегда имеет пустой хост (`""`) — путь используется как есть (относительный/абсолютный URL).

| Сервис (`service`) | Назначение | `stage` | `preprod` | `prod` |
| --- | --- | --- | --- | --- |
| `workspaces` | Сервис рабочих областей | `https://stage-api.sarex.io/workspaces/` | `https://api.preprod.sarex.io/workspaces/` | `https://api.sarex.io/workspaces/` |
| `bim` | BIM-API | `https://stage-api.sarex.io/bim/` | `https://api.preprod.sarex.io/bim/` | `https://api.sarex.io/bim/` |
| `sarex` | Локальный сервис данных (ЛК) | `https://stage.sarex.io/` | `https://lk.preprod.sarex.io/` | `https://lk.sarex.io/` |
| `sarexS3` | S3-хранилище ЛК | `https://lk.sarex.io/s3/` | `https://lk.preprod.sarex.io/s3/` | `https://lk.sarex.io/s3/` |
| `google` | Временное хранилище (GCS) | `https://storage.googleapis.com/srx-tmp/` | `https://storage.googleapis.com/srx-tmp/` | `https://storage.googleapis.com/srx-tmp/` |
| `absolute` | Пустой хост (относительные/полные URL) | `""` | `""` | `""` |

> Сервисы `google`, `sarex`, `sarexS3` определены в конфиге хостов, но в текущем реестре `endpoints.ts` эндпоинтов к ним нет — фактически используются `workspaces`, `bim` и `absolute`.

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

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

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getWorkspaces` | GET | да | `api/v1/workspaces/{uuid}` | Рабочая область по uuid |
| `getWorkspaceStates` | GET | да | `api/v1/workspaces/{uuid}/states` | Список состояний рабочей области |
| `getWorkspaceState` | GET | да | `api/v1/states/{uuid}` | Состояние по uuid |
| `saveWorkspaceState` | POST | да | `api/v1/workspaces/{uuid}/states` | Сохранить состояние (тело — объект `state`) |
| `getCompanyApps` | GET | да | `api/v1/company/{companyId}/apps` | Приложения компании |
| `createAppInstance` | POST | да | `api/v1/workspaces/{workspaceId}/apps/{appId}/instances` | Создать инстанс приложения в рабочей области |

### `bim` — BIM-API

| Ключ | Метод | Auth | Путь | Назначение |
| --- | --- | --- | --- | --- |
| `getBimElements` | GET | да | `api/v1/bims/{id}/sarexid/{elementSarexIds}` | Элементы BIM по sarex-id |
| `getElements` | GET | да | `{url}` | Запрос по произвольному URL (пагинация/выборка элементов) |
| `postElementsByIds` | POST | да | `api/v1/bims/{id}/sarexid` | Элементы по набору sarex-id (тело `sarex_ids`) |
| `postElementsStatus` | POST | да | `api/v1/changes` | Обновить статус элементов (тело `element_ids`, `current_state.abap_status`) |

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

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

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

Ошибки маппируются в `module/networking/errors.ts`. Для каждого сервиса задано человекочитаемое имя (`serviceToName`): `workspaces` → «Сервис рабочих областей», `bim` → «Сервис BIM», `google` → «Сервис хранения данных», `sarex`/`sarexS3` → «Локальный сервис данных», `absolute` → «Сервис».

Коды ответов (`httpCodeToError`): `400` — «некорректный формат запроса», `404` — «ресурс не найден», `500` — «ошибка сервера». Для прочих кодов берётся ближайший: `4xx` → сообщение `400`, остальные → `500`. Итоговый текст формируется как «`<Имя сервиса>` вернул ошибку: `<сообщение>`».