iac/apps/contracts/ENDPOINTS.md

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