ADR-UI-014. Рантайм-конфигурация

1. Контекст и постановка задачи

Приложению нужен адрес API (и потенциально другие параметры) на старте. Эти параметры различаются между средами (локальная разработка, dev-стенд, stage, прод), но артефакт сборки должен быть один — иначе выпуск в каждую среду требует отдельного билда, что усложняет релиз и повышает риск расхождений.

Стандартный шаблон Angular (environments/environment.ts) не подходит: он работает на этапе сборки, а не старта. Нужен способ подменять конфиг у уже собранного приложения.

У нас фронт и API на стенде — на разных origin, поэтому apiBaseUrl — абсолютный, а бэк держит CORS-allowlist по среде (см. связанный backend-ADR).

2. Драйверы решения

1. Один билд на все среды — конфиг подменяется без пересборки.
2. Конфиг гарантированно готов к первому запросу — никакой код не обратится к API раньше, чем конфиг загружен.
3. Прозрачный доступ — apiBaseUrl берётся инъекцией очевидного сервиса, без чтения window и глобальных объектов.
4. Стандартный механизм Angular — без хаков в index.html.

3. Рассмотренные варианты

• A. config.json + provideAppInitializer + fetch — Angular ждёт резолва инициализатора до bootstrap; конфиг кладётся в сервис-сигнал.
• B. <script src="config.js"> в index.html — синхронно выставляет глобальный объект до bootstrap. Без асинхронного ожидания, но завязан на window и тег <script>.
• C. environment.ts — build-time; требует пересборки на каждую среду. Отклонено.

4. Решение

Выбран Вариант A: config.json грузится через provideAppInitializer и кладётся в RuntimeConfigService.

4.1. Контракт config.json

Файл — в src-ui/public/config.json (Angular кладёт содержимое public/ в корень dist). Это рантайм-артефакт: на каждой среде заменяется своей версией средствами деплоя.

{ "apiBaseUrl": "https://sok-api.dev.example" }

Расширение состава ключей — дополнением этого раздела, без нового ADR.

4.2. RuntimeConfigService

• providedIn: 'root', хранит конфиг в signal;
• load() — fetch('config.json', { cache: 'no-store' }), вызывается из provideAppInitializer;
• apiBaseUrl — геттер; при обращении до инициализации бросает явную ошибку (не «тихий» undefined).

provideAppInitializer(() => inject(RuntimeConfigService).load()),

4.3. Связка с генерированным API-клиентом

Базовый URL сгенерированного клиента (@api/icd) задаётся токеном BASE_PATH — через фабрику из RuntimeConfigService (ADR-UI-012):

{ provide: BASE_PATH, useFactory: () => inject(RuntimeConfigService).apiBaseUrl },

Токен резолвится при первом создании api-сервиса (открытие страницы) — уже после инициализатора, конфиг гарантированно загружен.

4.4. Правила

1. apiBaseUrl — только из RuntimeConfigService. Никаких window.*, прямого чтения config.json, импорта из environment.ts.
2. config.json не кэшируется — no-store в fetch и на отдаче с сервера; иначе смена конфига потребует жёсткого обновления у каждого пользователя.
3. В репозитории лежит config.json с локальными значениями (http://localhost:5080); реальные значения сред — в артефактах деплоя (генерятся devops/configs-generator).
4. Секретов в config.json нет — значения видны в network tab; только публичные параметры.

5. Положительные следствия

• Один билд → все среды; деплой меняет только config.json.
• К первому обращению к API конфиг уже загружен — нет гонок.
• Расширение конфига — поле в интерфейсе и в config.json, без пересборки потребителей.

6. Отрицательные следствия и компромиссы

• Старт добавляет один HTTP-запрос (сотни байт). На медленной сети заметно; при необходимости — переход на синхронный <script> (вариант B).
• Значения конфига видны в браузере — секреты туда класть нельзя.

7. Проверка

• Подмена config.json в собранном dist меняет адрес API без пересборки.
• Обращение к apiBaseUrl до инициализации даёт явную ошибку, не undefined.
• В коде нет обращений к API мимо RuntimeConfigService / токена BASE_PATH.

8. Открытые вопросы / отложено

• Доп. ключи (appVersion, флаги фич) — по мере необходимости, дополнением этого ADR.
• Отдача config.json без кэша на CDN/прокси — настройка инфраструктуры; no-store обязателен.

9. Связанные артефакты

• ADR_SRV_004_AppConfigAndCors — конфиг бэка и CORS-allowlist по среде.
• ADR_UI_012_ApiAndModels — регистрация api-клиента и токен базового URL BASE_PATH.