iac/apps/inspections/ENDPOINTS.md

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

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

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

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

• service — логическое имя сервиса (см. таблицу хостов ниже);
• url — путь запроса (дописывается к базовому хосту сервиса);
• data — тело запроса (для POST/PATCH);
• axiosConfig — доп. настройки axios (params, paramsSerializer и т.п.);
• showErrorNotification — показывать ли уведомление об ошибке.

Базовый хост подставляется по паре «service + окружение». Окружение определяется глобальной переменной сборки BUILD_ENV (local/stage/preprod/prod/contour); при её отсутствии используется prod (const buildEnv = BUILD_ENV ?? "prod"). В режиме local для http-сервиса выставляется type: "original". BUILD_ENV задаётся при сборке (напр. BUILD_ENV=stage npm start) и прокидывается через webpack DefinePlugin.

Определения запросов сгруппированы по файлам в module/api/ (inspections.ts, assets.ts, Issues.ts, premises-api.ts) и по стор-файлам в module/Inspections/store/ (inspections.ts, filters.ts, resource.ts, calendar.ts, issuesStore.ts).

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

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

Сервис (service)	Назначение	stage	prod
inspections	Сервис событий/инспекций (этот бэкенд)	https://stage-api.sarex.io/inspections/api/v1	https://api.sarex.io/inspections/api/v1
sarexApi	Gateway/API Sarex (/gateway)	https://stage-api.sarex.io	https://api.sarex.io
sarex	Локальный сервис данных (/api/core, /api/client)	"" (относительные пути)	""
eavV0	Сервис атрибутов EAV, API v0	https://stage-api.sarex.io/eav/api/v0	https://api.sarex.io/eav/api/v0
eavV4	Сервис атрибутов EAV, API v4 (ассеты)	https://stage-api.sarex.io/eav/api/v4	https://api.sarex.io/eav/api/v4
issues	Сервис замечаний	https://stage-api.sarex.io/issues/api	https://api.sarex.io/issues/api
premises	Сервис помещений	https://stage-api.sarex.io/premises/api/v1	https://api.sarex.io/premises/api/v1
zitadel	IdP (аутентификация)	https://idp.dev.stage.sarex.io	https://login.sarex.io

Также определены окружения local, preprod и contour. В local сервис sarex проксируется на /sarex-backend, а inspections/eav/issues/premises указывают на стейдж. В contour все хосты пустые (относительные пути для изолированного контура). Сервис zitadel в hosts объявлен, но прямых запросов из модуля к нему нет — аутентификация обрабатывается на уровне SDK/платформы.

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

inspections — Сервис событий/инспекций

Базовый хост уже включает /api/v1, поэтому в путях ниже он не повторяется.

Метод	Путь	Где вызывается	Назначение
GET	/inspections/	store/resource.ts	Создание/список событий
POST	/inspections/	store/resource.ts	Создать событие
POST	/inspections/filter/	store/resource.ts, store/calendar.ts	Список событий с фильтрами и пагинацией в теле
GET	/inspections/{id}/	api/inspections.ts, store/resource.ts	Событие по id
PATCH	/inspections/{id}/	api/inspections.ts	Частичное обновление события
GET	/inspections/types/	api/inspections.ts	Типы событий компании (query company_id)
POST	/inspections/status-count/	store/inspections.ts	Счётчики по статусам (фильтры в теле)
POST	/inspections/filter-options/	store/filters.ts	Доступные значения фильтров
GET	/inspections/aggregate/created_at/minmax/	store/filters.ts	Мин/макс по дате создания
GET	/inspections/aggregate/inspection_dt/minmax/	store/filters.ts	Мин/макс по дате проведения
GET	/inspections/change-history/	api/inspections.ts	История изменений (пагинация, фильтры в query)
GET	/inspections/export/	store/inspections.ts	Экспорт событий (xlsx)
POST	/inspections/unavailable-dates/	api/inspections.ts	Недоступные даты для исполнителей
POST	/inspections/unavailable-users/	api/inspections.ts	Недоступные исполнители на интервал

sarexApi — Gateway/API Sarex

Метод	Путь	Где вызывается	Назначение
GET	/gateway/api/v1/resources/?company_id={companyId}	store/inspections.ts	Ресурсы (проекты) компании
GET	/gateway/api/v2/users/	store/issuesStore.ts, store/resource.ts	Пользователи (с пагинацией/фильтрами)
GET	/gateway/api/v1/attachments/?company_id={companyId}&instance_id={id}&model_name=inspection	store/resource.ts	Вложения события
POST	/gateway/api/v1/attachments/	store/resource.ts	Создать вложение
DELETE	/gateway/api/v1/attachments/{id}	store/resource.ts	Удалить вложение

sarex — Локальный сервис данных

Метод	Путь	Где вызывается	Назначение
GET	/api/client/settings/	store/inspections.ts	Клиентские настройки
GET	/api/core/users/	store/inspections.ts	Пользователи
GET	/api/core/admin/departments/?company={companyId}	store/inspections.ts	Отделы компании
GET	/api/core/admin/positions/?company={companyId}	store/inspections.ts	Должности компании

eavV4 — Сервис атрибутов EAV (ассеты)

Метод	Путь	Где вызывается	Назначение
POST	/assets/search/	api/assets.ts	Поиск ассетов по списку id
GET	/assets/	api/assets.ts	Список ассетов (фильтры/пагинация/теги в query)

Теги ассетов (EnumAssetTags): location, project_structure, events.can_be_selected, remarks.can_be_selected.

eavV0 — Сервис атрибутов EAV (атрибуты)

Метод	Путь	Где вызывается	Назначение
GET	/attribute/?company_id={companyId}	store/inspections.ts	Атрибуты компании

issues — Сервис замечаний

Метод	Путь	Где вызывается	Назначение
POST	/issues/	api/Issues.ts	Создать замечание
GET	/issues/	api/Issues.ts	Список замечаний (фильтры по компании/ресурсу/событию/типам)
POST	/attachments/	api/Issues.ts, store/issuesStore.ts	Прикрепить медиа к замечанию
GET	/companies/{companyId}/status-model/	api/Issues.ts	Статусная модель замечаний компании
GET	/issue-types/	api/Issues.ts	Типы замечаний компании

premises — Сервис помещений

Базовый хост уже включает /api/v1.

Метод	Путь	Где вызывается	Назначение
GET	/premises/{id}/	api/premises-api.ts	Помещение по id
POST	/premises/filter/	api/premises-api.ts	Помещения по фильтру (пагинация в query)
POST	/premise_types/filter/	api/premises-api.ts	Типы помещений по фильтру (пагинация в query)

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

Показ уведомлений об ошибках управляется флагом showErrorNotification в параметрах запроса (включается точечно для части запросов). Для сериализации query-параметров-массивов местами используется query-string с arrayFormat: "comma" (напр. в api/Issues.ts). Часть запросов в api/assets.ts оборачивает ошибку в throw new Error(...).