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