iac/apps/remarks/ENDPOINTS.md

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

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

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

В отличие от transmittal-frontend, в remarks-frontend нет декларативного реестра эндпоинтов (endpoints.ts). Запросы формируются по месту — в API-объектах (module/api/*.ts) и в MobX-сторах (module/store/*.ts) — прямыми вызовами методов httpService:

• httpService.getRequest(options)
• httpService.postRequest(options)
• httpService.putRequest(options) (объявлен, в коде не используется)
• httpService.patchRequest(options)
• httpService.deleteRequest(options)

Каждый вызов задаётся объектом-параметром:

• service — логическое имя сервиса (см. таблицу хостов ниже), определяет базовый хост;
• url — путь запроса (часто шаблонная строка с подстановкой id/query);
• data — тело запроса (для POST/PATCH/PUT);
• axiosConfig — доп. настройки axios (params для query-параметров, responseType: "blob" для файлов и т.п.);
• showErrorNotification — включает показ уведомления об ошибке средствами SDK.

httpService (module/api/http-client.ts) — это Proxy поверх базового baseHttpService (module/api/http-service.ts, создаётся через createHttpService из @sarex-team/sdk-js). Прокси добавляет единую обработку ответа 403: показывает toast с текстом response.data.detail либо сообщением «У вас недостаточно прав для выполнения данного действия.». Базовый хост подставляется SDK по значению service и текущему окружению BUILD_ENV (значения — из module/api/hosts.ts, по умолчанию prod). В окружении local тип HTTP-сервиса переключается на zitadel (setTypeOfHttpService("zitadel")).

Итоговый URL = <базовый хост сервиса> + url эндпоинта.

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

Значения из module/api/hosts.ts.

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

Также определены окружения local и preprod. В preprod хосты указывают на https://api.preprod.sarex.io/* (для zitadel — https://login.preprod.sarex.io). В local сервис sarex проксируется на /sarex-backend, а остальные сервисы указывают на stage-хосты (https://stage-api.sarex.io/*, zitadel → https://idp.dev.stage.sarex.io). Сервис zitadel явно в коде не вызывается — используется SDK для аутентификации.

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

sarexApi — Gateway/API Sarex (issues / flows / eav)

Базовый хост — корневой (https://<env>-api.sarex.io); маршрутизация задаётся префиксами пути (/issues/api, /flows/api, /eav/api).

Метод	Путь	Назначение	Где вызывается
POST	/issues/api/issues/filter/	Список/фильтрация замечаний (пагинация limit/offset)	api/issues/issues.ts
POST	/issues/api/issues/	Создать замечание	store/collectionRemarks.ts
GET	/issues/api/issues/{uuid}/	Замечание по uuid	store/collectionRemarks.ts
PATCH	/issues/api/issues/{uuid}/	Обновить замечание	store/collectionRemarks.ts, store/remarks.ts
POST	/issues/api/issues/export/?{params}	Экспорт замечаний (ответ blob)	store/remarks.ts
GET	/issues/api/issues/daterange/	Диапазон дат замечаний	store/filters.ts
POST	/issues/api/issues/filter-options/?{params}	Опции фильтра замечаний	store/filters.ts
GET	/issues/api/issue-changes/?issue_id={uuid}	История изменений замечания	store/remark.ts
POST	/issues/api/comments/	Создать комментарий	store/collectionRemarks.ts
DELETE	/issues/api/comments/{id}/	Удалить комментарий	store/collectionRemarks.ts
GET	/issues/api/attachments/{fileId}/	Получить вложение	store/collectionRemarks.ts
POST	/issues/api/attachments/	Загрузить вложение	store/collectionRemarks.ts
DELETE	/issues/api/attachments/{id}/	Удалить вложение	store/collectionRemarks.ts
GET	/issues/api/companies/{companyId}/status-model/v2/	Модель статусов компании	store/remarks.ts
GET	/flows/api/v1/documents/	Документы (flows)	store/filters.ts
GET	/flows/api/v1/documents/?{query}&offset=0&limit=100000	Документы (flows, полная выборка)	store/remarks.ts
POST	/flows/api/v1/flows/filter/	Фильтрация flows	store/filters.ts
GET	/eav/api/v0/attribute/?company_id={params}	Атрибуты компании (EAV v0)	store/remarks.ts

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

Метод	Путь	Назначение	Где вызывается
GET	/api/v1/remarks?target=true{params}	Список замечаний по target	store/remarks.ts
DELETE	/api/v1/remarks/{uuid}	Удалить замечание	store/collectionRemarks.ts

gateway — Gateway Sarex

Метод	Путь	Назначение	Где вызывается
GET	/api/v2/users/?{query}	Пользователи (с фильтрами прав/таргета)	store/remarks.ts
GET	/api/v2/users/	Пользователи (без фильтров)	store/remarks.ts
GET	/api/v1/documents/{docId}/attributes/	Атрибуты документа	store/remarks.ts
GET	/api/v1/resources/	Список ресурсов	store/resourcesStore.ts

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

Метод	Путь	Назначение	Где вызывается
GET	/api/v1/documents/{docId}?extend=bundles	Документ с бандлами	store/remark.ts

eavV4 — Сервис ассетов (EAV v4)

Базовый хост уже включает префикс /eav/api/v4.

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

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

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

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

Отдельного файла-маппера ошибок (аналога module/api/errors.ts в transmittal-frontend) в проекте нет. Обработка сосредоточена в двух местах:

• module/api/http-client.ts — прокси перехватывает ответ 403 и показывает toast (react-toastify) с текстом response.data.detail или сообщением по умолчанию «У вас недостаточно прав для выполнения данного действия.»;
• SDK @sarex-team/sdk-js — при showErrorNotification: true показывает стандартное уведомление об ошибке; в сторах ряд операций дополнительно оборачивается в try/catch с собственными toast-сообщениями (напр. «Замечание успешно создано!» / «Произошла ошибка при создании замечания»).