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