iac/apps/reviews/ENDPOINTS.md

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

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

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

В отличие от декларативного реестра endpoints.ts, запросы в reviews-frontend описаны императивно: в виде методов API-объектов и отдельных функций в каталоге module/api/ (а также в нескольких сторах/страницах). Каждый вызов идёт через единый httpService (module/api/http-service.ts), созданный createHttpService(...) из @sarex-team/sdk-js (поверх axios).

Вызов задаётся объектом со следующими полями:

• service — логическое имя сервиса (см. таблицу хостов ниже);
• метод определяется функцией httpService (getRequest/postRequest/putRequest/patchRequest/deleteRequest);
• url — путь запроса относительно базового хоста сервиса (базовый хост уже включает версионный префикс, напр. /api/v1);
• data — тело запроса (для POST/PUT/PATCH);
• axiosConfig — доп. настройки axios (params, paramsSerializer, responseType: "blob", timeout и т.п.);
• controller — AbortController для отмены запроса;
• showErrorNotification — показывать ли уведомление об ошибке (обрабатывается на стороне SDK).

Базовый хост подставляется SDK по имени service в зависимости от BUILD_ENV (см. module/api/hosts.ts). Итоговый URL = <базовый хост сервиса> + url.

Основные точки, где выполняются запросы:

Файл	Экспорт	Назначение
module/api/index.ts	ReviewAPI, DocumentAPI, IssuesAPI + отдельные функции (getUsersByResourceId, getUsersByCompanyId, getDepartments*, getPositions*, getMrpaList, fetchParentDocumentByResourceId, fetchDocumentsBundleVersions, getDocumentAncestors, getDiskDocumentsPath, fetchExportReviews*)	Ядро API: reviews, задачи, документы, справочники, экспорт
module/api/agents.ts	AgentsAPI	AI-агент подбора путей копирования (router-agent)
module/api/checklists.ts	ChecklistsAPI	Чек-листы и их результаты
module/api/documentations.ts	DocumentationsAPI	Дети папок с активными процессами
module/api/marks.ts	MarksAPI	Оркестрация штампов/подписей
module/api/tranmittals.ts	TransmittalsAPI	Создание трансмитталов и работа с шаблонами
module/pages/Review/CheckList/AiCheck/api.ts	AiCheckAPI	AI-проверка документов по чек-листу
module/store/stores/resources.ts	ResourcesStore.fetchResources	Список ресурсов компании
module/store/stores/users.ts	Users.fetchSettings	Клиентские настройки пользователя

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

Значения из module/api/hosts.ts. Базовый хост уже включает версионный префикс сервиса, поэтому в таблицах эндпоинтов ниже указан только url (без него).

Сервис (service)	Назначение	stage	prod
flows	Сервис рабочих процессов (reviews, задачи, документы review)	https://stage-api.sarex.io/flows/api/v1	https://api.sarex.io/flows/api/v1
documentations	Сервис документации (бандлы, файлы, штампы, подписи)	https://stage-api.sarex.io/documentations/api/v1	https://api.sarex.io/documentations/api/v1
gateway_api_v1	Gateway API v1 (ресурсы, документы, версии бандлов)	https://stage-api.sarex.io/gateway/api/v1	https://api.sarex.io/gateway/api/v1
gateway_api_v2	Gateway API v2 (пользователи по ресурсу)	https://stage-api.sarex.io/gateway/api/v2	https://api.sarex.io/gateway/api/v2
sarex	Локальный сервис данных (/api/core, /api/client)	"" (относительные пути)	""
eav_api_v0	Сервис атрибутов (EAV)	https://stage-api.sarex.io/eav/api/v0	https://api.sarex.io/eav/api/v0
checklists	Сервис чек-листов	https://stage-api.sarex.io/checklists/api/v1	https://api.sarex.io/checklists/api/v1
transmittals	Сервис передачи документации (трансмитталы, шаблоны)	https://stage-api.sarex.io/transmittals/api/v1	https://api.sarex.io/transmittals/api/v1
issues	Сервис замечаний	https://stage-api.sarex.io/issues/api	https://api.sarex.io/issues/api
orchestrator	Оркестратор процессов (штампы/подписи)	https://stage-api.sarex.io/orchestrator	https://api.sarex.io/orchestrator/api
files	Сервис файлов (скачивание бандлов)	https://stage-api.sarex.io/files/api/v1	https://api.sarex.io/files/api/v1
lambdas	Сервис экспорта (lambda-функции)	https://stage-api.sarex.io/lambdas	https://api.sarex.io/lambdas
sarexAgents	Сервис AI-агентов (проверка, подбор путей, загрузка файлов)	https://sarex-agents.dev.stage.sarex.io/api/v1	https://agents.sarex.tech/api/v1
zitadel	IdP (аутентификация)	https://idp.dev.stage.sarex.io	https://login.sarex.io

