iac/apps/issues/ENDPOINTS.md

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

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

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

Запросы сгруппированы по доменным API-объектам в каталоге module/api/ (IssuesApi, CoreApi, PrescriptionsApi, InspectionsApi, AttributesApi, AssetsApi, ContractsApi, ResourcesApi, TemplatesApi, PremisesApi, DocumentationApi). Каждый метод вызывает единый httpService (module/api/http-service.ts).

httpService создаётся фабрикой createHttpService из @sarex-team/sdk-js и принимает карту хостов hosts (module/api/hosts.ts) и текущее окружение BUILD_ENV. Вызов задаётся объектом:

• service — логическое имя сервиса (ключ из hosts, см. таблицу ниже);
• метод — getRequest/postRequest/putRequest/patchRequest/deleteRequest;
• url — путь запроса (дописывается к базовому хосту сервиса);
• axiosConfig — доп. настройки axios (params, paramsSerializer, responseType и т.п.);
• data — тело запроса;
• showErrorNotification, queryKey, cache — опции показа ошибок, ключа кеша и кеширования.

Итоговый URL = <базовый хост сервиса для BUILD_ENV> + url. Базовый хост выбирается по BUILD_ENV (local/stage/prod/preprod/contour).

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

Значения из module/api/hosts.ts. Приведены stage и prod; в contour используются относительные пути, в preprod — домен api.preprod.sarex.io, в local — как в stage, но sarex проксируется на /sarex-backend.

Сервис (service)	Назначение	stage	prod
issues	Сервис замечаний (issues-backend, собственный API)	https://stage-api.sarex.io/issues/api	https://api.sarex.io/issues/api
prescriptions	Предписания (issues-backend)	https://stage-api.sarex.io/issues/api/prescriptions	https://api.sarex.io/issues/api/prescriptions
sarexApi	Gateway/API Sarex (/gateway, /issues, /inspections, /contracts)	https://stage-api.sarex.io	https://api.sarex.io
sarex	Локальный сервис данных (/api/core, /api/client)	"" (относительные пути)	""
gateway	Gateway Sarex	https://stage-api.sarex.io/gateway	https://api.sarex.io/gateway
documentations	Сервис документации	https://stage-api.sarex.io/documentations/api/v1	https://api.sarex.io/documentations/api/v1
eav	Сервис атрибутов/ассетов (EAV)	https://stage-api.sarex.io/eav/api	https://api.sarex.io/eav/api
files	Сервис файлов	https://stage-api.sarex.io/files/api/v1	https://api.sarex.io/files/api/v1
premises	Сервис помещений	https://stage-api.sarex.io/premises/api/v1	https://api.sarex.io/premises/api/v1
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	Сервис замечаний (remarks)	https://stage-api.sarex.io/remarks	https://api.sarex.io/remarks
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://login.sarex.io

