154 lines
9.8 KiB
Markdown
154 lines
9.8 KiB
Markdown
# Связка с portal-front: запуск в dev, деплой в prod, тестовый стенд
|
||
|
||
Документ про встраивание конструктора в **portal-front** — React-приложение
|
||
портала. Про встраивание в админку Bitrix (пользовательский тип свойства
|
||
инфоблока) — отдельные документы:
|
||
[`bitrix-integration.md`](./bitrix-integration.md) и
|
||
[`backend-quickstart.md`](./backend-quickstart.md).
|
||
|
||
## 1. Как это устроено
|
||
|
||
Портал открывает конструктор в `<iframe>` **в режиме просмотра** и передаёт ему
|
||
схему через `postMessage`. Три вещи, которые надо знать, прежде чем что-то
|
||
запускать.
|
||
|
||
**Имя точки входа не константа.** Сборка выдаёт `index-<hash>.html`
|
||
(см. `vite.config.ts`, плагин `hashIndexHtml`), имя меняется при каждой
|
||
значимой пересборке. Рядом кладётся манифест со стабильным именем:
|
||
|
||
```json
|
||
{ "index": "index-300d7ef5.html" }
|
||
```
|
||
|
||
Портал читает его при открытии модалки — `fetch('app-manifest.js', { cache: 'no-store' })`
|
||
в `src/helpers/chart-builder.ts` — и уже к полученному имени дописывает
|
||
параметры. Поэтому выкладка конструктора **не требует пересборки портала**.
|
||
|
||
**Режим просмотра включается параметром.** Портал сам дописывает `?mode=view`:
|
||
редактор стартует в просмотре, переключатель режимов скрыт, `diagram:change`
|
||
портал игнорирует. В этом режиме приложение **всегда** берёт origin хоста из
|
||
`window.location.origin` и игнорирует `VITE_BITRIX_ORIGIN` — переменная нужна
|
||
только админке Bitrix, где встраивание идёт в режиме редактирования.
|
||
|
||
**Пути внутри сборки относительные** (`base: './'`), поэтому один и тот же
|
||
`dist/` работает из любого каталога размещения и переменной с путём больше нет.
|
||
|
||
Контракт обмена — `bitrix-integration.md`, раздел 4: приложение шлёт
|
||
`diagram:ready`, хост в ответ `diagram:init` с JSON-строкой схемы. На стороне
|
||
портала это `src/hooks/useDiagramBridge.ts`; если `diagram:ready` не пришёл за
|
||
10 секунд, в модалке появляется «Не удалось загрузить схему».
|
||
|
||
## 2. Dev
|
||
|
||
Портал на `http://localhost:5173`, конструктор на `http://localhost:5800`.
|
||
Порты разные, но портал проксирует конструктор на свой origin — без этого
|
||
режим просмотра не заработает (приложение отправит сообщения на 5800, то есть
|
||
самому себе, а не порталу).
|
||
|
||
Прокси уже прописан в `vite.config.ts` портала:
|
||
|
||
```ts
|
||
'/local/modules/vniigaz.bpmn/assets': {
|
||
target: 'http://localhost:5800',
|
||
changeOrigin: false,
|
||
rewrite: (path) => path.replace('/local/modules/vniigaz.bpmn/assets', '')
|
||
}
|
||
```
|
||
|
||
Порядок запуска:
|
||
|
||
```powershell
|
||
cd D:\Development\Work\portal-chart-builder; npm run build
|
||
```
|
||
|
||
```powershell
|
||
cd D:\Development\Work\portal-chart-builder; npm run preview
|
||
```
|
||
|
||
Порт 5800 зафиксирован в `vite.config.ts` (`preview.port` + `strictPort`), флаги
|
||
передавать не нужно. Если порт занят, `preview` упадёт с ошибкой, а не уедет на
|
||
соседний порт молча — иначе прокси портала указывал бы в пустоту.
|
||
|
||
```powershell
|
||
cd D:\Development\Work\portal-front; npm run dev
|
||
```
|
||
|
||
Переменные окружения не нужны ни там, ни там.
|
||
|
||
`npm run dev` самого конструктора для связки **не подходит**: `postMessage`-мост
|
||
включается только в production-сборке (`isProd` в `src/App.tsx`), в dev работает
|
||
`devAdapter` поверх localStorage. После правок в конструкторе — заново
|
||
`npm run build`; `preview` перезапускать не нужно, он читает файлы с диска.
|
||
|
||
Проверка, что связка поднята:
|
||
|
||
```powershell
|
||
curl.exe -s http://localhost:5173/local/modules/vniigaz.bpmn/assets/app-manifest.js
|
||
```
|
||
|
||
Пустой ответ — не поднят `preview` или не собран конструктор.
|
||
|
||
## 3. Prod (портал, бэк и конструктор на одном домене)
|
||
|
||
```powershell
|
||
cd D:\Development\Work\portal-chart-builder; npm run build
|
||
```
|
||
|
||
Дальше **очистить** каталог `local/modules/vniigaz.bpmn/assets/` в дереве сайта
|
||
и скопировать туда содержимое `dist/`. Именно очистить: имена файлов содержат
|
||
хеш, старые сборки не перезаписываются, а накапливаются — и ломают запасной
|
||
способ поиска точки входа «взять единственный `index-*.html`».
|
||
|
||
Портал пересобирается **только когда меняется сам портал**:
|
||
|
||
```powershell
|
||
cd D:\Development\Work\portal-front; npm run build
|
||
```
|
||
|
||
Проверка после выкладки:
|
||
|
||
```powershell
|
||
curl.exe -s https://ВАШ-ДОМЕН/local/modules/vniigaz.bpmn/assets/app-manifest.js
|
||
```
|
||
|
||
Имя в ответе должно совпадать с реально лежащим файлом. Открыть `index-<hash>.html`
|
||
напрямую в браузере тоже полезно: вечное «Загрузка диаграммы…» там — норма,
|
||
приложение ждёт `diagram:init` от родителя, которого при прямом открытии нет.
|
||
Значит, статика раздаётся правильно.
|
||
|
||
## 4. Тестовый стенд и админка Bitrix
|
||
|
||
Отличие одно: там встраивание идёт **в режиме редактирования**, без `?mode=view`,
|
||
и только в этом случае учитывается `VITE_BITRIX_ORIGIN`.
|
||
|
||
Рекомендация — не задавать её вообще (удалить `.env.production.local`): origin
|
||
возьмётся из `window.location.origin` и совпадёт с любым адресом, по которому
|
||
открыли админку — `localhost:8590`, IP или домен. Приложение и админка на одном
|
||
домене, так что это корректно всегда.
|
||
|
||
Если переменная всё-таки задаётся, её значение должно совпадать с адресной
|
||
строкой браузера **посимвольно, включая порт**: `http://192.168.100.146` и
|
||
`http://192.168.100.146:8590` — разные origin. При расхождении обмен молча не
|
||
состоится, ошибок в консоли не будет.
|
||
|
||
Второе требование к встраивающей стороне — не писать имя `index-<hash>.html`
|
||
строкой, а брать актуальное из `app-manifest.js` (или искать единственный `index-*.html`,
|
||
но тогда очистка каталога при деплое обязательна). Подробности — в
|
||
`backend-quickstart.md`, раздел 1.
|
||
|
||
## 5. Переменные окружения
|
||
|
||
| Переменная | Dev | Prod (портал) | Админка Bitrix |
|
||
|---|---|---|---|
|
||
| `VITE_BASE_PATH` | не существует, `base: './'` | то же | то же |
|
||
| `VITE_BITRIX_ORIGIN` | игнорируется в `mode=view` | игнорируется в `mode=view` | учитывается; лучше не задавать |
|
||
|
||
## 6. Если схема не появилась
|
||
|
||
| Что видно | Причина | Что делать |
|
||
|---|---|---|
|
||
| «Не удалось загрузить схему» в модалке | манифест не отдался либо не пришёл `diagram:ready` за 10 секунд | проверить `app-manifest.js` через curl, затем в Network — дошёл ли `index-<hash>.js` |
|
||
| Пустой iframe, в консоли 404 на `index-<hash>.js` | файлы сборки не докопированы или скопированы не в тот каталог | перекопировать `dist/` целиком |
|
||
| Приложение висит на «Загрузка диаграммы…» | `diagram:ready` ушёл не туда: origin хоста не совпал с ожидаемым | для админки — сверить `VITE_BITRIX_ORIGIN` с адресной строкой; для dev — проверить, что конструктор открывается через прокси портала, а не напрямую с 5800 |
|
||
| Портал открывает старую версию схемы | в каталоге лежат файлы прошлых сборок, `app-manifest.js` указывает на новый, а старый html закеширован браузером | очистить каталог при деплое; хеш в имени сам по себе кэш не победит, если старый файл остаётся на месте |
|