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

Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `contracts-frontend`).

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

Запросы сгруппированы по доменам в каталоге `src/shared/api/fetch/*.api.ts`. Каждая функция вызывает соответствующий метод `httpService` (`src/shared/api/http-service.ts`), который создаётся фабрикой `createHttpService` из `@sarex-team/sdk-js` (поверх `axios`). Для запроса указываются:

- `service` — логическое имя сервиса (см. таблицу хостов ниже);
- `url` — путь запроса (добавляется к базовому хосту сервиса);
- `data` — тело запроса (для `post`/`put`);
- `axiosConfig.params` — query-параметры;
- `cache`, `queryKey` — опции кеширования (react-query-подобные ключи из `src/shared/api/keys/*`);
- `isCSRF` — включение CSRF-обработки (для `departments`).

Базовый хост подставляется по значению `service` и текущему окружению `__BUILD_ENV__` (`local`/`stage`/`preprod`/`prod`, по умолчанию `prod`; см. `http-service.ts`). В режиме `local` для http-сервиса устанавливается тип `zitadel` (`setTypeOfHttpService("zitadel")`). Итоговый URL = `<базовый хост сервиса>` + `url`.

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

Значения из `src/shared/api/hosts.ts`. Ниже перечислены сервисы, **фактически используемые** запросами модуля; в реестре хостов определены и другие сервисы (`bim`, `bimv2`, `workflows`, `workspaces`, `documentations`, `comparisons`, `remarks`, `projects`, `eavV1`, `notifications`, `google`, `sarexApi`, `zitadel`), но обращений к ним в `fetch/*` нет.

| Сервис (`service`) | Назначение | `stage` | `prod` |
| --- | --- | --- | --- |
| `contracts` | Сервис договоров (contracts-backend) | `https://stage-api.sarex.io/contracts` | `https://api.sarex.io/contracts` |
| `sarex` | Локальный backend Sarex (core/admin) | `""` (относительные пути) | `""` |
| `gateway` | Gateway/API Sarex (ресурсы/проекты) | `https://stage-api.sarex.io/gateway` | `https://api.sarex.io/gateway` |

> Также определены окружения `local` и `preprod`. В `local` сервисы проксируются на относительные пути (`contracts` → `/sarex-contracts`, `sarex` → `/sarex-backend`, `gateway` → `/sarex-gateway`, `zitadel` → `/zitadel`). Значения `preprod` используют домен `api.preprod.sarex.io`.

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

### `contracts` — Сервис договоров

Определены в `src/shared/api/fetch/contract.api.ts`.

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `fetchContractsByResourceId` | GET | `/api/v0/contracts` | Список договоров (query: `limit`, `offset`, `resource_id`, `tenant_id`) |
| `fetchCreateContractByResourceId` | POST | `/api/v0/contracts` | Создать договор |
| `fetchUpdateContract` | PUT | `/api/v0/contracts/{contract.id}` | Обновить договор по id |

> Функция удаления `fetchDeleteContract` (`DELETE /api/v0/contracts/{contractId}`) присутствует в коде, но закомментирована.

### `sarex` — Локальный backend Sarex (core/admin)

Определены в `company.api.ts`, `contractor.api.ts`, `department.api.ts`.

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `fetchCompanies` | GET | `/api/core/admin/companies/` | Список компаний (кешируется, ключ `companies`) |
| `fetchContractors` | GET | `/api/core/admin/contractors/?company_id={companyId}` | Контрагенты компании (кешируется, ключ `contractors`) |
| `fetchDepartments` | GET | `/api/core/admin/departments/` | Отделы (кешируется, ключ `departments`, `isCSRF: true`) |

### `gateway` — Gateway/API Sarex

Определён в `project.api.ts`.

| Функция | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `fetchProjects` | GET | `/api/v1/resources/?company_id={companyId}` | Список ресурсов/проектов компании (кешируется, ключ `projects`) |

## Обработка запросов и кеширование

Кеширование включается флагом `cache: true` с ключом `queryKey` (значения ключей — в `src/shared/api/keys/*.ts`: `companies`, `projects`, `contractors`, `departments`). Обработка ошибок и авторизация (в т.ч. режим `zitadel` для `local`) выполняются внутри `httpService` из `@sarex-team/sdk-js`.