Правка по хэшам

docs/bitrix-integration.md

@@ -44,8 +44,12 @@ class DiagramProperty
 
         // Вариант A — рекомендуемый, приложение лежит внутри дерева портала (см. раздел 7):
         // appOrigin — это просто origin текущего запроса, appUrl — конкретный файл.
+        // ВАЖНО: имя файла — не константа. dist/index.html выходит из сборки как
+        // index-<hash>.html (хеш меняется при каждой значимой пересборке, см.
+        // раздел 7) — 'index.html' строкой здесь писать нельзя, нужно получать
+        // актуальное имя каким-то способом на своей стороне (см. раздел 7).
         $appOrigin = (CMain::IsHTTPS() ? 'https://' : 'http://') . $_SERVER['HTTP_HOST'];
-        $appUrl = $appOrigin . '/local/diagram-app/index.html';
+        $appUrl = $appOrigin . '/local/diagram-app/' . GetActualDiagramAppIndexFile(); // пример, не готовая функция
         // Вариант B — если приложение развёрнуто отдельным контейнером (см. раздел 7),
         // appUrl/appOrigin вместо этого указывают на его отдельный адрес, например:
         // $appOrigin = 'http://localhost:5178';
@@ -209,14 +213,13 @@ Backend не обязан ничего валидировать глубже «
 Что это даёт технически:
 - Nginx-конфиг стенда отдаёт файлы по расширению (`js|css|html|svg|png|...`) напрямую с диска — это срабатывает раньше, чем запрос попадёт в PHP-роутер Bitrix. Любой статический файл под корнем сайта отдаётся сам, никаких правок nginx не требуется.
 - `local/` уже существует как каталог для кастомного кода (`ai`, `components`, `modules`, `php_interface`, `templates` — по факту на дев-стенде). Новый подкаталог, например `local/diagram-app/`, вписывается в эту конвенцию и не пересекается с `local/modules`/`local/php_interface` — они у nginx явно помечены `internal` (заблокированы для прямого внешнего доступа), новый подкаталог под этот блок не попадает.
-- Нюанс: `index` на уровне сервера — `index.php`, не `index.html`. Открыть голый `/local/diagram-app/` (без имени файла) не выйдет — nginx попытается найти там `index.php` и не найдёт. Не проблема: PHP-класс (раздел 3) сам подставляет `src` у iframe, поэтому в `$appUrl` достаточно явно указывать файл — `/local/diagram-app/index.html`.
+- Нюанс: `index` на уровне сервера — `index.php`, не `index.html`. Открыть голый `/local/diagram-app/` (без имени файла) не выйдет — nginx попытается найти там `index.php` и не найдёт. PHP-класс (раздел 3) сам подставляет `src` у iframe — но, в отличие от более ранней версии этого документа, **больше нельзя просто написать `/local/diagram-app/index.html` строкой** — см. следующий пункт.
 - Так как приложение и портал теперь на одном домене, `VITE_BITRIX_ORIGIN`/`appOrigin` — это просто origin самого портала, а не адрес отдельного сервиса.
-- **Важный нюанс, найден живым тестом на дев-стенде:** тот же regex-location в nginx, что раздаёт статику, ставит `.html`-, `.js`- и `.css`-файлам одинаковый `Cache-Control: public` с `expires 30d`. Это касается **двух независимых уровней**, и решать их нужно по отдельности — закрыть только один недостаточно:
+- **Имена файлов в `dist/` — с хешем содержимого, включая сам `index.html`.** `index.js`/`index.css`/шрифты хеширует сам Vite при сборке (стандартное поведение, как в любом Vite-проекте). Кроме того, в `vite.config.ts` есть небольшой плагин (`hashIndexHtml`), который **дополнительно хеширует и сам `index.html`** — на выходе получается что-то вроде `index-2fddeca6.html`, а не просто `index.html`. Имя меняется всякий раз, когда меняется что-то значимое (сама HTML-обёртка либо то, что она подключает), и не меняется при пересборке без реальных изменений.
 
