# Конфигурация проекта documentation-frontend

Документ описывает сборку, рантайм-конфигурацию и деплой микрофронтенда `documentation-frontend` (образ `documentation-frontend-app`, деплой `frontend` в домене `documentations`).

## Способ конфигурирования

Это фронтенд-модуль (Module Federation remote), поэтому в отличие от backend-сервисов он **не** читает переменные окружения в рантайме. Единственный параметр конфигурации, влияющий на поведение, — окружение сборки `BUILD_ENV`, которое webpack «зашивает» в бандл на этапе сборки.

- Значение берётся из `process.env.BUILD_ENV` при запуске webpack.
- Webpack подставляет его как глобальную константу `BUILD_ENV` через `DefinePlugin` (`webpack.config.js`).
- Допустимые значения проверяются в `env.js`: `local`/`stage`/`preprod`/`prod`/`contour`. Если значение не входит в набор — сборка падает с ошибкой.
- `build.config.js` по `BUILD_ENV` выбирает режим webpack (`mode`/`devtool`): `local`/`stage` → `development` + `eval-source-map`, `prod`/`preprod`/`contour` → `production` + `source-map`.
- В рантайме `BUILD_ENV` определяет базовые хосты сервисов (`module/api/hosts.ts`, `resolveHost`) и тип http-сервиса (`module/api/http-service.ts`: при `local` — `setTypeOfHttpService("original")`). Подробности по хостам и эндпоинтам — в `frontend.ENDPOINTS.md`.

## Переменные сборки

| Переменная | Где используется | Назначение |
| --- | --- | --- |
| `BUILD_ENV` | `env.js`, `build.config.js`, `webpack.config.js` (`DefinePlugin`), `Dockerfile` (`ARG`), `.gitlab-ci.yml` (`--build-arg`) | Окружение сборки: `local`/`stage`/`preprod`/`prod`/`contour`. Определяет режим сборки и базовые хосты API |
| `NPM_NEXUS_TOKEN` | `Dockerfile` (`ARG`), `.npmrc`, `.gitlab-ci.yml` (`--build-arg`) | Токен доступа к приватному npm-реестру (Nexus) при `npm i` |

Отдельного `.env`-файла в репозитории нет; переменные передаются как build-arg'и Docker/CI.

## Сборка (`package.json`, `Dockerfile`)

Скрипты npm:

| Скрипт | Команда | Назначение |
| --- | --- | --- |
| `build-module` | `webpack --config webpack.config.js` | Сборка модуля в `dist` (используется в образе) |
| `serve-module` | `webpack serve --config webpack.config.js` | Dev-сервер (порт `9002`, https) |
| `lint` | `eslint ./module/**/*.ts(x) --fix` | Линтинг |
| `start` | `BUILD_ENV=local run-p serve-module storybook` | Локальный запуск (dev-сервер + Storybook) |
| `storybook` / `build-storybook` | `start-storybook` / `build-storybook` | Storybook |

Сборка образа (`Dockerfile`, multi-stage):

1. Стадия `static` (`node:16`): `npm i --legacy-peer-deps` с `NPM_NEXUS_TOKEN`, затем `npm run lint` и `BUILD_ENV=$BUILD_ENV npm run build-module` → артефакты в `/app/dist`.
2. Финальная стадия (`nginx:1.19.6`): копирует `dist` в `/dist` и `nginx/nginx.conf` в `/etc/nginx/nginx.conf`.

Module Federation (`webpack.config.js`, `ModuleFederationPlugin`): имя remote — `srx_documentations`, `filename: module/remoteEntry.js`. Экспонируемые модули: `./DocumentationsPage`, `./DocumentSelect`, `./CreateDocDialog`, `./DownloadFilesDialog`, `./FileBindingsDialog`. Shared-зависимости (singleton): `react`, `react-dom`, `@material-ui/core`, `@material-ui/styles`, `@sarex-team/sdk-js`, `@sarex-team/translator`, `@sarex-team/ui-kit`, `mobx`, `mobx-react-lite`.

## Деплой (Helm, `.helm/values.yaml`)

Чарт использует общий `universal-chart`. Ключевые значения для сервиса `frontend`:

- `deployment.name._default`: `documentation-frontend-static`; порт контейнера `80`.
- `replicaCount`: `stage` — 1, `preprod` — 2, `production` — 2.
- Пробы `liveness`/`readiness`: `httpGet /ping` на порту `80`.
- `resources.requests`: `memory 100Mi`, `cpu 100m`.
- `image.name._default`: `cr.yandex/crp3ccidau046kdj8g9q/documentation-frontend-static:latest` (в CI переопределяется на собранный `IMAGE_NAME` через `HELM_SET_ARGS`).
- `service`: `ClusterIP`, порт `80` (в `stage` — `8080`), `targetPort 80`, `portName http`.
- `imagePullSecrets.name._default`: `dockerhub`.

## CI/CD (`.gitlab-ci.yml`)

Пайплайн подключает шаблоны `generic/common-ci` (`common-security-scan.yaml`, `universal-pipeline.yaml`, ref `apps-business`). `SERVICE_NAME`: `documentation-frontend-app`. Окружение переключается по ветке/тегу (`workflow.rules`):

| Условие | STAND | Namespace | `BUILD_ENV` | `global.env` | `CHART_VERSION` |
| --- | --- | --- | --- | --- | --- |
| ветка `stage` | `stage` | `documentations` | `stage` | `stage` | `0.0.1-stage` |
| ветка `master` | `preprod` | `documentations-preprod` | `preprod` | `preprod` | `0.0.1-preprod` |
| тег (`CI_COMMIT_TAG`) | `prod` | `documentations-prod` | `prod` | `production` | `0.0.1-prod` |
| merge request | — | — | — | — | сборка образа отключена (`ENABLE_BUILD_IMAGE: "false"`) |

Каждая ветка задаёт `BUILD_ARGS` (`--build-arg BUILD_ENV=... --build-arg NPM_NEXUS_TOKEN=...`) и `HELM_SET_ARGS` (образ, `global.env`, `commitSha`, `gitlabUri`, `gitlabJobUrl`, `owner`), а также `K8S_HUSTLER_BRANCH` соответствующего окружения (`universal-chart-stage`/`-preprod`/`-production`).
