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