78 lines
6.0 KiB
Markdown
78 lines
6.0 KiB
Markdown
# Эндпоинты, с которыми взаимодействует comparisons-frontend
|
||
|
||
Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `comparisons-frontend`).
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
Все запросы описаны декларативно в реестре `module/networking/endpoints.ts` (объект `endpoints`). Каждый эндпоинт задаётся структурой `Endpoint`:
|
||
|
||
- `service` — логическое имя сервиса (`EServices`, см. таблицу хостов ниже);
|
||
- `method` — HTTP-метод (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`);
|
||
- `path(args)` — функция, возвращающая путь запроса (с подстановкой параметров/query);
|
||
- `body(args)` — опционально, формирование тела запроса.
|
||
|
||
Запрос выполняется единой функцией `fetch(endpoint, params)`, которая через `httpService` (`module/httpService/httpService.ts`, поверх `@sarex-team/sdk-js` + `axios`) отправляет запрос на базовый хост сервиса. Базовый хост подставляется `resolveHost(service)` из `module/httpService/hosts.ts` в зависимости от `buildEnv` (`__BUILD_ENV__`, задаётся сборкой; по умолчанию `prod`). Результат возвращается как `{ resp }` либо `{ errMessage }`.
|
||
|
||
## Базовые хосты по сервисам и окружениям
|
||
|
||
Значения из `module/httpService/hosts.ts` (`allHosts`). Итоговый URL = `<базовый хост сервиса>` + `path` эндпоинта. Хосты берутся из `@sarex-team/sdk-js` (`resolveHost`).
|
||
|
||
| Сервис (`EServices`) | Назначение | `stage` | `prod` |
|
||
| --- | --- | --- | --- |
|
||
| `comparisons` | Сервис сравнений (comparisons-backend) | `https://stage-api.sarex.io/comparisons` | `https://api.sarex.io/comparisons` |
|
||
| `documentations` | Сервис документации (диски, документы) | `https://stage-api.sarex.io/documentations` | `https://api.sarex.io/documentations` |
|
||
| `sarexApi` | Gateway/API Sarex (`/gateway`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
|
||
| `sarex` | Локальный сервис данных (`/api/core`) | `""` (относительные пути) | `""` |
|
||
| `workflows` | Сервис обработки документов | `https://stage-api.sarex.io/workflows` | `https://api.sarex.io/workflows` |
|
||
| `bimv2` | BIM API v2 | `https://stage-api.sarex.io/bimv2` | `https://api.sarex.io/bimv2` |
|
||
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |
|
||
|
||
> Также определены окружения `local`, `preprod` и `contour`. В `local` сервисы проксируются на `https://localhost:9000/sarex-backend` и `https://localhost:9000/sarex-api-backend/*`. В `contour` используются относительные пути (`/comparisons`, `/documentations`, `/bimv2`, `/workflows`) для изолированного контура. В `preprod` — `https://api.preprod.sarex.io/*`.
|
||
|
||
## Эндпоинты по сервисам
|
||
|
||
### `comparisons` — Сервис сравнений
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getTypes` | GET | `/api/v1/types` | Справочник типов сравнений и их параметров |
|
||
| `createComparison` | POST | `/api/v1/comparisons` | Создать сравнение (тело — параметры сравнения) |
|
||
| `getComparisons` | GET | `/api/v1/comparisons?workspace_id={workspaceId}` | Список сравнений рабочей области |
|
||
| `deleteComparison` | DELETE | `/api/v1/comparisons/{id}` | Удалить сравнение |
|
||
|
||
### `documentations` — Сервис документации
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getDisks` | GET | `/api/v1/disks` | Список дисков |
|
||
| `getDocuments` | GET | `/api/v1/disks/{id}/documents` | Документы диска |
|
||
| `getNearestNameTemplate` | GET | `/api/v1/documents/{documentId}/name_template` | Ближайший шаблон имени документа |
|
||
|
||
### `sarexApi` — Gateway/API Sarex
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getDocumentsV2` | GET | `/gateway/api/v1/disks/{id}/documents?parent_id=&child_id=&search=&{attributeValue}` | Документы диска с фильтрами (родитель/ребёнок/поиск/атрибуты) |
|
||
|
||
### `sarex` — Локальный сервис данных
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getUsersByIDs` | GET | `/api/core/users/?id={ids}` | Пользователи по списку id |
|
||
|
||
### `workflows` — Сервис обработки документов
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getWorkflow` | GET | `/api/v1/workflows/{workflowId}` | Workflow по id |
|
||
|
||
### `bimv2` — BIM API v2
|
||
|
||
| Ключ | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `getBim` | GET | `/api/v1/bims/{bimId}` | BIM-модель по id |
|
||
|
||
## Обработка ошибок
|
||
|
||
`fetch` перехватывает исключения запроса и возвращает `{ errMessage }` (строка ошибки) вместо данных; успешный ответ приходит как `{ resp: <data> }`. Явного маппинга кодов ответа в реестре нет — обработка и отображение ошибок выполняются на уровне репозиториев/вью-моделей, использующих `fetch`.
|