-  1. **Кэш самого `index.html`.** После повторного деплоя (обновили React-приложение, положили новый `dist/` поверх старого) браузер, уже открывавший `$appUrl` раньше, может до 30 дней получать из кэша старый `index.html` вместо нового. Решение: тот, кто формирует `src` у iframe (PHP-класс из раздела 3, либо любой другой хост), должен сам добавлять к нему cache-busting query-параметр, привязанный к версии сборки (например, `?v=<git-hash>` или `?v=<дата билда>`), а не отдавать голый `/local/diagram-app/index.html` без параметров.
-  2. **Кэш `index.js`/`index.css`, на которые ссылается сам `index.html`.** Тут пункт 1 не помогает: даже если браузер честно перезапросит свежий `index.html` (URL с новым `?v=` не совпал с закэшированным), внутри этого свежего файла ссылки на `index.js`/`index.css` — те же самые, неизменные имена (в приложении нет хеша в имени файла, см. `vite.config.ts` — сделано намеренно, чтобы имена были человекочитаемыми). Если эти конкретные URL уже лежат в кэше браузера с прошлого визита, он отдаст их с диска, даже не сходив на сервер, — HTML окажется свежим, а исполняемый код внутри него старым.
+  Из этого следует главное отличие от более ранней версии данного документа: **`$appUrl` в PHP-классе (раздел 3) больше нельзя хардкодить как строку** — конкретное имя `index-<hash>.html` меняется при каждой пересборке приложения. Бэкенду нужен свой способ узнавать актуальное имя файла на момент рендера страницы (например, взять единственный `index-*.html` из каталога деплоя, или через отдельный метод/эндпоинт, который вернёт актуальное имя, — механизм на усмотрение бэкенда, здесь не фиксирован, уточняйте на момент внедрения).
 
-     Пока это **не автоматизировано** и остаётся на усмотрение того, кто деплоит: либо вручную версировать `index.js`/`index.css` внутри задеплоенного `dist/index.html` при каждом обновлении, либо настроить на стороне nginx `Cache-Control` для этих файлов иначе (например, `no-cache`/`must-revalidate`). Если проблема будет всплывать на практике — можно вернуться к автоматизации на стороне сборки.
+  Взамен это полностью снимает необходимость в отдельном cache-busting query-параметре (`?v=...`) — раньше он был обязателен и для самого `index.html`, и (до появления хеша у самого файла) для `index.js`/`index.css` внутри него. Теперь URL меняется вместе с содержимым: старый закэшированный `index-OLDHASH.html` просто никогда больше не запрашивается, как только хост узнаёт новое имя — что убирает разом оба уровня кэш-проблемы, описанной в более ранней версии этого раздела.
 
 Порядок действий:
 
@@ -227,8 +230,8 @@ Backend не обязан ничего валидировать глубже «
    `VITE_BITRIX_ORIGIN` в этом варианте не задаётся — см. примечание в конце раздела.
    `VITE_BASE_PATH` — путь, под которым будет отдаваться приложение (нужен, чтобы ссылки на JS/CSS внутри `dist/index.html` были корректными под этим подпутём; см. `vite.config.ts`). По умолчанию, если переменная не задана, `base` — `/` (не влияет на локальную разработку, `npm run dev`).
 2. Скопировать содержимое `dist/` в `local/diagram-app/` внутри host-каталога, который смонтирован как `bitrix_www` (на текущем дев-стенде это `/home/nikit/bitrix/www/local/diagram-app/` — точный путь для конкретного стенда уточняется у того, кто его поднимал/администрирует).
-3. В PHP-классе (раздел 3): `$appUrl = $appOrigin . '/local/diagram-app/index.html';`, `$appOrigin` — origin портала (без пути).
-4. Обновление после правок в React-приложении — тот же `npm run build` + копирование поверх старых файлов. Пересборка/перезапуск контейнеров Bitrix не нужны.
+3. В PHP-классе (раздел 3): `$appUrl = $appOrigin . '/local/diagram-app/' . $actualIndexFileName;`, `$appOrigin` — origin портала (без пути), `$actualIndexFileName` — актуальное имя `index-<hash>.html` в `local/diagram-app/`, полученное способом на усмотрение бэкенда (см. врезку про кэш выше — хардкодить `index.html` строкой уже нельзя).
+4. Обновление после правок в React-приложении — тот же `npm run build` + копирование поверх старых файлов. Пересборка/перезапуск контейнеров Bitrix не нужны. Старый `index-<hash>.html` от предыдущей сборки при этом не удаляется автоматически — если способ поиска актуального файла (шаг 3) предполагает «взять единственный файл по маске», после нескольких деплоев в каталоге стоит убирать файлы прошлых версий, иначе маска перестанет быть однозначной.
 
 ### Вариант B — отдельный Docker-контейнер