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

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

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

Все запросы собраны в объекте `notesApi` в `module/api/endpoints.ts`. Каждый метод вызывает `httpService` (`module/api/http-service.ts`, обёртка над `@sarex-team/sdk-js`) одним из методов `getRequest` / `postRequest` / `putRequest` / `deleteRequest`, передавая:

- `service` — логическое имя сервиса (см. таблицу хостов ниже);
- `url` — путь запроса (относительно базового хоста сервиса);
- `data` — тело запроса (для POST/PUT).

Базовый хост подставляется `httpService` из `module/api/hosts.ts` в зависимости от `BUILD_ENV` (`local`/`stage`/`preprod`/`prod`). `BUILD_ENV` задаётся через webpack `DefinePlugin` на этапе сборки (`build.config.js`). Итоговый URL = `<базовый хост сервиса>` + `url`. Удалённый модуль `documentations` (Module Federation) подключается отдельно через `module/api/modules-hosts.ts`.

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

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

| Сервис (`service`) | Назначение | `stage` | `prod` |
| --- | --- | --- | --- |
| `notes` | Бэкенд заметок (notes-backend) | `https://stage-api.sarex.io/notes` | `https://api.sarex.io/notes` |
| `sarexApi` | Gateway/API Sarex (`/eav`, `/notes`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
| `documentations` | Сервис документации (бандлы) | `https://stage-api.sarex.io/documentations/` | `https://api.sarex.io/documentations/` |
| `sarex` | Основной backend Sarex (`/api/core`) | `""` (относительные пути) | `""` |
| `workspaces` | Сервис рабочих областей | `https://stage-workspaces.sarex.io` | `https://workspaces.sarex.io` |
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |

> Также определены окружения `local` и `preprod`. В `local` `sarex` указывает на `https://stage.sarex.io`, в остальных — пустая строка (относительные пути). Сервисы `workspaces` и `zitadel` объявлены в хостах, но напрямую из `endpoints.ts` не вызываются. Удалённый модуль `documentations` описан в `module/api/modules-hosts.ts` (`…/documentations/static/module/remoteEntry.js`).

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

### `notes` — Бэкенд заметок (notes-backend)

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `createNote` | POST | `/api/v1/notes/` | Создать заметку |
| `getNote` | GET | `/api/v1/notes/{id}/` | Заметка по id |
| `updateNote` | PUT | `/api/v1/notes/{id}/` | Обновить заметку |
| `deleteNote` | DELETE | `/api/v1/notes/{id}/` | Удалить заметку |
| `getNoteAttachments` | GET | `/api/v1/notes/{noteId}/attachments/` | Вложения заметки |
| `createAttachmentsToNote` | POST | `/api/v1/notes/{noteId}/attachments/` | Загрузить вложения к заметке |
| `deleteAttachmentsFromNote` | DELETE | `/api/v1/attachments/{attachmentId}/` | Удалить вложение |
| `generateDocument` | POST | `/api/v1/notes/{noteId}/generate_document/` | Сгенерировать документ по заметке |
| `postScreen` | POST | `/api/v1/nd/bound-note/{noteId}/` | Привязать скриншот/файл к заметке (НД) |

### `sarexApi` — Gateway/API Sarex

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getAttributes` | GET | `/eav/api/v0/attribute/` | Атрибуты (EAV) |
| `createLinkNote` | POST | `/notes/api/v1/links/` | Привязать ссылку к заметке (через gateway) |

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

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getBundle` | GET | `/api/v1/bundles/{id}` | Бандл по id |

### `sarex` — Основной backend Sarex (`/api/core`)

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getCompanies` | GET | `/api/core/companies/` | Список компаний |
| `createLink` | POST | `/api/core/target-links/` | Создать ссылку у target |
| `updateLink` | PUT | `/api/core/target-links/{id}/` | Обновить ссылку |
| `deleteLink` | DELETE | `/api/core/target-links/{id}/` | Удалить ссылку |

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

Централизованного модуля обработки ошибок (аналога `errors.ts`) нет. Ответы `httpService` (`@sarex-team/sdk-js` поверх axios) обрабатываются в местах вызова — в MobX-сторах (`module/Notes/stores/notes.ts`, `sendScreen.ts`) через `try/catch`.

## Замечания

- Путь `postScreen` (`/api/v1/nd/bound-note/{noteId}/`) не совпадает с фактическим маршрутом бэкенда `/api/v1/nd/nd_proxy/{instance_id}/bound/` — при интеграции стоит свериться с актуальным API notes-backend.
- Часть создания/обновления ссылок идёт через сервис `sarex` (`/api/core/target-links/`), а привязка ссылки к заметке — через `sarexApi` (`/notes/api/v1/links/`).
- В `endpoints.ts` присутствует закомментированный устаревший вариант `updateLink` (декларативный стиль `service/method/path/body`) — актуальна функция-обёртка над `httpService`.