Introduction

Пример сторонних контролов для вебклиента с использованием Webpack Module Federation и React

Build and Test

Скрипт	Назначение
npm run build:release	Релизная сборка в dist/ для загрузки через Dev Studio
npm run build:dev:remote	Dev-сборка remote-режима. Если заданы переменные SUNGERO_DEPLOY_BASE, SUNGERO_SOLUTION_NAME и SUNGERO_COMPONENT_NAME в .env — пишет на сервер, иначе в dist/
npm run build:dev:standalone	Dev-сборка standalone-режима (локальная отладка с заглушками)
npm run start:dev:remote	Hot-reload: следит за исходниками, пересобирает в серверную папку (переменные в .env обязательны)
npm run start:dev:standalone	Hot-reload локальной отладки: сборка + serve на http://localhost:3001
npm run serve	Хостинг собранного контрола из dist/ на http://localhost:3001
npm run check	Полная проверка: typecheck + lint + build:dev:remote
npm run check:full	Расширенная проверка: prettier:check + typecheck + lint + build:release
npm run format	Автоформатирование: prettier --write + eslint --fix

Настройка окружения

Dev-сборка на сервер использует три переменных окружения, задаваемые через .env-файл:

1. Скопировать .env.example в .env:

   cp .env.example .env

2. Заменить значения в .env на актуальные:

   SUNGERO_DEPLOY_BASE=D:<путь до директории со сторонними компонентами на сервере>
   SUNGERO_SOLUTION_NAME=Sungero.MySolution
   SUNGERO_COMPONENT_NAME=DemoComponent

Итоговый путь сборки: {SUNGERO_DEPLOY_BASE}/{SUNGERO_SOLUTION_NAME}.Components/{SUNGERO_COMPONENT_NAME}.

.env добавлен в .gitignore — настройки останутся локальными и не попадут в коммиты.

Standalone-отладка

Запуск контрола без хоста с тестовыми заглушками — для быстрой разработки и отладки UI.

Как запустить

npm run start:dev:standalone

Откроется http://localhost:3001 с выпадашкой для переключения между всеми контролами на лету, без правки кода и пересборки.

Заглушки

Файл	Что эмулирует
host-api-stub.ts	IRemoteComponentCardApi + IRemoteComponentCoverApi — executeAction, getEntity, canExecuteAction, getActionsMetadata, getSettings
host-context-stub.ts	IRemoteComponentContext — userId, culture, theme, logger, лицензии

Доступные контролы в выпадашке

• CardApiDemo — демонстрация Card API
• CoverApiDemo — демонстрация Cover API
• PerformedWorkDetailsGrid — грид выполненных работ
• StringControl — редактор строкового свойства
• Gantt — диаграмма Ганта
• ActionsPanel — панель действий обложки

Отладка с реальным хостом

Разработка контрола в контексте веб-клиента Sungero с автоматическим обновлением файлов на сервере при изменении кода.

Однократная настройка

1. Настроить .env (см. раздел «Настройка окружения» выше)
2. Собрать и загрузить компонент через Dev Studio (npm run build:release → загрузить dist/)

Hot-reload разработка

npm run start:dev:remote

Webpack следит за исходниками, при изменениях пересобирает бандл в папку компонента на сервере. Остаётся только обновить страницу в браузере (F5).

Разовая dev-сборка на сервер

npm run build:dev:remote

Если переменные в .env не заданы — сборка идёт в dist/.

Важно

• Переменные действуют только в dev-режиме и только для remote-сборки
• build:release всегда пишет в dist/, независимо от .env
• Standalone-режим всегда пишет в dist/
• .env в .gitignore — настройки остаются локальными и не попадают в коммиты

Воркараунды

В процессе разработки возникают ситуации, когда правильное решение недоступно из-за ограничений API хоста или платформы. Разработчик вынужден применить хак — захардкодить значение, написать обходной код.

Цель системы учёта воркараундов — отделить намеренные безвыходные решения от просто неправильных или необдуманных. Без такой маркировки аудитор не может отличить «это сделано криво, потому что разработчик не знал как лучше» от «это сделано криво, потому что по-другому невозможно».

Тег WORKAROUND-{номер} в коде явно говорит: «да, я знаю, что это выглядит неправильно, но вот причина, и она задокументирована».

Как это помогает:

• Аудит: grep -r "WORKAROUND-" src/ → мгновенный список всех хаков
• Статистика: сколько воркараундов, в каких модулях, как долго висят
• Приоритизация API: воркараунды, которые висят дольше всего — сигнал команде платформы, что именно нужно доработать в первую очередь
• Onboarding: новый разработчик видит не «странный код», а «WORKAROUND-{номер} — это потому что API не умеет X, не трогай, пока не появится метод Y»

Когда API дорабатывают и воркараунд становится не нужен — тег удаляется из кода, запись удаляется из файла. История остаётся в git.

Соглашение по оформлению и список текущих воркараундов — в WORKAROUND.md.