iac/apps/django/ENDPOINTS.md

# Эндпоинты и хосты сервисов для sarex-frontend

Документ описывает базовые хосты сервисов, к которым обращается фронтенд-шелл
`sarex-frontend`, и удалённые модули (Module Federation), которые он подгружает.
Backend для этого приложения — `sarex-backend` (Django), его конфигурация и
переменные описаны в `CONFIGURATION.md`, а серверное REST API — в `openapi.yaml`.

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

`sarex-frontend` — это host-приложение на **Webpack Module Federation**. Реестр
хостов задаётся декларативно в `endpoints.js` (корень репозитория): объект вида
`<сервис>.<тип>.<окружение>` → URL. Возможные типы:

- `api` / `apiV1` / `apiV2` / … — базовый URL REST API сервиса;
- `module` — URL `remoteEntry.js` удалённого микрофронтенда;
- `gateway` — базовый URL gateway.

Окружение выбирается сборочной переменной `ENDPOINT` (`process.env.ENDPOINT`,
по умолчанию `prod`) в `webpack.common.js`. Значения `endpoints.js[сервис][тип][ENDPOINT]`
пробрасываются в код как константы `process.env.<CONST>` через `DefinePlugin`
(объект `processEnvByEndpoint`), напр. `endpoints.bim.api[ENDPOINT]` → `BIM_API`.

Для локального запуска backend-таргет задаётся отдельно в `env.js`
(`SAREX_BACKEND`, по умолчанию `https://stage.sarex.io/`) и используется
dev-сервером (`webpack.dev.js`) как прокси; собственный Django-backend в окружении
`contour` доступен по относительным путям (пустой хост).

## Окружения (`ENDPOINT`)

| Значение | Назначение |
| --- | --- |
| `prod` | Продакшн (`https://api.sarex.io`, `https://modules.sarex.io`) |
| `stage` | Stage (`https://stage-api.sarex.io`, `https://stage-modules.sarex.io`) |
| `preprod` | Preprod (`https://api.preprod.sarex.io`, `https://modules.preprod.sarex.io`) |
| `contour` | Изолированный контур — относительные пути (пустой хост) |
| `local` | Локальная разработка (задан не у всех сервисов) |

> У части сервисов `gateway` определены также специальные ключи `contour_local`
> (`https://stage.sarex.io`) и `contour_prod` (`https://lk.sarex.io`).

## Базовые хосты API-сервисов

Итоговый URL = `<базовый хост сервиса>` + путь запроса.

| Сервис (`endpoints.*`) | Константа | `stage` | `prod` | `contour` |
| --- | --- | --- | --- | --- |
| `api.api` | `SAREX_API` | `https://stage-api.sarex.io` | `https://api.sarex.io` | `""` |
| `bim.api` | `BIM_API` | `https://stage-api.sarex.io/bim/api/v1` | `https://api.sarex.io/bim/api/v1` | `""` |
| `bim.apiV2` | `BIM_API_V2` | `…/bim/api/v2` | `…/bim/api/v2` | `""` |
| `bim.files` | `BIM_FILES` | `…/bim` | `…/bim` | `""` |
| `workspaces.api` / `workspacesV2.api` | `WORKSPACESV2_API` | `…/workspaces/` | `…/workspaces/` | `/workspaces/` |
| `workflows.api` | `WORKFLOWS_API` | `…/workflows` | `…/workflows` | `/workflows` |
| `remarks.api` | `REMARKS_API` | `…/remarks/api/v1` | `…/remarks/api/v1` | `/remarks/api/v1` |
| `issues.api` | `ISSUES_API` | `…/issues/api/v1` | `…/issues/api/v1` | `/issues/api/v1` |
| `issuesBase.api` | `ISSUES_BASE_API` | `…/issues/api` | `…/issues/api` | `/issues/api` |
| `flows.api` | — | `…/issues/api/v1` | `…/issues/api/v1` | `/issues/api/v1` |
| `inspections.api` | — | `…/inspections/api/v1` | `…/inspections/api/v1` | `/inspections/api` |
| `documentations.api` | `DOCUMENTATIONS_API` | `…/documentations/api/v1` | `…/documentations/api/v1` | `/documentations/api/v1` |
| `pm.api` | — | `…/documentations/api/v1` | `…/documentations/api/v1` | `/documentations/api/v1` |
| `analyticsV2.api` | — | `…/analytics-v2/api/v1` | `…/analytics-v2/api/v1` | `/analytics-v2/api/v1` |
| `analytics.api` | `ANALYTICS_API` | `…/analytics` | `…/analytics` | `/analytics` |
| `processes.api` | `PROCESSES_API` | `…/flows/api/v1` | `…/flows/api/v1` | `/flows/api/v1` |
| `gateway.gateway` | `GATEWAY` | `…/gateway` | `…/gateway` | (local: `http://localhost:9000/gateway`) |
| `gateway.api` | `GATEWAY_API` | `…/gateway/api/v1` | `…/gateway/api/v1` | `/gateway/api/v1` |
| `gateway.apiV2` | `GATEWAY_API_V2` | `…/gateway/api/v2` | `…/gateway/api/v2` | `/gateway/api/v2` |
| `eav.api` | `EAV_API` | `…/eav/api/v0` | `…/eav/api/v0` | `/eav/api/v0` |
| `eav.apiV1…apiV4` | `EAV_API_V1…V4` | `…/eav/api/v1…v4` | `…/eav/api/v1…v4` | `/eav/api/v1…v4` |
| `notifications.api` | `NOTIFICATIONS_API` | `…/lambdas/notification/` | `…/lambdas/notification/` | `""` |
| `lambdas.api` | `LAMBDAS_API` | `…/lambdas` | `…/lambdas` | `/lambdas` |
| `automations.api` | `AUTOMATIONS_API` | `…/automation/api/v1` | `…/automation/api/v1` | `/automation/api/v1` |
| `orchestrator.api` | `ORCHESTRATOR_API` | `…/orchestrator` | `…/orchestrator/api` | `/orchestrator/api` |

