szdl-utils-kit 0.3.23 → 0.3.25

package/Readme.md

@@ -97,11 +97,9 @@ const deals = await bx.batch({
 -   `appOption(key, value?)` – чтение/запись пользовательских настроек
 -   `call({ method, params, updateList })` – одиночный REST-вызов
 -   `batch(commandList, progressCall?, options?)` – пакетные вызовы с обновлениями/логом
--   `errorCall(errors)` – вызывается после выполнения всего батча, получает объект с ключами запросов и списком ошибок Bitrix24
--   `updateList` – массив описаний изменений для логера (`method`, `name`, `list[{ id, fields }]`), отображается в истории операций
+    -   `errorCall(errors)` – вызывается после выполнения всего батча, получает объект с ключами запросов и списком ошибок Bitrix24
+    -   `updateList` – массив описаний изменений для логера (`method`, `name`, `list[{ id, fields }]`), отображается в истории операций
 -   `batchTotalCount(commandList, progressCall?, options?)` – подсчет элементов в пакетном режиме
--   `errorCall(errors)` – вызывается после выполнения всего батча, получает объект с ключами запросов и списком ошибок Bitrix24
--   `updateList` – массив описаний изменений для логера (`method`, `name`, `list[{ id, fields }]`), отображается в истории операций
 -   `timeLimit` – глобальный статус лимита выполнения (`{ limit, date }`), можно напрямую читать в компонентах (например, в лоадере)
 -   `placementBind(place, userId?)`, `placementUnBind(...)`, `placementCheck()` – работа с встройками (кроме `PAGE_BACKGROUND_WORKER`, их ведёт `BackgroundWorker`)
 -   `getBotList()`, `regBot()`, `unRegBot()` – управление чат-ботом
@@ -187,7 +185,9 @@ await worker.init();
 -   `bx` – инициализированный экземпляр `BxBoot`, используемый для работы с REST;
 -   `appFunc` – функция, которая должна выполниться в «активном» табе;
 -   `users` – подготовленные данные (если не переданы, будут запрошены через REST);
--   `continueBackground` – опциональная функция-условие (`(worker) => boolean | Promise<boolean)`), которая определяет, можно ли запускать воркер. Должна вернуть `true`, чтобы продолжить цикл. По умолчанию всегда возвращает `true`.
+-   `continueBackground` – опциональная функция-условие, которая определяет, можно ли запускать воркер. Должна вернуть `true`, чтобы продолжить цикл. По умолчанию всегда возвращает `true`; см. пример ниже.
+-   `timing` – объект с таймингами poll-цикла, подтверждения лидерства и разнесённого старта приложений (см. [Тайминги](#тайминги-timing)). Можно передать только нужные поля — остальные возьмутся из `DEFAULT_BACKGROUND_WORKER_TIMING`;
+-   `coordinationScope` – область координации лидера и пула вкладок (см. [Область координации](#область-координации-coordinationscope)). По умолчанию `'user'`.
 
 ```ts
 const worker = new BackgroundWorker({
@@ -206,6 +206,111 @@ const worker = new BackgroundWorker({
 });
 ```
 
+#### Область координации (`coordinationScope`)
+
+Передаётся строкой: `'user'` или `'portal'`. Другие значения игнорируются с предупреждением в консоль, используется `'user'`.
+
+| Значение | Поведение |
+|----------|-----------|
+| `'user'` (по умолчанию) | Один запуск `appFunc` одновременно **на пользователя**. Вкладки разных пользователей не конкурируют. |
+| `'portal'` | Один запуск `appFunc` одновременно **на портал**. Все пользователи в общем пуле вкладок; лидер один на всё приложение. |
+
+**Как это работает:**
+
+- В режиме `'user'` записи в entity хранятся с `NAME = userId`, Web Lock тоже per-user.
+- В режиме `'portal'` все вкладки пишутся с общим ключом `NAME = {appCodeName}:portal`, Web Lock — per-portal (per-app).
+- В данных вкладки всегда сохраняется `userId` — в portal-режиме видно, у кого открыта вкладка, хотя `appFunc` выполняется только у лидера.
+- `setBackgroundWorkerAll` в portal-режиме привязывает только общую встройку `PAGE_BACKGROUND_WORKER` и отвязывает персональные (`USER_ID=…`).
+
+```ts
+const worker = new BackgroundWorker({
+	bx,
+	appFunc: async () => {
+		console.log("background job started (once per portal)");
+	},
+	coordinationScope: "portal",
+});
+await worker.init();
+```
+
+#### Тайминги (`timing`)
+
+Экспортируются `DEFAULT_BACKGROUND_WORKER_TIMING` и `resolveBackgroundWorkerTiming` — удобно собирать конфиг заранее или переопределять отдельные поля.
+
+```ts
+import {
+	BackgroundWorker,
+	DEFAULT_BACKGROUND_WORKER_TIMING,
+	resolveBackgroundWorkerTiming,
+} from "szdl-utils-kit";
+
+const timing = resolveBackgroundWorkerTiming({
+	startDelayMs: 10_000,
+	leaderConfirmDelayMs: 10_000,
+});
+
+const worker = new BackgroundWorker({ bx, appFunc, timing });
+```
+
+**Поля объекта `timing`:**
+
+| Поле | По умолчанию | Назначение |
+|------|--------------|------------|
+| `startDelayMs` | `0` | Пауза перед первым poll-тиком. Разносит старт разных приложений (один апп — через 20 с, другой — через 4–5 мин). |
+| `pollIntervalMs` | `60_000` | Базовый интервал фонового poll-цикла (обновление `lastActive`, выбор лидера, очистка мёртвых вкладок). |
+| `pollIntervalJitterMs` | `30_000` | Случайная добавка к `pollIntervalMs`. Итоговый интервал: от `pollIntervalMs` до `pollIntervalMs + pollIntervalJitterMs` (по умолчанию 1–1,5 мин). |
+| `leaderConfirmDelayMs` | `60_000` | Пауза после захвата Web Lock перед повторной проверкой лидерства и вызовом `appFunc`. Защита от гонки между вкладками. |
+| `activeMaxPauseMs` | `180_000` | Порог «мёртвой» вкладки: если `lastActive` не обновлялся дольше — запись удаляется из entity. Должен быть **больше** `startDelayMs + leaderConfirmDelayMs`, иначе вкладка может удалиться во время пауз перед стартом. |
+| `quickCleanupThresholdMs` | `300_000` | Отдельный порог для агрессивной очистки, когда достигнут лимит вкладок (`maxTabs`). |
+| `leaderHeartbeatMs` | `null` | Интервал обновления `lastActive` лидером во время `appFunc`. Если не задан — вычисляется автоматически из `pollInterval` и `activeMaxPauseMs`. |
+
+**Как устроен старт (без лишних раундов):**
+
+1. Регистрация вкладки в entity.
+2. Пауза `startDelayMs` (если задана).
+3. Poll-тик: выбор лидера по entity (самая старая вкладка).
+4. Если текущая вкладка — лидер: захват Web Lock → пауза `leaderConfirmDelayMs` → повторная проверка лидера → `appFunc`.
+5. Далее poll-цикл продолжается с интервалом `pollIntervalMs` … `+ pollIntervalJitterMs`.
+
+**Пример: старт через ~20 секунд**
+
+```ts
+const START_DELAY_MS = 10_000;
+const LEADER_CONFIRM_MS = 10_000;
+
+const worker = new BackgroundWorker({
+	bx,
+	appFunc: async () => {
+		console.log("background job started");
+	},
+	timing: {
+		...DEFAULT_BACKGROUND_WORKER_TIMING,
+		startDelayMs: START_DELAY_MS,
+		leaderConfirmDelayMs: LEADER_CONFIRM_MS,
+		activeMaxPauseMs: Math.max(
+			60_000,
+			(START_DELAY_MS + LEADER_CONFIRM_MS) * 3,
+		),
+	},
+});
+```
+
+**Пример: отложенный старт (~4–5 минут)**
+
+```ts
+const worker = new BackgroundWorker({
+	bx,
+	appFunc: async () => {
+		/* ... */
+	},
+	timing: {
+		...DEFAULT_BACKGROUND_WORKER_TIMING,
+		startDelayMs: 4 * 60_000,
+		leaderConfirmDelayMs: 60_000,
+	},
+});
+```
+
 Методы:
 
 -   **`init`** – регистрирует бек-встройку для текущего пользователя, создаёт запись текущего таба и запускает цикл наблюдения.
@@ -227,7 +332,7 @@ const formatted = tempus().format("%Y-%m-%d");
 
 -   `types/batch.d.ts` – детальное описание Batch;
 -   `types/bx-boot.d.ts`, `types/bx-helper.d.ts`, `types/bx-logger.d.ts`;
--   `types/background-worker.d.ts`.
+-   `types/background-worker.d.ts` – в том числе `BackgroundWorkerTiming`, `DEFAULT_BACKGROUND_WORKER_TIMING`.
 
 ## Разработка и публикация