iac/apps/workspaces/ENDPOINTS-workspaces-frontend.md

Эндпоинты, с которыми взаимодействует 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. Итоговый текст формируется как «<Имя сервиса> вернул ошибку: <сообщение>».