iac/apps/notes/ENDPOINTS.md

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