95 lines
9.2 KiB
Markdown
95 lines
9.2 KiB
Markdown
# Эндпоинты, с которыми взаимодействует projects-frontend
|
||
|
||
Документ описывает все HTTP-эндпоинты внешних сервисов, к которым обращается модуль (микрофронтенд `projects-frontend`), а также удалённые модули, которые он подключает и экспортирует через Module Federation.
|
||
|
||
## Как устроено взаимодействие
|
||
|
||
Запросы описаны в слое `src/shared/api`. Функции запросов сгруппированы по доменам в каталоге `src/shared/api/fetch/*.api.ts` и реэкспортируются из `src/shared/api/index.ts` (`targetsApi`, `resourcesApi`, `projectsApi`, `userApi`, `companyApi`).
|
||
|
||
Каждый запрос выполняется через единый `httpService` (`src/shared/api/http-service.ts`), созданный фабрикой `createHttpService` из `@sarex-team/sdk-js` (поверх `axios`). У сервиса есть методы `getRequest` / `postRequest` / `putRequest` / `deleteRequest`, принимающие объект с полями:
|
||
|
||
- `service` — логическое имя сервиса (см. таблицу хостов ниже);
|
||
- `url` — путь запроса (относительно базового хоста сервиса);
|
||
- `data` — тело запроса (для POST/PUT);
|
||
- `axiosConfig.params` — query-параметры;
|
||
- `isCSRF` — признак необходимости передать CSRF-токен (для сервиса `sarex`);
|
||
- `cache`, `queryOptions`, `queryKey` — опции кеширования и ключи кеша.
|
||
|
||
Базовый хост подставляется по `service` из карты хостов `src/shared/api/hosts.ts` в зависимости от окружения сборки. Окружение задаётся значением `__ENDPOINT__`, которое подставляется на этапе сборки Webpack (`DefinePlugin`) из переменной `BUILD_ENV` и по умолчанию равно `prod` (`const endpoint = (__ENDPOINT__ as TypeEnvironment) || "prod"`).
|
||
|
||
## Базовые хосты по сервисам и окружениям
|
||
|
||
Значения из `src/shared/api/hosts.ts`. Итоговый URL = `<базовый хост сервиса>` + `url` эндпоинта.
|
||
|
||
| Сервис (`service`) | Назначение | `local` | `stage` | `prod` |
|
||
| --- | --- | --- | --- | --- |
|
||
| `sarex` | Основной backend (core, pm) | `/sarex-backend` (прокси dev-сервера → `https://stage.sarex.io`) | `/` (относительные пути, тот же origin) | `/` |
|
||
| `gateway` | Gateway/API Sarex | `/sarex-gateway` (прокси → `https://stage-api.sarex.io/gateway`) | `https://stage-api.sarex.io/gateway` | `https://api.sarex.io/gateway` |
|
||
| `documentations` | Сервис документации | `/sarex-documentations` (прокси → `https://stage-api.sarex.io/documentations`) | `https://stage-api.sarex.io/documentations` | `https://api.sarex.io/documentations` |
|
||
| `sarexApi` | API Sarex (корень) | `/sarex-api` (прокси → `https://stage-api.sarex.io`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
|
||
| `workspaces` | Сервис рабочих областей | `""` | `https://stage-api.sarex.io/workspaces` | `https://api.sarex.io/workspaces` |
|
||
| `workflows` | Сервис обработки документов | `""` | `https://stage-api.sarex.io/workflows` | `https://api.sarex.io/workflows` |
|
||
| `comparisons` | Сервис сравнений | `""` | `https://stage-api.sarex.io/comparisons` | `https://api.sarex.io/comparisons` |
|
||
| `remarks` | Сервис замечаний | `""` | `https://stage-api.sarex.io/remarks` | `https://api.sarex.io/remarks` |
|
||
| `projects` | Сервис проектов | `""` | `https://stage-api.sarex.io/projects` | `https://api.sarex.io/projects` |
|
||
| `eavV1` | EAV (атрибуты) | — | `https://stage-api.sarex.io/eav` | `https://api.sarex.io/eav` |
|
||
| `notifications` | Сервис уведомлений (lambdas) | — | `https://stage-api.sarex.io/lambdas/notification` | `https://api.sarex.io/lambdas/notification` |
|
||
| `bim` / `bimv2` | BIM-API | `""` | `https://stage-api.sarex.io/bim` / `/bimv2` | `https://api.sarex.io/bim` / `/bimv2` |
|
||
| `google` | Временное хранилище (GCS) | `""` | `https://storage.googleapis.com/srx-tmp` | `https://storage.googleapis.com/srx-tmp` |
|
||
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |
|
||
|
||
> Также определено окружение `preprod` (`https://api.preprod.sarex.io/*`, `zitadel` → `https://login.preprod.sarex.io`). В `local` часть сервисов проксируется dev-сервером Webpack (`configWebpack/buildDevServer.ts`): `/sarex-backend`, `/sarex-gateway`, `/sarex-documentations`, `/sarex-api`. Остальные сервисы в `local` заданы пустой строкой (относительные пути). Окружение `contour` присутствует в конфигурации сборки (`build.config.ts`), но в `hosts.ts` для него карта хостов не задана.
|
||
|
||
## Эндпоинты по сервисам
|
||
|
||
Реально вызываются эндпоинты двух сервисов — `sarex` и `gateway`.
|
||
|
||
### `sarex` — Основной backend (core, pm)
|
||
|
||
Все запросы к `sarex` выполняются с `isCSRF: true`.
|
||
|
||
| Функция | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `fetchTargetLinks` | GET | `/api/core/target-links/` | Список ссылок таргета (кешируется, `stateTime: 20`) |
|
||
| `fetchCreateTargetLink` | POST | `/api/core/target-links/` | Создать ссылку (`name`, `link`, `target`, `type`) |
|
||
| `fetchUpdateTargetLink` | PUT | `/api/core/target-links/{id}/` | Обновить ссылку |
|
||
| `fetchDeleteTargetLink` | DELETE | `/api/core/target-links/{id}/` | Удалить ссылку |
|
||
| `fetchMilestonesByProjectId` | GET | `/api/pm/msp/projects/{projectId}/key_milestones/` | Ключевые вехи проекта |
|
||
| `fetchUsersByCompanyId` | GET | `/api/core/users/?companies={companyId}&limit=10000&id={usersIds}` | Пользователи компании по списку id |
|
||
| `fetchCompanyById` | GET | `/api/core/companies/{companyId}/` | Компания по id (кешируется) |
|
||
|
||
### `gateway` — Gateway/API Sarex
|
||
|
||
| Функция | Метод | Путь | Назначение |
|
||
| --- | --- | --- | --- |
|
||
| `fetchResources` | GET | `/api/v1/resources?company_id={companyId}` | Список ресурсов компании (кешируется, `stateTime: 20`) |
|
||
| `fetchProjectsByCompanyId` | GET | `/api/v2/resources?company_id={companyId}&limit=10000` | Проекты компании (ресурсы v2, кешируется) |
|
||
|
||
## Удалённые модули (Module Federation)
|
||
|
||
Помимо HTTP-запросов, модуль взаимодействует с другими микрофронтендами через Webpack Module Federation.
|
||
|
||
### Подключаемый удалённый модуль
|
||
|
||
`src/widgets/remote-timeline` динамически загружает удалённый модуль `srx_pm`, экспонированный модуль `./Timeline` (`src/widgets/remote-timeline/ui/timelineProxy.tsx`, загрузка через `src/widgets/remote-timeline/lib/loader.ts`).
|
||
|
||
| Окружение | URL `remoteEntry.js` |
|
||
| --- | --- |
|
||
| `stage` | `https://stage-modules.sarex.io/pm/module/remoteEntry.js` |
|
||
| `local` | `https://stage-modules.sarex.io/pm/module/remoteEntry.js` |
|
||
| `prod` | `https://modules.sarex.io/pm/module/remoteEntry.js` |
|
||
| `preprod` | `https://modules.sarex.io/pm/module/remoteEntry.js` |
|
||
| `contour` | `""` (не задан) |
|
||
|
||
### Экспортируемый модуль
|
||
|
||
Сам `projects-frontend` при сборке (для всех окружений, кроме `local`) публикует себя как удалённый модуль `srx_projects` (`webpack.config.ts`, `ModuleFederationPlugin`):
|
||
|
||
- `filename`: `module/remoteEntry.js`;
|
||
- `exposes`: `./ProjectsPage` → `./src/app/App.tsx`;
|
||
- `shared` (singleton): `react`, `react-dom`, `@material-ui/core`, `@sarex-team/sdk-js`.
|
||
|
||
## Обработка ошибок
|
||
|
||
Отдельного модуля маппинга ошибок в `projects-frontend` нет (в отличие от некоторых других фронтендов) — обработка ответов и ошибок делегирована `httpService` из `@sarex-team/sdk-js`. Заголовки CORS для запросов в режиме разработки задаются dev-сервером Webpack, а в кластере — политикой CORS Istio `VirtualService` (`.helm/templates/mesh-config.yaml`): разрешённые источники по регулярке `(https://.*\.sarex\.io)|(https://localhost:.*)`, методы `GET, POST, PUT, PATCH, HEAD, DELETE`, заголовки `Authorization`, `Content-Type`.
|