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

Эндпоинты, с которыми взаимодействует 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.