Часть сервисов объявлена в карте хостов, но напрямую в module/api/* не вызывается (workspaces, workflows, comparisons, remarks, bim, bimv2, google, zitadel) — они используются инфраструктурой SDK / другими слоями. Сервис prescriptions объявлен в хостах, но методы предписаний фактически ходят через sarexApi по пути /issues/api/prescriptions.

Подключаемый удалённый модуль documentations описан отдельно в module/api/module-hosts.ts (remoteEntry.js микрофронтенда documentations).

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

issues — Сервис замечаний (собственный API)

Файл module/api/issuesApi.ts.

Метод API	HTTP	Путь	Назначение
IssuesApi.getStatusModels	GET	/companies/{companyId}/status-model/	Модель статусов компании (по resource_id, issue_type_id)
IssuesApi.getTypes	GET	/issue-types/	Типы замечаний компании (company_id)
IssuesApi.getIssue	GET	/issues/{public_id}/	Замечание по публичному id
IssuesApi.editIssue	PATCH	/issues/{publicId}/	Редактировать замечание
IssuesApi.getChanges	GET	/issue-changes/	История изменений замечания (issue_id)

sarexApi — Gateway/API Sarex

Файлы issuesApi.ts, prescriptionsApi.ts, inspections.ts, contractsApi.ts, attributes.ts.

Метод API	HTTP	Путь	Назначение
IssuesApi.postComment	POST	/issues/api/comments/	Добавить комментарии
IssuesApi.deleteComment	DELETE	/issues/api/comments/{id}/	Удалить комментарий
IssuesApi.postAttachment	POST	/issues/api/attachments/	Загрузить вложение (multipart)
IssuesApi.deleteAttachment	DELETE	/issues/api/attachments/{id}/	Удалить вложение (issue_public_id)
PrescriptionsApi.postPrescription	POST	/issues/api/prescriptions/	Создать предписание
PrescriptionsApi.getPrescriptions	GET	/issues/api/prescriptions/	Список предписаний (сериализованные фильтры в query)
InspectionsApi.getInspections	GET	/inspections/api/v1/inspections/light/	Список инспекций (company_id, limit, offset)
InspectionsApi.getInspectionTypes	GET	/inspections/api/v1/inspections/types/	Типы инспекций (company_id)
ContractsApi.getContracts	GET	/contracts/api/v0/contracts/	Договоры (tenant_id, contractor_id, resource_id)
AttributesApi.getDocumentAttributes	GET	/gateway/api/v1/documents/{documentId}/attributes/	Атрибуты документа

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

Файл module/api/coreApi.ts.

Метод API	HTTP	Путь	Назначение
CoreApi.getUserSettings	GET	/api/client/settings/	Клиентские настройки
CoreApi.getUsers	GET	/api/core/users/	Пользователи компании (company, limit, offset, show_inactive)
CoreApi.getDepartments	GET	/api/core/admin/departments/	Отделы компании
CoreApi.getPositions	GET	/api/core/admin/positions/	Должности компании

gateway — Gateway Sarex

Файлы coreApi.ts, resources.ts, templatesApi.ts.

Метод API	HTTP	Путь	Назначение
CoreApi.getGatewayUsers	GET	/api/v2/users/	Пользователи по ресурсу/правам (resource_id, permissions, limit, offset)
ResourcesApi.getResourceFullInfo	GET	/api/v2/resources/{resourceId}/	Полная информация о ресурсе
TemplatesApi.getTemplates	GET	/api/v1/disks/{diskId}/flat_documents/	Плоский список документов диска (type)

documentations — Сервис документации

Файлы documentation.ts, templatesApi.ts.

Метод API	HTTP	Путь	Назначение
DocumentationApi.getDocumentById	GET	/documents/{docId}	Документ по id (опц. extend)
TemplatesApi.getDisks	GET	/disks	Список дисков

eav — Атрибуты и ассеты (EAV)

Файлы assets.ts, attributes.ts.

Метод API	HTTP	Путь	Назначение
AssetsApi.getAssetsPost	POST	/v4/assets/search/	Поиск ассетов
AssetsApi.getAssetsGet	GET	/v4/assets/	Список ассетов
AttributesApi.getAttributes	GET	/v0/attribute/	Атрибуты компании (company_id)

files — Сервис файлов

Файл documentation.ts.

Метод API	HTTP	Путь	Назначение
DocumentationApi.getPage	GET	/pages/{sourceId}/{pageId}	Страница файла (ответ blob)

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

Файл premises-api.ts.

Метод API	HTTP	Путь	Назначение
PremisesApi.getPremise	GET	/premises/{id}/	Помещение по id
PremisesApi.getPremisesFilter	POST	/premises/filter/	Фильтрация помещений (limit, offset в query)
PremisesApi.getPremiseTypesFilter	POST	/premise_types/filter/	Фильтрация типов помещений (limit, offset в query)

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

Глобальная обработка выполняется в module/api/http-service.ts: httpService обёрнут в Proxy, который для методов запросов (getRequest/postRequest/putRequest/patchRequest/deleteRequest) перехватывает ошибку и при статусе 403 показывает toast-уведомление (react-toastify) с текстом detail из ответа либо сообщением «У вас недостаточно прав для выполнения данного действия», после чего пробрасывает ошибку дальше. Для отдельных запросов показ уведомлений включается флагом showErrorNotification: true. В окружении local SDK переключается в режим original (setSharedHttpServiceConfig({ type: "original" })).