# Эндпоинты, с которыми взаимодействует projects-frontend

Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `projects-frontend`), а также удалённые модули, которые он подключает и экспортирует через Module Federation.

## Как устроено взаимодействие

Запросы описаны в слое `src/shared/api`. Функции запросов сгруппированы по доменам в каталоге `src/shared/api/fetch/*.api.ts` и реэкспортируются из `src/shared/api/index.ts` (`targetsApi`, `resourcesApi`, `projectsApi`, `userApi`, `companyApi`).

Каждый запрос выполняется через единый `httpService` (`src/shared/api/http-service.ts`), созданный фабрикой `createHttpService` из `@sarex-team/sdk-js` (поверх `axios`). У сервиса есть методы `getRequest` / `postRequest` / `putRequest` / `deleteRequest`, принимающие объект с полями:

- `service` — логическое имя сервиса (см. таблицу хостов ниже);
- `url` — путь запроса (относительно базового хоста сервиса);
- `data` — тело запроса (для POST/PUT);
- `axiosConfig.params` — query-параметры;
- `isCSRF` — признак необходимости передать CSRF-токен (для сервиса `sarex`);
- `cache`, `queryOptions`, `queryKey` — опции кеширования и ключи кеша.

Базовый хост подставляется по `service` из карты хостов `src/shared/api/hosts.ts` в зависимости от окружения сборки. Окружение задаётся значением `__ENDPOINT__`, которое подставляется на этапе сборки Webpack (`DefinePlugin`) из переменной `BUILD_ENV` и по умолчанию равно `prod` (`const endpoint = (__ENDPOINT__ as TypeEnvironment) || "prod"`).

## Базовые хосты по сервисам и окружениям

Значения из `src/shared/api/hosts.ts`. Итоговый URL = `<базовый хост сервиса>` + `url` эндпоинта.

