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