115 lines
9.9 KiB
Markdown
115 lines
9.9 KiB
Markdown
# Эндпоинты, с которыми взаимодействует 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-сообщениями (напр. «Замечание успешно создано!» / «Произошла ошибка при создании замечания»).
|