@alizadefaig/pos-server 1.2.25 → 1.2.27

package/app/db/migrations/005_printers.sql

@@ -0,0 +1,43 @@
+-- Принтеры для офлайн-печати (sendToWorkshops / printBillReceipt в ядре).
+-- Наполняет их синк снапшота, как и остальные справочники: печать решает, КУДА слать чек
+-- (терминал + физический принтер), а сама печать остаётся на терминале через сокет.
+-- Колонки повторяют Postgres-схему Laravel один в один — синк копирует строки
+-- по пересечению колонок, без маппинга.
+
+CREATE TABLE IF NOT EXISTS printers (
+    id          TEXT PRIMARY KEY,
+    name        TEXT,
+    -- usb | lan: по типу терминал выбирает транспорт
+    type        TEXT,
+    ip_address  TEXT,
+    vendor_id   TEXT,
+    product_id  TEXT,
+    -- терминал, к которому физически подключён принтер (на него уходит сокет-запрос)
+    terminal_id TEXT,
+    team_id     TEXT,
+    company_id  TEXT,
+    -- принтер счёта (чек гостю); цеховые принтеры идут через printer_workshop
+    bill        INTEGER DEFAULT 0,
+    bell        INTEGER DEFAULT 1,
+    -- открыть денежный ящик при печати оплаченного счёта (на пречеке — никогда)
+    cashdraw    INTEGER DEFAULT 0,
+    deleted_at  TEXT,
+    created_at  TEXT,
+    updated_at  TEXT,
+    synced_at   TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_printers_terminal ON printers (terminal_id);
+
+-- Какие цеха печатает принтер. Своего id и timestamps у связи в Laravel нет; уникальности
+-- тоже нет — повторы в облаке возможны, и локально они должны вести себя так же (два задания).
+CREATE TABLE IF NOT EXISTS printer_workshop (
+    printer_id          TEXT NOT NULL,
+    product_workshop_id TEXT NOT NULL,
+    -- выключенная связь хранится, но цеховой чек на этот принтер не уходит
+    print_ticket        INTEGER DEFAULT 0,
+    synced_at           TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_printer_workshop_printer ON printer_workshop (printer_id);
+CREATE INDEX IF NOT EXISTS idx_printer_workshop_workshop ON printer_workshop (product_workshop_id);

package/app/db/migrations/006_sync.sql

@@ -0,0 +1,136 @@
+-- Синк локального Node с облаком (OFFLINE-FIRST-PLAN §11, модель F).
+--
+-- Облако — основная система, локальная БД — зеркало на случай обрыва связи. Всё, что касса
+-- изменила сама (офлайн), помечается «грязным» и уезжает наверх агрегатом чека; пока пометка
+-- висит, зеркало этот чек не перезаписывает — иначе офлайн-правки затёр бы старый облачный снимок.
+
+-- Мелкое состояние синка: сессия терминала, курсор зеркала, blob ответа app.init, времена.
+CREATE TABLE IF NOT EXISTS kv (
+    key        TEXT PRIMARY KEY,
+    value      TEXT,
+    updated_at TEXT
+);
+
+-- Что изменено локально и ещё не подтверждено облаком. version растёт на каждой записи:
+-- пометку снимаем, только если после отправки её никто не трогал (DELETE ... AND version = ?),
+-- поэтому правка, прилетевшая во время push, не потеряется.
+CREATE TABLE IF NOT EXISTS sync_dirty (
+    entity   TEXT NOT NULL,              -- 'order' | 'shift'
+    id       TEXT NOT NULL,
+    version  INTEGER NOT NULL DEFAULT 1,
+    dirty_at TEXT,
+    PRIMARY KEY (entity, id)
+);
+
+-- Пока здесь есть строка, триггеры молчат: так зеркало пишет облачные данные, не помечая их
+-- грязными. Ставится и снимается внутри одного синхронного блока (см. app/sync/mirror.js),
+-- поэтому запись ядра в этот момент вклиниться не может.
+CREATE TABLE IF NOT EXISTS sync_suppress (
+    id INTEGER PRIMARY KEY CHECK (id = 1)
+);
+
+-- Язык команды: в облаке это teams.language_id → languages.code (см. Context::resolveLocale).
+-- Снапшот кладёт обе таблицы как есть, language_code выводится при применении снапшота.
+CREATE TABLE IF NOT EXISTS languages (
+    id        TEXT PRIMARY KEY,
+    code      TEXT,
+    name      TEXT,
+    synced_at TEXT
+);
+
+ALTER TABLE teams ADD COLUMN language_id TEXT;
+ALTER TABLE teams ADD COLUMN user_id TEXT;
+
+-- Офлайн-вход по PIN / карте: ищем сотрудника в ответе app.init, но смену (cash/work) ищем
+-- по team_users/shifts — колонки нужны для этого поиска и для паритета со снапшотом.
+ALTER TABLE team_users ADD COLUMN pin TEXT;
+ALTER TABLE team_users ADD COLUMN ic_card TEXT;
+ALTER TABLE team_users ADD COLUMN deleted_at TEXT;
+
+-- ------------------------------------------------------------------ триггеры грязных чеков
+
+-- Одна и та же вставка для всех триггеров: пометить чек (или смену) и поднять версию.
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_orders_ins AFTER INSERT ON orders
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_orders_upd AFTER UPDATE ON orders
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_order_products_ins AFTER INSERT ON order_products
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+-- merge/transfer переносят позицию в другой чек (UPDATE order_id): грязными становятся оба —
+-- исходный теряет позицию, целевой её получает.
+CREATE TRIGGER IF NOT EXISTS sync_dirty_order_products_upd AFTER UPDATE ON order_products
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', OLD.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+-- У модификатора нет order_id — чек находим через позицию.
+CREATE TRIGGER IF NOT EXISTS sync_dirty_opms_ins AFTER INSERT ON order_product_modifier_sets
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at)
+    SELECT 'order', op.order_id, 1, datetime('now') FROM order_products op WHERE op.id = NEW.order_product_id
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_opms_upd AFTER UPDATE ON order_product_modifier_sets
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at)
+    SELECT 'order', op.order_id, 1, datetime('now') FROM order_products op WHERE op.id = NEW.order_product_id
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_order_payments_ins AFTER INSERT ON order_payments
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_order_payments_upd AFTER UPDATE ON order_payments
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_order_events_ins AFTER INSERT ON order_events
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress) AND NEW.order_id IS NOT NULL
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_shifts_ins AFTER INSERT ON shifts
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('shift', NEW.id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_shifts_upd AFTER UPDATE ON shifts
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('shift', NEW.id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;

package/app/db/migrations/007_printer_mac.sql

@@ -0,0 +1,4 @@
+-- MAC сетевого принтера (привязка по MAC, фронт с VITE_PRINTER_MAC): колонка как в Laravel
+-- (миграция add_mac_address_to_printers_table). Снапшот копирует её вместе с остальными, а печать
+-- ядра отдаёт терминалу в payload принтера — локальный Node находит принтер, сменивший IP.
+ALTER TABLE printers ADD COLUMN mac_address TEXT;

package/app/db/migrations/008_kds.sql

@@ -0,0 +1,94 @@
+-- KDS (кухонный экран) и экран готовности без облака: порт KdsService из Laravel.
+--
+-- Тикеты создаёт ядро в момент отправки в цех (PrintService.sendToWorkshops), статусы ведёт
+-- KDS-терминал, при закрытии/удалении чека тикеты гасятся (soft delete). Колонки повторяют
+-- Postgres-схему Laravel один в один — в облачном контуре ядро пишет в те же таблицы.
+
+CREATE TABLE IF NOT EXISTS kds_tickets (
+    id                  TEXT PRIMARY KEY,
+    company_id          TEXT,
+    team_id             TEXT,
+    order_id            TEXT,
+    product_workshop_id TEXT,
+    -- порядковый номер отправки в рамках чека; удалённые тикеты номера не освобождают
+    number              INTEGER DEFAULT 1,
+    -- waiting | cooking | ready
+    status              TEXT DEFAULT 'waiting',
+    -- 0 — цех без KDS-терминала: тикет сразу «готов» и готовность чека не держит
+    tracked             INTEGER DEFAULT 1,
+    fired_at            TEXT,
+    ready_at            TEXT,
+    deleted_at          TEXT,
+    created_at          TEXT,
+    updated_at          TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_kds_tickets_order ON kds_tickets (order_id);
+CREATE INDEX IF NOT EXISTS idx_kds_tickets_company_workshop ON kds_tickets (company_id, product_workshop_id);
+
+CREATE TABLE IF NOT EXISTS kds_ticket_items (
+    id                 TEXT PRIMARY KEY,
+    kds_ticket_id      TEXT,
+    order_product_id   TEXT,
+    product_id         TEXT,
+    -- снимок названия на момент отправки
+    name               TEXT,
+    quantity           REAL DEFAULT 1,
+    -- позицию убавили/удалили после отправки: сколько из quantity отменено
+    cancelled_quantity REAL DEFAULT 0,
+    comment            TEXT,
+    status             TEXT DEFAULT 'waiting',
+    ready_at           TEXT,
+    cancelled_at       TEXT,
+    created_at         TEXT,
+    updated_at         TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_kds_ticket_items_ticket ON kds_ticket_items (kds_ticket_id);
+CREATE INDEX IF NOT EXISTS idx_kds_ticket_items_order_product ON kds_ticket_items (order_product_id);
+
+-- Какие цеха показывает KDS-терминал. Как и printer_workshop, своего id у связи нет;
+-- наполняет её снапшот (Laravel уже отдаёт terminal_workshop по терминалам заведения).
+CREATE TABLE IF NOT EXISTS terminal_workshop (
+    terminal_id         TEXT NOT NULL,
+    product_workshop_id TEXT NOT NULL,
+    synced_at           TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_terminal_workshop_terminal ON terminal_workshop (terminal_id);
+CREATE INDEX IF NOT EXISTS idx_terminal_workshop_workshop ON terminal_workshop (product_workshop_id);
+
+-- ------------------------------------------------------------------ триггеры грязных чеков
+
+-- Тикеты едут наверх в агрегате своего чека (как позиции и платежи), поэтому их правка
+-- помечает грязным сам чек. Зеркало пишет их под sync_suppress — тогда триггеры молчат.
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_kds_tickets_ins AFTER INSERT ON kds_tickets
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_kds_tickets_upd AFTER UPDATE ON kds_tickets
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('order', NEW.order_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_kds_ticket_items_ins AFTER INSERT ON kds_ticket_items
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at)
+    SELECT 'order', t.order_id, 1, datetime('now') FROM kds_tickets t WHERE t.id = NEW.kds_ticket_id
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_kds_ticket_items_upd AFTER UPDATE ON kds_ticket_items
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at)
+    SELECT 'order', t.order_id, 1, datetime('now') FROM kds_tickets t WHERE t.id = NEW.kds_ticket_id
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;

package/app/db/migrations/009_product_categories.sql

@@ -0,0 +1,20 @@
+-- Категории товаров — для отчёта кассы (reports.getReport, разбивка by_category) без облака.
+-- Облако шлёт их в снапшоте давно (SyncService::snapshotTables), но без локальной таблицы
+-- applyTables их пропускал. Только живые строки: надгробий у категорий в снапшоте нет,
+-- deleted_at оставлен ради одинаковых запросов с Postgres.
+
+CREATE TABLE IF NOT EXISTS product_categories (
+    id          TEXT PRIMARY KEY,
+    team_id     TEXT,
+    name        TEXT,
+    description TEXT,
+    slug        TEXT,
+    parent_id   TEXT,
+    "order"     INTEGER DEFAULT 0,
+    color       TEXT,
+    image       TEXT,
+    deleted_at  TEXT,
+    synced_at   TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_product_categories_team ON product_categories (team_id);

package/app/db/migrations/010_printers_sync.sql

@@ -0,0 +1,43 @@
+-- Настройка принтеров без облака (printers.update / delete / syncAddress в ядре).
+--
+-- Правка принтера на кассе помечает его грязным — push везёт строку принтера вместе с его
+-- цехами (printer_workshop) в облако. Снапшот грязный принтер не перезаписывает, пока push
+-- его не доставил. Снапшот и зеркало пишут под sync_suppress — триггеры молчат.
+--
+-- Сущность — 'printer', id — printers.id. Связки printer_workshop своего id не имеют,
+-- поэтому помечают своего принтера.
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_printers_ins AFTER INSERT ON printers
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('printer', NEW.id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_printers_upd AFTER UPDATE ON printers
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('printer', NEW.id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_printer_workshop_ins AFTER INSERT ON printer_workshop
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('printer', NEW.printer_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_printer_workshop_upd AFTER UPDATE ON printer_workshop
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('printer', NEW.printer_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;
+
+CREATE TRIGGER IF NOT EXISTS sync_dirty_printer_workshop_del AFTER DELETE ON printer_workshop
+WHEN NOT EXISTS (SELECT 1 FROM sync_suppress)
+BEGIN
+    INSERT INTO sync_dirty (entity, id, version, dirty_at) VALUES ('printer', OLD.printer_id, 1, datetime('now'))
+    ON CONFLICT (entity, id) DO UPDATE SET version = version + 1, dirty_at = excluded.dirty_at;
+END;

package/app/db/migrations/011_team_logos.sql

@@ -0,0 +1,13 @@
+-- Логотип команды для счёта (orders.printBillReceipt). Laravel читает его из своего Storage
+-- (ImageService::toBase64), у кассы туда доступа нет — копию привозит снапшот ключом team_logo.
+--
+-- Это не таблица справочника: снапшот заменяет справочники целиком, а облако повторно логотип
+-- не шлёт, пока у кассы та же картинка (image_id). Поэтому своя таблица, которую пишет только
+-- snapshot.js::applyTeamLogo.
+
+CREATE TABLE IF NOT EXISTS team_logos (
+    team_id    TEXT PRIMARY KEY,
+    image_id   TEXT,
+    data       TEXT,
+    updated_at TEXT
+);

package/app/db/migrations/012_category_workshop.sql

@@ -0,0 +1,4 @@
+-- Цех категории: мутатор Product::productWorkshopId берёт его, когда у товара свой цех пуст.
+-- Без колонки касса не отправляла такие позиции на кухню (ни бумага, ни KDS). Снапшот шлёт
+-- product_categories целиком и заполнит колонку при первой же синхронизации.
+ALTER TABLE product_categories ADD COLUMN product_workshop_id TEXT;

package/app/monitor.js

@@ -0,0 +1,185 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {performance} = require('node:perf_hooks');
+
+/**
+ * Самочувствие кассы для суперадминки (OFFLINE-FIRST-PLAN §12.8, P2): задержка event loop,
+ * память, итоги печати, размер локальной БД и свободное место на диске.
+ *
+ * В облако уходит внутри heartbeat синка (sync.mode → terminals.sync_status.monitor), поэтому
+ * отправляется только там, где синк включён. OFFLINE_MONITOR=false — поле не отправляется,
+ * сэмплер не заводится. Счётчики печати копятся всегда: это пара чисел в памяти.
+ *
+ * Задержка event loop — дрейф собственного таймера, а не perf_hooks.monitorEventLoopDelay:
+ * тот после reset() теряет замер, пересекающий сброс, а сброс делает сам heartbeat — то есть
+ * блокировки внутри цикла синка выпадали бы из окна систематически.
+ */
+const enabled = () => (process.env.OFFLINE_MONITOR || 'true').toLowerCase() !== 'false';
+
+const MB = 1024 * 1024;
+
+// шаг сэмплера — он же погрешность: блокировку таймер видит заниженной не больше чем на шаг
+const SAMPLE_MS = 20;
+// больше — это сон/гибернация машины, а не блокировка потока
+const SUSPEND_MS = 30000;
+const MAX_SAMPLES = 4096;
+
+let sampler = null;
+let expectedAt = 0;
+let windowStartedAt = Date.now();
+const lag = {count: 0, sum: 0, max: 0, samples: []};
+
+const print = {
+    ok: 0,
+    // честная печать (PRINT_HONEST_ACK) без подтверждения от LAN-принтера
+    unconfirmed: 0,
+    failed: 0,
+    errors: {},
+    last_ok_at: null,
+    last_error: null,
+    last_error_at: null,
+};
+
+const nowIso = () => new Date().toISOString();
+
+const resetLag = () => {
+    lag.count = 0;
+    lag.sum = 0;
+    lag.max = 0;
+    lag.samples = [];
+    windowStartedAt = Date.now();
+};
+
+/** Таймер срабатывает на SAMPLE_MS позже прошлого запуска; всё сверх этого — задержка потока. */
+const sample = () => {
+    const now = performance.now();
+    const delay = Math.max(0, now - expectedAt);
+    expectedAt = now + SAMPLE_MS;
+    if (delay > SUSPEND_MS) {
+        return;
+    }
+    lag.count += 1;
+    lag.sum += delay;
+    lag.max = Math.max(lag.max, delay);
+    // окно без heartbeat (облако недоступно) растёт сколько угодно — для p99 держим выборку
+    if (lag.samples.length < MAX_SAMPLES) {
+        lag.samples.push(delay);
+    } else {
+        const slot = Math.floor(Math.random() * lag.count);
+        if (slot < MAX_SAMPLES) {
+            lag.samples[slot] = delay;
+        }
+    }
+};
+
+const ensureSampler = () => {
+    if (!sampler) {
+        expectedAt = performance.now() + SAMPLE_MS;
+        sampler = setInterval(sample, SAMPLE_MS);
+        sampler.unref();
+        resetLag();
+    }
+};
+
+const percentile = (values, p) => {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1)];
+};
+
+/** Итог /printers.print (тело ответа терминалу). Моки APP_DEBUG не считаем. */
+const recordPrint = (body) => {
+    if (!body || typeof body !== 'object' || body.mock) {
+        return;
+    }
+    if (body.success) {
+        if (body.confirmed === false) {
+            print.unconfirmed += 1;
+        } else {
+            print.ok += 1;
+        }
+        print.last_ok_at = nowIso();
+        return;
+    }
+    const code = typeof body.error === 'string' && body.error ? body.error.slice(0, 40) : 'unknown';
+    print.failed += 1;
+    print.errors[code] = (print.errors[code] || 0) + 1;
+    print.last_error = code;
+    print.last_error_at = nowIso();
+};
+
+const round = (value, digits = 1) => {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+};
+
+const fileSize = (file) => {
+    try {
+        return fs.statSync(file).size;
+    } catch (e) {
+        return 0;
+    }
+};
+
+/** Размер SQLite вместе с WAL и свободное место на её диске. */
+const disk = (dbFile) => {
+    if (!dbFile) {
+        return {db_mb: null, disk_free_mb: null};
+    }
+    const bytes = fileSize(dbFile) + fileSize(`${dbFile}-wal`);
+    let free = null;
+    if (typeof fs.statfsSync === 'function') {
+        try {
+            const stats = fs.statfsSync(path.dirname(dbFile));
+            free = Math.round((Number(stats.bavail) * Number(stats.bsize)) / MB);
+        } catch (e) {
+            free = null;
+        }
+    }
+    return {db_mb: round(bytes / MB), disk_free_mb: free};
+};
+
+/**
+ * Снимок для heartbeat. Задержка event loop — за окно с прошлого снимка (reset: true сбрасывает
+ * окно; /local/status смотрит без сброса). null — мониторинг выключен; loop: null — в окне
+ * ещё не было замеров.
+ */
+const snapshot = ({dbFile = null, reset = true} = {}) => {
+    if (!enabled()) {
+        return null;
+    }
+    ensureSampler();
+    const memory = process.memoryUsage();
+    const loop = lag.count > 0 ? {
+        p99_ms: round(percentile(lag.samples, 99)),
+        max_ms: round(lag.max),
+        mean_ms: round(lag.sum / lag.count),
+        window_s: Math.round((Date.now() - windowStartedAt) / 1000),
+    } : null;
+    if (reset) {
+        resetLag();
+    }
+    return {
+        uptime_s: Math.round(process.uptime()),
+        rss_mb: Math.round(memory.rss / MB),
+        heap_mb: Math.round(memory.heapUsed / MB),
+        loop,
+        print: {...print, errors: {...print.errors}},
+        ...disk(dbFile),
+    };
+};
+
+/** Запуск сэмплера заранее, чтобы первый heartbeat пришёл уже с окном. */
+const start = () => {
+    if (enabled()) {
+        ensureSampler();
+    }
+};
+
+const stop = () => {
+    if (sampler) {
+        clearInterval(sampler);
+        sampler = null;
+    }
+};
+
+module.exports = {enabled, start, stop, snapshot, recordPrint};