@alizadefaig/pos-server 1.2.25 → 1.2.27

package/app/core/idempotency.js

@@ -0,0 +1,196 @@
+const moment = require('moment');
+
+const {HttpError} = require('./errors');
+const {nowSql, SQL_FORMAT, now} = require('./support/time');
+
+/**
+ * Exactly-once для мутаций ядра — порт App\Http\Middleware\IdempotencyMiddleware (БАГ A).
+ *
+ * Зачем дубль логики на JS: в облаке событие, забранное ядром, до Laravel не доходит, а
+ * значит и до его middleware. Без этой проверки один жест кассы (сокет + HTTP-fallback,
+ * реплей буфера при reconnect, ретрай оператора) снова добавлял бы позицию дважды.
+ *
+ * Таблица та же — `idempotency_keys`, и формат хранимого ответа тот же (JSON тела ответа).
+ * Поэтому событие можно возить туда-сюда между Laravel и Node на одном ключе: кто первый
+ * захватил, тот и выполнил, второй канал получит сохранённый ответ независимо от того,
+ * какая из двух реализаций его записала.
+ *
+ * Модель захвата — как в PHP: лёгкий atomic INSERT без удержания транзакции на время
+ * обработчика (иначе конкурентный дубль блокировался бы на всё время внешнего I/O).
+ */
+const flag = (name, fallback) => (process.env[name] ?? fallback);
+
+const isEnabled = () => flag('CORE_IDEMPOTENCY', 'true') === 'true';
+
+const config = () => ({
+    ttlHours: Number(flag('IDEMPOTENCY_TTL_HOURS', 24)),
+    waitMs: Number(flag('IDEMPOTENCY_WAIT_MS', 2500)),
+    waitStepMs: Math.max(50, Number(flag('IDEMPOTENCY_WAIT_STEP_MS', 150))),
+    stalePendingSeconds: Number(flag('IDEMPOTENCY_STALE_PENDING_SECONDS', 190)),
+});
+
+const MAX_KEY_LENGTH = 64;
+
+/** Ключ жеста: заголовок Idempotency-Key либо operation_id в теле — как у Laravel. */
+const resolveKey = (value) => {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const key = value.trim();
+    if (!key || key.length > MAX_KEY_LENGTH) {
+        return null;
+    }
+    return key;
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+class Idempotency {
+    constructor(db) {
+        this.db = db;
+        this.config = config();
+    }
+
+    /**
+     * Захват ключа. true — мы владельцы и обязаны выполнить операцию ровно один раз.
+     * false — ключ уже занят: операция выполняется или выполнена другим каналом.
+     *
+     * Вместо ловли ошибки уникальности используем ON CONFLICT/OR IGNORE: разбор кодов
+     * ошибок у pg и node:sqlite разный, а результат нужен один — вставили или нет.
+     */
+    async claim(key, {companyId = null, event = null} = {}) {
+        if (await this.insertPending(key, companyId, event)) {
+            return true;
+        }
+
+        // Занято. Если pending остался от умершего процесса — перезахватываем.
+        const row = await this.find(key);
+        if (row && row.status === 'pending' && this.isStale(row)) {
+            return this.reclaimStale(key, companyId, event);
+        }
+        return false;
+    }
+
+    /**
+     * Дубль: отдаём сохранённый ответ, если первый уже закончил, иначе коротко ждём его.
+     * Ждать долго нельзя (печать держит операцию до двух минут) → 409 с маркером
+     * in_progress: фронт по нему не шумит ошибкой и повторит с тем же ключом.
+     */
+    async replay(key) {
+        const row = (await this.find(key)) || null;
+        const done = row && row.status === 'done' ? row : await this.pollDone(key);
+
+        if (done) {
+            return {replayed: true, result: this.decode(done.response)};
+        }
+
+        throw new HttpError(409, {message: 'Operation in progress', in_progress: true});
+    }
+
+    async markDone(key, result) {
+        await this.db.run(
+            `UPDATE idempotency_keys
+                SET status = 'done', http_status = 200, response = ?, updated_at = ?
+              WHERE operation_id = ?`,
+            [JSON.stringify(result === undefined ? null : result), nowSql(), key]
+        );
+    }
+
+    /** Ошибка не кэшируется: честный повтор жеста должен выполниться заново. */
+    async release(key) {
+        await this.db.run('DELETE FROM idempotency_keys WHERE operation_id = ?', [key]);
+    }
+
+    /** Локальному мастеру чистить некому — в облаке это делает команда Laravel. */
+    async cleanup(limit = 1000) {
+        const result = await this.db.run(
+            `DELETE FROM idempotency_keys
+              WHERE operation_id IN (
+                    SELECT operation_id FROM idempotency_keys WHERE expires_at < ? LIMIT ?
+              )`,
+            [nowSql(), limit]
+        );
+        return result?.changes ?? 0;
+    }
+
+    /* ------------------------------------------------------------------ */
+
+    async insertPending(key, companyId, event) {
+        const timestamp = nowSql();
+        const expires = moment.utc(now()).add(this.config.ttlHours, 'hours').format(SQL_FORMAT);
+        const columns = '(operation_id, company_id, event, status, created_at, updated_at, expires_at)';
+        const values = [key, companyId, event, 'pending', timestamp, timestamp, expires];
+
+        const sql = this.db.dialect === 'sqlite'
+            ? `INSERT OR IGNORE INTO idempotency_keys ${columns} VALUES (?, ?, ?, ?, ?, ?, ?)`
+            : `INSERT INTO idempotency_keys ${columns} VALUES (?, ?, ?, ?, ?, ?, ?)
+               ON CONFLICT (operation_id) DO NOTHING`;
+
+        const result = await this.db.run(sql, values);
+        return (result?.changes ?? 0) > 0;
+    }
+
+    /** Удалить брошенный pending и вставить свой — владеет только победитель гонки. */
+    async reclaimStale(key, companyId, event) {
+        const staleBefore = moment.utc(now())
+            .subtract(this.config.stalePendingSeconds, 'seconds')
+            .format(SQL_FORMAT);
+
+        return this.db.transaction(async (tx) => {
+            const deleted = await tx.run(
+                `DELETE FROM idempotency_keys
+                  WHERE operation_id = ? AND status = 'pending' AND created_at < ?`,
+                [key, staleBefore]
+            );
+            if ((deleted?.changes ?? 0) === 0) {
+                return false; // кто-то опередил с перезахватом или уже завершил
+            }
+            const scoped = new Idempotency(tx);
+            return scoped.insertPending(key, companyId, event);
+        });
+    }
+
+    async pollDone(key) {
+        let waited = 0;
+        while (waited < this.config.waitMs) {
+            await sleep(this.config.waitStepMs);
+            waited += this.config.waitStepMs;
+
+            const row = await this.find(key);
+            if (!row) {
+                return null; // первый освободил ключ из-за ошибки → повтор выполнит заново
+            }
+            if (row.status === 'done') {
+                return row;
+            }
+        }
+        return null;
+    }
+
+    find(key) {
+        return this.db.get('SELECT * FROM idempotency_keys WHERE operation_id = ?', [key]);
+    }
+
+    isStale(row) {
+        if (!row.created_at) {
+            return false;
+        }
+        const created = moment.utc(row.created_at, [SQL_FORMAT, moment.ISO_8601]);
+        return created.isValid()
+            && created.valueOf() < now().getTime() - this.config.stalePendingSeconds * 1000;
+    }
+
+    decode(response) {
+        if (response === null || response === undefined || response === '') {
+            return null;
+        }
+        try {
+            return JSON.parse(response);
+        } catch (e) {
+            // Ответ записан Laravel и почему-то не JSON — вернуть как есть честнее, чем упасть.
+            return response;
+        }
+    }
+}
+
+module.exports = {Idempotency, isEnabled, resolveKey};

package/app/core/index.js

@@ -0,0 +1,374 @@
+const {getDatabase, Database} = require('../db/Database');
+const Context = require('./Context');
+const SocketEmitter = require('./emitter');
+const OrderService = require('./services/OrderService');
+const OrderProductService = require('./services/OrderProductService');
+const OutboxRepository = require('./repositories/OutboxRepository');
+const {Idempotency, isEnabled: idempotencyEnabled, resolveKey} = require('./idempotency');
+const {HttpError} = require('./errors');
+const syncConfig = require('../sync/config');
+const auth = require('./auth');
+
+/**
+ * Точка входа ядра — POS-API, перенесённый с PHP на JS.
+ *
+ * Один и тот же код работает в двух контурах (см. app/db/driver.js):
+ *   CORE_MODE=cloud — облако, общая с Laravel Postgres-база. Laravel остаётся рядом как откат,
+ *                     Node забирает события постепенно (список CORE_EVENTS).
+ *   CORE_MODE=local — локальный мастер: одна касса держит SQLite, остальные терминалы ходят
+ *                     к ней; мутации дублируются в outbox для досылки наверх.
+ * По умолчанию режим выводится из диалекта БД, отдельно его задавать не нужно.
+ *
+ * Флаг OFFLINE_CORE по умолчанию ВЫКЛЮЧЕН: тогда роут делает next(), запрос доходит до прокси
+ * и уезжает в Laravel — сервер ведёт себя ровно как сегодня.
+ *
+ * Регистрация событий живёт в routes/common/api/*.js — здесь только реестр и исполнение,
+ * общие для двух транспортов: HTTP (express) и socket.io (`api:request`, горячий путь фронта).
+ */
+const isEnabled = () => (process.env.OFFLINE_CORE ?? 'false') === 'true';
+
+const mode = () => {
+    const value = (process.env.CORE_MODE || '').toLowerCase();
+    if (value === 'cloud' || value === 'local') {
+        return value;
+    }
+    return Database.defaultDialect() === 'sqlite' ? 'local' : 'cloud';
+};
+
+/**
+ * Поэтапный перевод: CORE_EVENTS — список событий, которые ядру разрешено обслуживать
+ * («orders.getById,orders.archive»). Пусто = все зарегистрированные. Всё остальное уходит
+ * в Laravel как раньше, поэтому откат любого события — это правка одной переменной.
+ */
+let allowCache = {raw: null, set: null};
+const allowed = (event) => {
+    const raw = process.env.CORE_EVENTS || '';
+    if (!raw.trim()) {
+        return true;
+    }
+    if (allowCache.raw !== raw) {
+        allowCache = {
+            raw,
+            set: new Set(raw.split(',').map((item) => item.trim()).filter(Boolean)),
+        };
+    }
+    return allowCache.set.has(event);
+};
+
+/**
+ * event → {mutation, localOnly, followerLocal, cloudOnly, isPublic, action}. Заполняется при
+ * загрузке роутов. isPublic — событие без проверки токена (вход по логину: у Laravel это отдельный
+ * роут `app.auth` без middleware).
+ */
+const registry = new Map();
+
+/**
+ * Пути, которые ядро обслуживает локально. Нужны server.js: только у локальных роутов тело
+ * можно парсить (см. комментарий к LOCAL_BODY_ROUTES) — проксируемые обязаны идти сырым потоком.
+ */
+const registeredPaths = new Map(); // path → event
+
+/**
+ * Модель F (OFFLINE_SYNC, см. app/sync): облако — основная система, ядро включается только
+ * на время обрыва связи. В режиме cloud событие уходит в прокси (в облако) как раньше, в
+ * offline/recovering его обслуживает локальная БД.
+ *
+ * localOnly — обработчики, нужные только офлайн (app.init, вход по PIN, смены): без синка
+ * их всегда обслуживает Laravel, иначе ядро перехватило бы то, что сегодня умеет только он.
+ */
+const syncGate = (entry) => {
+    if (!syncConfig.isSyncEnabled()) {
+        return !entry.localOnly;
+    }
+    // Лениво: app/sync сам зовёт ядро (эмит патчей), прямой require замкнул бы цикл.
+    return require('../sync').mode() !== 'cloud';
+};
+
+/**
+ * cloudOnly — события облачного контура (auth.check): на кассе их по-прежнему обслуживает
+ * облако через прокси, у кассы нет ни токенов, ни данных для ответа.
+ */
+const contourGate = (entry) => !entry.cloudOnly || mode() === 'cloud';
+
+const canHandle = (event) => {
+    if (!isEnabled()) {
+        return false;
+    }
+    const entry = registry.get(event);
+    return Boolean(entry) && allowed(event) && contourGate(entry) && syncGate(entry);
+};
+
+const isOfflineRoute = (path) => {
+    if (!isEnabled()) {
+        return false;
+    }
+    const event = registeredPaths.get(path);
+    return Boolean(event) && canHandle(event);
+};
+
+/** Заголовки, которые нужны апстриму при досылке операции из outbox. */
+const FORWARD_HEADERS = [
+    'team-id', 'company-id', 'terminal-id', 'employee-id',
+    'timestamp', 'ip-address', 'authorization', 'idempotency-key',
+];
+
+/** Заголовки приходят и в нижнем регистре (express), и в исходном (socket-payload фронта). */
+const header = (headers, name) => {
+    if (!headers) {
+        return null;
+    }
+    if (headers[name] !== undefined) {
+        return headers[name];
+    }
+    const found = Object.keys(headers).find((key) => key.toLowerCase() === name);
+    return found ? headers[found] : null;
+};
+
+const forwardHeaders = (headers) => {
+    const result = {};
+    for (const name of FORWARD_HEADERS) {
+        const value = header(headers, name);
+        if (value) {
+            result[name] = value;
+        }
+    }
+    return result;
+};
+
+// Печать у мастера ждёт принтер (цеха параллельно, до 120с) — запас как у сокет-прокси.
+const SLOW_EVENTS = new Set(['orders.sendToWorkshops', 'orders.printBillReceipt']);
+
+/** Событие ведомого → мастер зала. Ответ мастера отдаётся как есть, ошибка — HttpError. */
+const forwardToMaster = async (event, {headers = {}, params = {}}) => {
+    const axios = require('axios');
+    const {lanHeaders} = require('../sync/lan');
+    const masterUrl = syncConfig.masterUrl();
+    const unavailable = () => new HttpError(503, {success: false, message: 'Master terminal is unavailable', error_code: 'master_unavailable'});
+    // OFFLINE_MASTER_URL=auto, а мастер в сети ещё не найден
+    if (!masterUrl) {
+        throw unavailable();
+    }
+    let response;
+    try {
+        response = await axios.post(`${masterUrl}/api/${event}`, params, {
+            headers: {
+                ...forwardHeaders(headers),
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                ...lanHeaders(),
+            },
+            timeout: SLOW_EVENTS.has(event) ? 150000 : syncConfig.timeouts().master,
+            validateStatus: () => true,
+        });
+    } catch (e) {
+        throw unavailable();
+    }
+    if (response.status >= 400) {
+        throw new HttpError(response.status, response.data || {success: false, message: `HTTP ${response.status}`});
+    }
+    return response.data === '' || response.data === undefined ? null : response.data;
+};
+
+/** Адрес клиента для логов scope. За Traefik — первый адрес X-Forwarded-For. */
+const clientIp = (req) => {
+    const forwarded = req.headers && req.headers['x-forwarded-for'];
+    if (typeof forwarded === 'string' && forwarded.trim()) {
+        return forwarded.split(',')[0].trim();
+    }
+    return req.ip || (req.socket && req.socket.remoteAddress) || null;
+};
+
+/** Сервисы на запрос — прямой аналог резолва PlatformService + сервисов из контейнера Laravel. */
+const makeServices = async ({headers = {}, params = {}, team = undefined, locale = undefined, db = null} = {}) => {
+    db = db || await getDatabase();
+    const context = new Context({
+        team,
+        locale,
+        teamId: header(headers, 'team-id'),
+        companyId: header(headers, 'company-id'),
+        terminalId: header(headers, 'terminal-id'),
+        employeeId: header(headers, 'employee-id'),
+        timestamp: header(headers, 'timestamp'),
+        ipAddress: header(headers, 'ip-address'),
+        operationId: header(headers, 'idempotency-key') || params.operation_id || null,
+        db,
+    });
+    // Один раз читаем team/company/terminal/employee, дальше геттеры контекста синхронны.
+    await context.load();
+
+    const emitter = new SocketEmitter({
+        db,
+        context,
+        // Отдельный экземпляр без эмиттера: нужен только для чтения списка открытых чеков.
+        buildOpenOrders: (companyId) => new OrderService({db, context}).getOpenOrders(companyId),
+    });
+
+    return {
+        db,
+        context,
+        emitter,
+        orders: new OrderService({db, context, emitter}),
+        orderProducts: new OrderProductService({db, context, emitter}),
+        outbox: new OutboxRepository(db),
+    };
+};
+
+/**
+ * Выполнение события ядром. Бросает HttpError, если сервис вернул ошибку с кодом.
+ *
+ * @param {string} event  имя события Laravel («orders.create»)
+ * @param {{headers: object, params: object, ip?: string}} request
+ */
+const runEvent = async (event, {headers = {}, params = {}, ip = null} = {}) => {
+    const handler = registry.get(event);
+    if (!handler) {
+        throw new HttpError(404, {success: false, message: `Unknown event ${event}`});
+    }
+
+    // Облако: токен, лицензия, scope и режим заведения — до всего остального, как цепочка
+    // middleware Laravel. Заведение в `local` — событие выполнил мастер, отдаём его ответ.
+    let authorized = null;
+    if (!handler.isPublic && mode() === 'cloud' && auth.isEnabled()) {
+        const db = await getDatabase();
+        authorized = await auth.authorize(db, {event, headers, params, ip});
+        if (authorized.relayed) {
+            const {status, body} = authorized.relayed;
+            if (status >= 400) {
+                throw new HttpError(status, body ?? {});
+            }
+            return body === undefined ? null : body;
+        }
+    }
+
+    // Ведомый терминал зала своей БД не ведёт: чеки живут у мастера, туда и уходит событие
+    // (вместе с ключом идемпотентности — дедуп делает мастер).
+    if (syncConfig.isSyncEnabled() && syncConfig.role() === 'follower' && !handler.followerLocal) {
+        return forwardToMaster(event, {headers, params});
+    }
+
+    // Модель M, to_online: касса досылает очередь и вот-вот отдаст заведение облаку. Новая
+    // правка сейчас продлила бы очередь и могла разойтись с облаком — просим подождать.
+    if (handler.mutation && syncConfig.isSyncEnabled() && require('../sync').mode() === 'draining') {
+        throw new HttpError(409, {
+            success: false,
+            error_code: 'mode_switching',
+            message: 'Rejim dəyişdirilir, bir az gözləyin',
+        });
+    }
+
+    const services = await makeServices({
+        headers,
+        params,
+        team: authorized ? authorized.team : undefined,
+        locale: authorized ? authorized.locale : undefined,
+    });
+
+    // Дедуп жеста. Забранное ядром событие до middleware Laravel не доходит — проверку
+    // exactly-once делаем здесь, на той же таблице idempotency_keys и по тому же ключу.
+    // Чтения не дедупим: у них нет побочных эффектов, а ключ на них фронт и не шлёт.
+    const key = handler.mutation && idempotencyEnabled()
+        ? resolveKey(services.context.operationId)
+        : null;
+    const guard = key ? new Idempotency(services.db) : null;
+    const owned = guard
+        ? await guard.claim(key, {companyId: services.context.companyId, event})
+        : false;
+
+    if (guard && !owned) {
+        // Тот же жест уже выполняется/выполнен: отдаём сохранённый ответ либо 409 in_progress.
+        return (await guard.replay(key)).result;
+    }
+
+    let result;
+    try {
+        // Третий аргумент нужен редким обработчикам, которым мало контекста (ведомый app.init
+        // спрашивает у мастера открытые чеки с исходными заголовками терминала).
+        result = await handler.action(services, params, {event, headers, ip, auth: authorized});
+    } catch (e) {
+        if (owned) {
+            await guard.release(key);
+        }
+        throw e;
+    }
+
+    if (owned) {
+        await guard.markDone(key, result === undefined ? null : result);
+    }
+
+    // Outbox — только у локального мастера: в облаке запись уже в целевой базе,
+    // досылать её некуда, да и таблицы outbox там нет.
+    // С синком (модель F) outbox не нужен: наверх уходит агрегат чека по пометкам sync_dirty.
+    if (handler.mutation && mode() === 'local' && !syncConfig.isSyncEnabled()) {
+        // Пишем ПОСЛЕ успешной обработки: провалившаяся операция не уедет наверх.
+        try {
+            await services.outbox.push({
+                event,
+                payload: params,
+                headers: forwardHeaders(headers),
+                operationId: services.context.operationId,
+            });
+        } catch (e) {
+            console.error(`[core] outbox push failed for ${event}:`, e.message);
+        }
+    }
+
+    return result === undefined ? null : result;
+};
+
+/** Транспорт socket.io: тот же реестр, но результат/ошибка отдаются вызывающему. */
+const dispatch = (event, request) => runEvent(event, request);
+
+/**
+ * Регистрирует карту обработчиков на роутере: ключ — имя события, значение — [options, action].
+ * Метод не фиксируем (router.all): Laravel принимает событие через Route::any, фронт ходит
+ * и POST'ом (сокет-фолбэк), и GET'ом (например orders.archive).
+ */
+const registerOfflineRoutes = (router, prefix, handlers) => {
+    for (const [event, [options, action]] of Object.entries(handlers)) {
+        registry.set(event, {
+            mutation: Boolean(options.mutation),
+            localOnly: Boolean(options.localOnly),
+            followerLocal: Boolean(options.followerLocal),
+            cloudOnly: Boolean(options.cloudOnly),
+            isPublic: Boolean(options.public),
+            action,
+        });
+        registeredPaths.set(`${prefix}/${event}`, event);
+
+        router.all(`/${event}`, async (req, res, next) => {
+            // Решение «локально или в прокси» принимается один раз — там же, где решается,
+            // парсить ли тело (server.js). Режим синка может смениться между этими точками, а
+            // распарсенное тело нельзя отдать прокси, как и нераспарсенное — ядру.
+            const local = typeof req.coreLocal === 'boolean' ? req.coreLocal : canHandle(event);
+            if (!local) {
+                return next();
+            }
+            try {
+                // Laravel $request->get() читает и query, и тело — повторяем порядок.
+                const params = {...(req.query || {}), ...(req.body || {})};
+                return res.json(await runEvent(event, {headers: req.headers, params, ip: clientIp(req)}));
+            } catch (e) {
+                if (e instanceof HttpError) {
+                    if (e.headers) {
+                        res.set(e.headers);
+                    }
+                    return res.status(e.status).json(e.body);
+                }
+                console.error(`[core] ${event} failed:`, e);
+                return res.status(500).json({success: false, message: e.message});
+            }
+        });
+    }
+    return router;
+};
+
+module.exports = {
+    isEnabled,
+    mode,
+    canHandle,
+    dispatch,
+    isOfflineRoute,
+    makeServices,
+    forwardToMaster,
+    registerOfflineRoutes,
+};