Правки для лучшей интеграции
This commit is contained in:
NikitaKalitov
@@ -16,7 +16,7 @@
|
||||
3. Готово — но с оговоркой: приложение доступно **не** по фиксированному `index.html`.
|
||||
|
||||
**Имя `index.html` в `dist/` — с хешем содержимого**, например `index-2fddeca6.html`, а не просто `index.html` (см. `vite.config.ts`, плагин `hashIndexHtml` — хеширует и сам HTML-файл, не только JS/CSS, которые Vite и так хеширует по умолчанию). Хеш меняется при каждой значимой пересборке и не меняется, если содержимое не менялось. Значит:
|
||||
- **`src` у iframe нельзя хардкодить строкой** — нужно на своей стороне подставлять актуальное имя файла. Готовый способ: рядом с билдом сборка кладёт `app.json` со **стабильным** именем и актуальным именем точки входа внутри — `{ "index": "index-2fddeca6.html" }`. Прочитать его можно и с бэкенда, и прямо из браузера (`fetch('app.json', { cache: 'no-store' })`). Альтернативы — взять единственный `index-*.html` в каталоге или отдать имя отдельным методом; выбор за бэкендом.
|
||||
- **`src` у iframe нельзя хардкодить строкой** — нужно на своей стороне подставлять актуальное имя файла. Готовый способ: рядом с билдом сборка кладёт `app-manifest.js` со **стабильным** именем и актуальным именем точки входа внутри — `{ "index": "index-2fddeca6.html" }`. Прочитать его можно и с бэкенда, и прямо из браузера (`fetch('app-manifest.js', { cache: 'no-store' })`). Альтернативы — взять единственный `index-*.html` в каталоге или отдать имя отдельным методом; выбор за бэкендом.
|
||||
- Ручной cache-busting (`?v=...`) для JS/CSS/HTML **больше не нужен**: раз URL меняется вместе с содержимым, старый закэшированный файл просто никогда больше не запрашивается, как только известно новое имя.
|
||||
- **После каждого редеплоя старые `index-<hash>.html`/`index-<hash>.js`/`index-<hash>.css` от прошлых версий стоит убирать** из `local/diagram-app/` — они не удаляются сами, и если способ поиска актуального файла — «взять единственный файл по маске», их накопление сломает эту логику.
|
||||
|
||||
|
||||
@@ -219,13 +219,13 @@ Backend не обязан ничего валидировать глубже «
|
||||
|
||||
Из этого следует главное отличие от более ранней версии данного документа: **`$appUrl` в PHP-классе (раздел 3) больше нельзя хардкодить как строку** — конкретное имя `index-<hash>.html` меняется при каждой пересборке приложения. Бэкенду нужен свой способ узнавать актуальное имя файла на момент рендера страницы (например, взять единственный `index-*.html` из каталога деплоя, или через отдельный метод/эндпоинт, который вернёт актуальное имя, — механизм на усмотрение бэкенда, здесь не фиксирован, уточняйте на момент внедрения).
|
||||
|
||||
**Готовый механизм — `app.json` рядом с билдом.** Тот же плагин `hashIndexHtml` кладёт в `dist/` файл со стабильным, никогда не меняющимся именем:
|
||||
**Готовый механизм — `app-manifest.js` рядом с билдом.** Тот же плагин `hashIndexHtml` кладёт в `dist/` файл со стабильным, никогда не меняющимся именем:
|
||||
|
||||
```json
|
||||
{ "index": "index-2fddeca6.html" }
|
||||
```
|
||||
|
||||
Его можно прочитать как с бэкенда при рендере страницы, так и на клиенте — `fetch('<каталог>/app.json', { cache: 'no-store' })`, — и уже к полученному имени дописывать `?mode=view`. `no-store` здесь обязателен: имя файла стабильно, значит сам манифест попадает под тот же 30-дневный `Cache-Control`, что и остальная статика. Этим сейчас пользуется portal-front (`src/helpers/chart-builder.ts`), пока у бэка нет своего метода.
|
||||
Его можно прочитать как с бэкенда при рендере страницы, так и на клиенте — `fetch('<каталог>/app-manifest.js', { cache: 'no-store' })`, — и уже к полученному имени дописывать `?mode=view`. `no-store` здесь обязателен: имя файла стабильно, значит сам манифест попадает под тот же 30-дневный `Cache-Control`, что и остальная статика. Этим сейчас пользуется portal-front (`src/helpers/chart-builder.ts`), пока у бэка нет своего метода.
|
||||
|
||||
Взамен это полностью снимает необходимость в отдельном cache-busting query-параметре (`?v=...`) — раньше он был обязателен и для самого `index.html`, и (до появления хеша у самого файла) для `index.js`/`index.css` внутри него. Теперь URL меняется вместе с содержимым: старый закэшированный `index-OLDHASH.html` просто никогда больше не запрашивается, как только хост узнаёт новое имя — что убирает разом оба уровня кэш-проблемы, описанной в более ранней версии этого раздела.
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
{ "index": "index-300d7ef5.html" }
|
||||
```
|
||||
|
||||
Портал читает его при открытии модалки — `fetch('app.json', { cache: 'no-store' })`
|
||||
Портал читает его при открытии модалки — `fetch('app-manifest.js', { cache: 'no-store' })`
|
||||
в `src/helpers/chart-builder.ts` — и уже к полученному имени дописывает
|
||||
параметры. Поэтому выкладка конструктора **не требует пересборки портала**.
|
||||
|
||||
@@ -83,7 +83,7 @@ cd D:\Development\Work\portal-front; npm run dev
|
||||
Проверка, что связка поднята:
|
||||
|
||||
```powershell
|
||||
curl.exe -s http://localhost:5173/local/modules/vniigaz.bpmn/assets/app.json
|
||||
curl.exe -s http://localhost:5173/local/modules/vniigaz.bpmn/assets/app-manifest.js
|
||||
```
|
||||
|
||||
Пустой ответ — не поднят `preview` или не собран конструктор.
|
||||
@@ -108,7 +108,7 @@ cd D:\Development\Work\portal-front; npm run build
|
||||
Проверка после выкладки:
|
||||
|
||||
```powershell
|
||||
curl.exe -s https://ВАШ-ДОМЕН/local/modules/vniigaz.bpmn/assets/app.json
|
||||
curl.exe -s https://ВАШ-ДОМЕН/local/modules/vniigaz.bpmn/assets/app-manifest.js
|
||||
```
|
||||
|
||||
Имя в ответе должно совпадать с реально лежащим файлом. Открыть `index-<hash>.html`
|
||||
@@ -132,7 +132,7 @@ curl.exe -s https://ВАШ-ДОМЕН/local/modules/vniigaz.bpmn/assets/app.json
|
||||
состоится, ошибок в консоли не будет.
|
||||
|
||||
Второе требование к встраивающей стороне — не писать имя `index-<hash>.html`
|
||||
строкой, а брать актуальное из `app.json` (или искать единственный `index-*.html`,
|
||||
строкой, а брать актуальное из `app-manifest.js` (или искать единственный `index-*.html`,
|
||||
но тогда очистка каталога при деплое обязательна). Подробности — в
|
||||
`backend-quickstart.md`, раздел 1.
|
||||
|
||||
@@ -147,7 +147,7 @@ curl.exe -s https://ВАШ-ДОМЕН/local/modules/vniigaz.bpmn/assets/app.json
|
||||
|
||||
| Что видно | Причина | Что делать |
|
||||
|---|---|---|
|
||||
| «Не удалось загрузить схему» в модалке | манифест не отдался либо не пришёл `diagram:ready` за 10 секунд | проверить `app.json` через curl, затем в Network — дошёл ли `index-<hash>.js` |
|
||||
| «Не удалось загрузить схему» в модалке | манифест не отдался либо не пришёл `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.json` указывает на новый, а старый html закеширован браузером | очистить каталог при деплое; хеш в имени сам по себе кэш не победит, если старый файл остаётся на месте |
|
||||
| Портал открывает старую версию схемы | в каталоге лежат файлы прошлых сборок, `app-manifest.js` указывает на новый, а старый html закеширован браузером | очистить каталог при деплое; хеш в имени сам по себе кэш не победит, если старый файл остаётся на месте |
|
||||
|
||||
Reference in New Issue
Block a user