| Сервис (`service`) | Назначение | `local` | `stage` | `prod` |
| --- | --- | --- | --- | --- |
| `sarex` | Основной backend (core, pm) | `/sarex-backend` (прокси dev-сервера → `https://stage.sarex.io`) | `/` (относительные пути, тот же origin) | `/` |
| `gateway` | Gateway/API Sarex | `/sarex-gateway` (прокси → `https://stage-api.sarex.io/gateway`) | `https://stage-api.sarex.io/gateway` | `https://api.sarex.io/gateway` |
| `documentations` | Сервис документации | `/sarex-documentations` (прокси → `https://stage-api.sarex.io/documentations`) | `https://stage-api.sarex.io/documentations` | `https://api.sarex.io/documentations` |
| `sarexApi` | API Sarex (корень) | `/sarex-api` (прокси → `https://stage-api.sarex.io`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
| `workspaces` | Сервис рабочих областей | `""` | `https://stage-api.sarex.io/workspaces` | `https://api.sarex.io/workspaces` |
| `workflows` | Сервис обработки документов | `""` | `https://stage-api.sarex.io/workflows` | `https://api.sarex.io/workflows` |
| `comparisons` | Сервис сравнений | `""` | `https://stage-api.sarex.io/comparisons` | `https://api.sarex.io/comparisons` |
| `remarks` | Сервис замечаний | `""` | `https://stage-api.sarex.io/remarks` | `https://api.sarex.io/remarks` |
| `projects` | Сервис проектов | `""` | `https://stage-api.sarex.io/projects` | `https://api.sarex.io/projects` |
| `eavV1` | EAV (атрибуты) | — | `https://stage-api.sarex.io/eav` | `https://api.sarex.io/eav` |
| `notifications` | Сервис уведомлений (lambdas) | — | `https://stage-api.sarex.io/lambdas/notification` | `https://api.sarex.io/lambdas/notification` |
| `bim` / `bimv2` | BIM-API | `""` | `https://stage-api.sarex.io/bim` / `/bimv2` | `https://api.sarex.io/bim` / `/bimv2` |
| `google` | Временное хранилище (GCS) | `""` | `https://storage.googleapis.com/srx-tmp` | `https://storage.googleapis.com/srx-tmp` |
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |

> Также определено окружение `preprod` (`https://api.preprod.sarex.io/*`, `zitadel` → `https://login.preprod.sarex.io`). В `local` часть сервисов проксируется dev-сервером Webpack (`configWebpack/buildDevServer.ts`): `/sarex-backend`, `/sarex-gateway`, `/sarex-documentations`, `/sarex-api`. Остальные сервисы в `local` заданы пустой строкой (относительные пути). Окружение `contour` присутствует в конфигурации сборки (`build.config.ts`), но в `hosts.ts` для него карта хостов не задана.

## Эндпоинты по сервисам

Реально вызываются эндпоинты двух сервисов — `sarex` и `gateway`.

### `sarex` — Основной backend (core, pm)

Все запросы к `sarex` выполняются с `isCSRF: true`.

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `fetchTargetLinks` | GET | `/api/core/target-links/` | Список ссылок таргета (кешируется, `stateTime: 20`) |
| `fetchCreateTargetLink` | POST | `/api/core/target-links/` | Создать ссылку (`name`, `link`, `target`, `type`) |
| `fetchUpdateTargetLink` | PUT | `/api/core/target-links/{id}/` | Обновить ссылку |
| `fetchDeleteTargetLink` | DELETE | `/api/core/target-links/{id}/` | Удалить ссылку |
| `fetchMilestonesByProjectId` | GET | `/api/pm/msp/projects/{projectId}/key_milestones/` | Ключевые вехи проекта |
| `fetchUsersByCompanyId` | GET | `/api/core/users/?companies={companyId}&limit=10000&id={usersIds}` | Пользователи компании по списку id |
| `fetchCompanyById` | GET | `/api/core/companies/{companyId}/` | Компания по id (кешируется) |

### `gateway` — Gateway/API Sarex

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `fetchResources` | GET | `/api/v1/resources?company_id={companyId}` | Список ресурсов компании (кешируется, `stateTime: 20`) |
| `fetchProjectsByCompanyId` | GET | `/api/v2/resources?company_id={companyId}&limit=10000` | Проекты компании (ресурсы v2, кешируется) |

## Удалённые модули (Module Federation)

Помимо HTTP-запросов, модуль взаимодействует с другими микрофронтендами через Webpack Module Federation.

### Подключаемый удалённый модуль

`src/widgets/remote-timeline` динамически загружает удалённый модуль `srx_pm`, экспонированный модуль `./Timeline` (`src/widgets/remote-timeline/ui/timelineProxy.tsx`, загрузка через `src/widgets/remote-timeline/lib/loader.ts`).

| Окружение | URL `remoteEntry.js` |
| --- | --- |
| `stage` | `https://stage-modules.sarex.io/pm/module/remoteEntry.js` |
| `local` | `https://stage-modules.sarex.io/pm/module/remoteEntry.js` |
| `prod` | `https://modules.sarex.io/pm/module/remoteEntry.js` |
| `preprod` | `https://modules.sarex.io/pm/module/remoteEntry.js` |
| `contour` | `""` (не задан) |

### Экспортируемый модуль

Сам `projects-frontend` при сборке (для всех окружений, кроме `local`) публикует себя как удалённый модуль `srx_projects` (`webpack.config.ts`, `ModuleFederationPlugin`):

- `filename`: `module/remoteEntry.js`;
- `exposes`: `./ProjectsPage` → `./src/app/App.tsx`;
- `shared` (singleton): `react`, `react-dom`, `@material-ui/core`, `@sarex-team/sdk-js`.

## Обработка ошибок

Отдельного модуля маппинга ошибок в `projects-frontend` нет (в отличие от некоторых других фронтендов) — обработка ответов и ошибок делегирована `httpService` из `@sarex-team/sdk-js`. Заголовки CORS для запросов в режиме разработки задаются dev-сервером Webpack, а в кластере — политикой CORS Istio `VirtualService` (`.helm/templates/mesh-config.yaml`): разрешённые источники по регулярке `(https://.*\.sarex\.io)|(https://localhost:.*)`, методы `GET, POST, PUT, PATCH, HEAD, DELETE`, заголовки `Authorization`, `Content-Type`.