Также определены окружения local, preprod и contour. В contour все хосты — относительные пути (изолированный контур), а zitadel пуст. В local сервис sarex указывает на https://stage.sarex.io, а httpService переключается в режим zitadel (setTypeOfHttpService("zitadel") в http-service.ts). Подключаемый удалённый модуль documentations (Module Federation) описан отдельно в module/api/module-hosts.ts.

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

flows — Сервис рабочих процессов (reviews)

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
ReviewAPI.getReviews	POST	/reviews/filter/	Список reviews с фильтрами (пагинация limit/offset в query)
ReviewAPI.getReview	GET	/reviews/{id}/	Review по id
ReviewAPI.getReviewsByDocumentIds	GET	/documents/?document_ids={ids}&full=true&review_status=completed,canceled&limit=100000	Документы review по id документов
ReviewAPI.getReviewsByBundleCopiedIds	GET	/documents/?bundle_copied_ids={ids}&full=true&review_status=completed,canceled&limit=100000	Документы review по id скопированных бандлов
ReviewAPI.fetchCurrentTasks	GET	/tasks/	Текущие задачи (фильтры reviewer_id, is_active, resource_id, пагинация)
ReviewAPI.changePriorityTask	PATCH	/tasks/{id}/change-priority/	Изменить приоритет задачи
ReviewAPI.changeDurationTask	PATCH	/tasks/{id}/change-duration/	Изменить длительность задачи
ReviewAPI.getTasksEndDates	GET	/tasks/reviewers-max-end-dates/?{query}	Макс. даты завершения по проверяющим
ReviewAPI.getCountByResourceId	POST	/reviews/count_by_resource_id/	Количество reviews по ресурсам
ReviewAPI.getCountByReviewers	POST	/reviews/count_by_reviewer_id/	Количество reviews по проверяющим
ReviewAPI.getNextStepReviewers	GET	/steps/{stepId}/get_reviewers/?review_id={reviewId}	Проверяющие следующего шага
ReviewAPI.getReviewDocuments	GET	/reviews/{id}/documents/	Документы review
ReviewAPI.updateReviewDocument	PUT	/documents/{id}/	Обновить документ review
ReviewAPI.bulkUpdateReviewDocument	PUT	/reviews/{reviewId}/documents/	Массовое обновление документов review
ReviewAPI.setStatus	PATCH	/documents/set-status/?document_ids={ids}	Проставить статус документам
ReviewAPI.createReview	POST	/reviews/	Создать review
ReviewAPI.changeReviewers	PATCH	/reviews/{reviewId}/change_reviewers/	Сменить проверяющих
ReviewAPI.changeMinReviewers	PATCH	/reviews/{reviewId}/change-min-reviewers/	Изменить мин. число проверяющих
ReviewAPI.getTimeTrackerInfo	GET	/reviews/{reviewId}/time-tracking/	Данные тайм-трекинга review
ReviewAPI.startReview	PATCH	/reviews/{reviewId}/start/	Запустить review
ReviewAPI.patchReview	PATCH	/reviews/{id}/	Обновить атрибуты review
ReviewAPI.deleteReview	DELETE	/reviews/{id}/	Удалить review
ReviewAPI.activateReview / ReviewAPI.passReview	PATCH	/reviews/{id}/approve/	Утвердить/пройти review (с комментарием и статусом)
ReviewAPI.setReviewStep	PATCH	/reviews/{review_id}/set-step/{step_id}/	Установить шаг review
ReviewAPI.reviewUpdateBundles	PATCH	/reviews/{id}/update-bundles/	Обновить бандлы review
ReviewAPI.userAction	POST	/user-actions/	Записать действие пользователя
ReviewAPI.writeTransmittalCreated	POST	/reviews/{review_id}/transmittal-created/	Отметить создание трансмиттала для review
ReviewAPI.getProcesses	GET	/flows/light/?{query}	Список процессов (облегчённый)
ReviewAPI.getProcessById	GET	/flows/{id}/	Процесс по id
DocumentAPI.changeCopyPaths	PATCH	/documents/change-copy-paths/	Изменить пути копирования документов
ChecklistsAPI.createReviewsChecklistResult	PATCH	/reviews/{reviewId}/checklist-results/	Результаты чек-листа для review

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

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
DocumentAPI.getDocumentsBatch	POST	/documents/batch	Пакетное получение документов
DocumentAPI.mark	PUT	/bundles/{bundleId}/marks	Добавить штампы/QR/подписи
DocumentAPI.sign	POST	/bundles/{bundleId}/sign	Подписать бандл
DocumentAPI.downloadFile	GET	/bundles/{bundleId}/{key}/download	Скачать файл (ответ blob)
DocumentAPI.getDisks	GET	/disks	Список дисков
DocumentationsAPI.getFolderChildrenWithActiveProcesses	POST	/documents/flows	Дети папок с активными процессами
AiCheckAPI.getBundlePresignedUrl	GET	/bundles/{bundleDocumentId}/presigned_url?key=pdf	Presigned-URL PDF бандла