> `…` = `https://stage-api.sarex.io` (stage) или `https://api.sarex.io` (prod).
> Собственный Django-backend (`sarex-backend`) в контуре обслуживается по
> относительным путям `/api/...` — см. `openapi.yaml`.

## Удалённые модули (Module Federation, `remoteEntry.js`)

Хост подгружает микрофронтенды по URL из `endpoints.<сервис>.module[ENDPOINT]`.
Базовый хост модулей: `https://stage-modules.sarex.io` (stage) /
`https://modules.sarex.io` (prod); в контуре — относительные пути.

| Сервис | Константа | Путь `module` (относительный, контур) |
| --- | --- | --- |
| `workspaces` | `WORKSPACES_MODULE` | `/workspaces/module/remoteEntry.js` |
| `workspacesV2` | `WORKSPACESV2_MODULE` | `/workspaces-v2/module/remoteEntry.js` |
| `workflows` | `WORKFLOWS_MODULE` | `/workflows/module/remoteEntry.js` |
| `remarks` | `REMARKS_MODULE` | `/remarks/static/module/remoteEntry.js` |
| `issues` | `ISSUES_MODULE` | `/issues/static/module/remoteEntry.js` |
| `flows` | `FLOWS_MODULE` | `/flows/static/module/remoteEntry.js` |
| `inspections` | `INSPECTIONS_MODULE` | `/inspections/static/module/remoteEntry.js` |
| `documentations` | `DOCUMENTATIONS_MODULE` | `/documentations/static/module/remoteEntry.js` |
| `pm` | `PM_MODULE` | `/pm/module/remoteEntry.js` |
| `projects` | `PROJECTS_MODULE` | `/projects/static/module/remoteEntry.js` |
| `analyticsV2` | `ANALYTICS_MODULE` | `/analytics-v2/static/module/remoteEntry.js` |
| `reviews` | `REVIEWS_MODULE` | `/reviews/static/module/remoteEntry.js` |
| `administration` | `ADMINISTRATION_MODULE` | `/control-interface/modules/admin/remoteEntry.js` |
| `adminProc` | `ADMIN_PROC_MODULE` | `/admin-frontend/static/module/remoteEntry.js` |
| `assets` | `ASSETS_MODULE` | `/control-interface/modules/assets/remoteEntry.js` |
| `premises` | `PREMISES_MODULE` | `/premises/static/module/remoteEntry.js` |
| `contracts` | `CONTRACTS_MODULE` | `/cotracts/static/module/remoteEntry.js` |
| `transmittal` | `TRANSMITTAL_MODULE` | `/transmittal/static/module/remoteEntry.js` |
| `prescriptions` | `PRESCRIPTIONS_MODULE` | `/prescriptions/static/module/remoteEntry.js` |
| `rfi` | `RFI_MODULE` | `/rfi/static/module/remoteEntry.js` |
| `assistant` | — | `/assistant/static/module/remoteEntry.js` |

Список подключаемых в ЛК модулей (пункты меню) дублируется на стороне backend в
`SAREX_MODULES` (ConfigMap `django-configmap`): `remarks`, `issues`,
`documentations`, `reviews`, `processes`, `rfi`, `transmittal`.

## Backend, обслуживающий шелл

Основной API самого шелла (аутентификация, пользователи, настройки приложения,
проекты/цели/миссии, аналитика) — это `sarex-backend` под префиксом `/api/...`
(и `/internal/...` для внутрикластерных вызовов). Полное описание серверных
эндпоинтов приведено в `openapi.yaml`. Ключевые группы:

| Префикс | Назначение |
| --- | --- |
| `/api/token…`, `/api/auth/…`, `/api/login`, `/api/logout` | Аутентификация и JWT |
| `/api/app-settings/` | Настройки приложения |
| `/api/core/…` | Пользователи, компании, цели, миссии, ортофото, облака точек и т.д. |
| `/api/client/…` | Клиентский дашборд, загрузки, self-сервис |
| `/api/analytics/…` | Аналитические дашборды, метрики, виджеты |
| `/api/map/…` | Кадастр и заметки на карте |
| `/api/pg/…` | Облака точек, экспорт, измерения |
| `/internal/client/…` | Внутренние вызовы (настройки, токены) |