gateway_api_v1 — Gateway API v1

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
fetchResources (ResourcesStore)	GET	/resources/?company_id={companyId}	Список ресурсов компании
fetchParentDocumentByResourceId	GET	/resources-rpc/parent-document-by-resource-id/{resourceId}/	Родительский документ по resource id
fetchDocumentsBundleVersions	POST	/documents/bundle_versions	Версии бандлов документов
getDocumentAncestors	POST	/documents/ancestors	Предки документов
getDiskDocumentsPath	GET	/disks/{diskId}/documents?child_id={childId}	Путь документа на диске

gateway_api_v2 — Gateway API v2

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
getUsersByResourceId	GET	/users/?{query}	Пользователи по ресурсу (с правами)

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

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
Users.fetchSettings	GET	/api/client/settings/	Клиентские настройки пользователя
getUsersByCompanyId	GET	/api/core/users/?company={companyId}&{query}	Пользователи компании
getDepartments	GET	/api/core/admin/departments/	Отделы
getDepartmentsV2	GET	/api/core/admin/departments/?company={companyId}&{query}	Отделы компании (пагинация)
getPositions	GET	/api/core/admin/positions/	Должности
getPositionsV2	GET	/api/core/admin/positions/?company={companyId}&{query}	Должности компании (пагинация)
getMrpaList	POST	/api/core/mrpa/list/	Список MRPA

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

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
ReviewAPI.getAttributes	GET	/schema/?model_name=flow&company_id={companyId}	Схема атрибутов модели flow

checklists — Сервис чек-листов

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
ChecklistsAPI.getChecklist	GET	/checklists/{id}/	Чек-лист по id
ChecklistsAPI.getChecklistResults	GET	/results/	Результаты чек-листов (фильтры в query)
ChecklistsAPI.createChecklistResult	POST	/results/	Создать результат чек-листа
ChecklistsAPI.updateChecklistResult	PATCH	/results/{id}/	Обновить результат чек-листа

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

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
TransmittalsAPI.createTransmittal	POST	/transmittals/create	Создать трансмиттал
TransmittalsAPI.getTransmittals	POST	/transmittals	Список трансмитталов ресурса (пагинация по bookmark)
TransmittalsAPI.getTemplate	GET	/transmittal_templates/{templateId}?resource={resourceId}	Шаблон трансмиттала по id
TransmittalsAPI.getSelectTemplates	GET	/transmittal_templates/select?resource={resourceId}	Список шаблонов для выбора

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

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
IssuesAPI.getIssues	POST	/issues/filter/	Список замечаний с фильтрами (пагинация в query)
IssuesAPI.getIssuesTypesStatusModelsByCompanyId	GET	/status-models/?company_id={companyId}	Модели статусов замечаний компании

orchestrator — Оркестратор процессов

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
MarksAPI.createMarkFlow	POST	/process	Запустить процесс маркировки
MarksAPI.getMarkFlow	GET	/process/{id}	Процесс маркировки по id
MarksAPI.startSign	POST	/sign	Запустить подписание

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

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
DocumentAPI.downloadDocuments	POST	/documents/	Скачать документы по bundle_ids (ответ blob)

lambdas — Сервис экспорта

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
fetchExportReviewsByResourceIDs	GET	/export-reviews/{params}	Экспорт reviews в XLSX (ответ blob)
fetchExportReview	GET	/export-reviews/{reviewId}/report/	Экспорт отчёта по review в PDF (ответ blob)

sarexAgents — Сервис AI-агентов

Ключ (метод API)	HTTP-метод	Путь (url)	Назначение
AgentsAPI.suggestCopyPaths	POST	/runs/wait	Запуск router-agent для подбора путей копирования
AiCheckAPI.runValidator	POST	/runs/wait	Запуск AI-проверки документов по чек-листу
AiCheckAPI.getDocumentStorageStatus	GET	/files/documents/{documentId}/storage-status?tenant_id={tenantId}	Статус загрузки документа в хранилище
AiCheckAPI.uploadFileByUrl	POST	/files/upload/url	Загрузить файл по URL в RAG-каталог
AiCheckAPI.getEntitled	GET	/internal/tenant-agent-entitlements/{tenantId}/agents-status?user_id={userId}	Доступность AI-агента для тенанта

Запросы /runs/wait выполняются с увеличенным таймаутом RUN_WAIT_TIMEOUT_MS = 600000 мс (10 минут) и с showErrorNotification: false.

Удалённый модуль (Module Federation)

Помимо HTTP-API, reviews-frontend подключает удалённый микрофронтенд documentations через Module Federation (module/api/module-hosts.ts, функция getModuleHost):

Модуль	stage	prod
documentations	https://stage-modules.sarex.io/documentations/static/module/remoteEntry.js	https://modules.sarex.io/documentations/static/module/remoteEntry.js

В contour путь относительный (/documentations/static/module/remoteEntry.js), в preprod — https://modules.preprod.sarex.io/....

Аутентификация

Токен и режим аутентификации обеспечиваются @sarex-team/sdk-js. В окружении local httpService переводится в режim zitadel (setTypeOfHttpService("zitadel")), а хост IdP берётся из hosts.zitadel (https://idp.dev.stage.sarex.io для stage, https://login.sarex.io для prod). В остальных окружениях используется режим по умолчанию SDK.

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

Отдельного модуля маппинга ошибок (аналогичного errors.ts) в reviews-frontend нет. Обработка ошибок выполняется в двух местах:

• SDK @sarex-team/sdk-js — при showErrorNotification: true (значение по умолчанию для большинства запросов) показывает пользователю уведомление об ошибке. Для «тихих» запросов (AI-агенты, presigned-URL, часть фоновых вызовов) явно задаётся showErrorNotification: false.
• Локальные try/catch — в сторах (resources.ts, users.ts) и функциях экспорта (fetchExportReviews*) ошибки перехватываются и логируются через console.error, без проброса наверх.

Замечания

• Пути (url) указываются относительно базового хоста сервиса, который уже содержит версионный префикс (/api/v1, /api/v0 и т.п.). Это отличается от реестра endpoints.ts в некоторых других микрофронтендах, где префикс включается в путь эндпоинта.
• Файл module/api/tranmittals.ts назван с опечаткой (tranmittals вместо transmittals); экспорт при этом называется TransmittalsAPI.
• Сервис sarex в окружениях stage/prod/preprod/contour имеет пустой базовый хост ("") — запросы идут по относительным путям (через тот же origin/реверс-прокси); в local он указывает на https://stage.sarex.io.
• Хост сервиса orchestrator в prod содержит суффикс /api (.../orchestrator/api), тогда как в stage/preprod — без него (.../orchestrator); пути методов (/process, /sign) одинаковы.