@alizadefaig/pos-server 1.2.26 → 1.2.27

package/routes/desktop/api/offline.js

@@ -0,0 +1,146 @@
+const express = require('express');
+const router = express.Router();
+const {registerOfflineRoutes, forwardToMaster} = require('../../../app/core');
+const {HttpError} = require('../../../app/core/errors');
+const {money} = require('../../../app/core/support/num');
+const {translated} = require('../../../app/core/support/lang');
+const ShiftService = require('../../../app/core/services/ShiftService');
+const {shiftResource} = require('../../../app/core/resources/ShiftResource');
+const syncConfig = require('../../../app/sync/config');
+const kv = require('../../../app/sync/kv');
+const {unlockThrottle, findUnlockUser, throttleKey} = require('../../../app/core/support/unlock');
+
+/**
+ * Офлайн-обработчики модели F (OFFLINE-FIRST-PLAN §11): то, без чего касса не поднимется и
+ * не начнёт смену при оборванном интернете. Порты AuthController::init/unlock,
+ * ShiftController (кассовая смена) и ProductController::getExtraProducts.
+ *
+ * Все localOnly: пока облако доступно (и всегда без OFFLINE_SYNC) их обслуживает Laravel,
+ * ядро включается только в режимах offline/recovering. Только desktop — облачному Node
+ * они не нужны.
+ *
+ * Ведомый терминал зала обслуживает сам лишь app.init (followerLocal): свой blob терминала
+ * хранит он, а чеки — мастер. Остальное ядро ведомого пересылает мастеру.
+ */
+
+const get = (params, name, fallback = null) => {
+    const value = params[name];
+    return value === undefined || value === null ? fallback : value;
+};
+
+const LOCAL_READ = {mutation: false, localOnly: true};
+const LOCAL_MUTATION = {mutation: true, localOnly: true};
+
+/** Ответ app.init, сохранённый снапшотом (kv 'init'). Без него офлайн-старт невозможен. */
+const readInit = () => {
+    const store = require('../../../app/sync').store();
+    const blob = store ? kv.get(store, 'init') : null;
+    if (!blob || typeof blob !== 'object') {
+        throw new HttpError(503, {
+            success: false,
+            message: 'Offline data is not ready yet',
+            error_code: 'offline_not_ready',
+        });
+    }
+    return blob;
+};
+
+/**
+ * Снапшот снят для терминала самой кассы. Телефон официанта, ушедший на мастера по LAN
+ * (LAN_FRONT), получает init со СВОИМ терминалом из реестра устройств: иначе он стал бы
+ * работать от имени кассы. Терминала нет в реестре — честные 503, как без снапшота.
+ *
+ * `user` телефону не отдаётся: это пользователь кассы вместе с её bearer-токеном
+ * (AuthController::init кладёт в user.token токен запроса). Свой пользователь и токен у
+ * телефона уже есть — без поля фронт их не трогает.
+ */
+const withRequestTerminal = (blob, headers) => {
+    if (!syncConfig.isLanFrontEnabled()) {
+        return blob;
+    }
+    const raw = headers ? Object.entries(headers).find(([key]) => key.toLowerCase() === 'terminal-id') : null;
+    const terminalId = raw ? (Array.isArray(raw[1]) ? raw[1][0] : raw[1]) : null;
+    if (!terminalId || (blob.terminal && blob.terminal.id === terminalId)) {
+        return blob;
+    }
+    const terminal = require('../../../app/sync/lanDevices').terminal(terminalId);
+    if (!terminal) {
+        throw new HttpError(503, {
+            success: false,
+            message: 'Offline data is not ready yet',
+            error_code: 'offline_not_ready',
+        });
+    }
+    const {user, ...rest} = blob;
+    return {...rest, terminal};
+};
+
+registerOfflineRoutes(router, '/api', {
+    /**
+     * AuthController::init — снапшотный blob терминала + живые открытые чеки. Чеки из blob
+     * не отдаём никогда: он снят до обрыва, и закрытый с тех пор чек выглядел бы открытым.
+     */
+    'app.init': [{...LOCAL_READ, followerLocal: true}, async ({orders}, p, {headers}) => {
+        const blob = withRequestTerminal(readInit(), headers);
+        if (syncConfig.role() === 'follower') {
+            // Чеки живут у мастера. Он недоступен — честная ошибка лучше пустого зала:
+            // «свободный» стол, за которым сидят гости, опаснее экрана с ошибкой.
+            return {...blob, orders: await forwardToMaster('orders.getOpen', {headers, params: {}})};
+        }
+        return {...blob, orders: await orders.getOpenOrders()};
+    }],
+
+    /** AuthController::unlock — null, если PIN/карта не подошли. */
+    'auth.unlock': [LOCAL_READ, async ({db, context}, p) => {
+        const code = get(p, 'code');
+        if (!code) {
+            return null;
+        }
+        const key = throttleKey(context.teamId, context.terminalId);
+        unlockThrottle.assertAllowed(key);
+        const blob = readInit();
+        const user = await findUnlockUser(db, Array.isArray(blob.users) ? blob.users : [], code, blob.pin_salt);
+        if (!user) {
+            unlockThrottle.fail(key);
+            return null;
+        }
+        unlockThrottle.reset(key);
+        const shifts = new ShiftService({db, context});
+        const [cashShift, workShift] = await Promise.all([
+            shifts.cashShift(),
+            shifts.workShift(user.id),
+        ]);
+        // JsonResource от null сериализуется в [] — повторяем, фронт проверяет именно так.
+        return {
+            user: {...user, cash_shift: shiftResource(cashShift), shift: shiftResource(workShift)},
+            shift: workShift ? shiftResource(workShift) : [],
+            cash_shift: cashShift ? shiftResource(cashShift) : [],
+        };
+    }],
+
+    /** ShiftController::getCashShifts — как в Laravel, без фильтра по типу смены. */
+    'shifts.getCashShifts': [LOCAL_READ, async (services) => new ShiftService(services).cashShifts()],
+
+    /** ShiftController::openCashShift. Смена уедет в облако push'ем раньше чеков (sync_dirty). */
+    'shifts.openCashShift': [LOCAL_MUTATION, async (services, p) => new ShiftService(services).openCashShift(p)],
+
+    /** ShiftController::closeCashShift. Отчёт в Telegram отправит облако, приняв смену push'ем. */
+    'shifts.closeCashShift': [LOCAL_MUTATION, async (services, p) => new ShiftService(services).closeCashShift(p)],
+
+    /** ProductController::getExtraProducts — «свободные» позиции, name переведён на язык команды. */
+    'products.getExtraProducts': [LOCAL_READ, async ({db, context}) => {
+        const rows = await db.all(
+            `SELECT id, full_name, product_workshop_id, price FROM products
+             WHERE type = 'extra' AND team_id = ? AND deleted_at IS NULL`,
+            [context.teamId]
+        );
+        return rows.map((row) => ({
+            id: row.id,
+            full_name: translated(row.full_name, context.locale()),
+            product_workshop_id: row.product_workshop_id,
+            price: row.price === null ? null : money(row.price),
+        }));
+    }],
+});
+
+module.exports = router;

package/routes/desktop/api/printers.js

@@ -7,6 +7,10 @@ escpos.USB = require('@alizadefaig/cafetap-escpos-usb');
 escpos.Network = require('escpos-network');
 const axios = require('axios');
 const {getConfig} = require("../../../app/config");
+const monitor = require('../../../app/monitor');
+const printerAddress = require('../../../app/printers/address');
+const core = require('../../../app/core');
+const syncConfig = require('../../../app/sync/config');
 const appConfig = getConfig();
 
 let PROXY_TARGET = appConfig.apiUrl || 'http://localhost:8000';
@@ -94,7 +98,22 @@ const getNetworkDevices = async (timeOut = 1000) => {
 router.get('/printers.get', async (req, res) => {
     let usbPrinters = await getUsbPrinters();
     let networkPrinters = await getNetworkDevices();
+    // Скан с MAC (фронт с VITE_PRINTER_MAC): Laravel узнаёт по нему принтер, сменивший IP.
+    if (req.query.mac_binding && process.env.PRINTER_MAC_BINDING !== 'false') {
+        networkPrinters = await printerAddress.withMacs(networkPrinters);
+    }
     const printers = [...usbPrinters, ...networkPrinters]
+    // Сохранённые настройки (цеха, счёт, звонок) без облака отдаёт ядро: своя БД кассы или
+    // мастер зала у ведомого. Иначе модалка «Printerlər» офлайн показывала бы голый скан.
+    const fromCore = () => core.dispatch('printers.get', {headers: req.headers, params: {printers}});
+    if (core.canHandle('printers.get')) {
+        try {
+            return res.json(await fromCore());
+        } catch (e) {
+            console.warn('[printers] printers.get from core failed:', e.message);
+            return res.json(printers);
+        }
+    }
     const headers = { ...req.headers };
     delete headers['accept-encoding'];
     axios.post(PROXY_TARGET + '/api/printers.get', {
@@ -111,7 +130,16 @@ router.get('/printers.get', async (req, res) => {
         }
     }).then(({data}) => {
         res.json(data);
-    }).catch(e => {
+    }).catch(async (e) => {
+        // Облако не ответило, а касса ещё не перешла в офлайн (нужно два провала подряд):
+        // настройки уже лежат в локальной БД со снапшота.
+        if (core.isEnabled() && syncConfig.isSyncEnabled()) {
+            try {
+                return res.json(await fromCore());
+            } catch (coreError) {
+                console.warn('[printers] printers.get from core failed:', coreError.message);
+            }
+        }
         res.json([...usbPrinters, ...networkPrinters])
     })
 });
@@ -121,19 +149,261 @@ router.get('/printers.getUsbPrinters', async (req, res) => {
     res.json(usbPrinters);
 })
 
-router.post('/printers.print', async (req, res) => {
+/**
+ * Честный ответ печати (PRINT_HONEST_ACK=true; по умолчанию — старый путь ниже, как сегодня).
+ *
+ * Старый путь отвечает success сразу после вызова printer.close(): запись в устройство идёт уже
+ * после ответа, а escpos в close() ошибку записи выбрасывает (flush(() => adapter.close(cb))).
+ * Потерянный чек рапортуется напечатанным, а следующее задание на тот же принтер стартует
+ * поверх незавершённой передачи — фронт закрывает это паузой DEVICE_SETTLE_MS (эвристика).
+ *
+ * Здесь:
+ *   - ответ — по колбэку записи (USB: bulk-transfer дошёл до принтера; LAN: байты ушли в сокет);
+ *     ошибка записи → success:false, error:'write_error';
+ *   - таймаут `timeout` из запроса — только на открытие устройства (как раньше), на запись —
+ *     отдельный PRINT_WRITE_TIMEOUT_MS (длинный чек пишется, пока принтер печатает). Не успели →
+ *     устройство закрывается, error:'write_timeout' (чек мог выйти частично — оператор повторит);
+ *   - задания на ОДНО физическое устройство выстраиваются в очередь в самом Node: сюда печатают
+ *     не только свой фронт, но и мост ведомого терминала (app/sync/bridge.js).
+ */
+const honestAck = () => process.env.PRINT_HONEST_ACK === 'true';
+const writeTimeout = () => Number(process.env.PRINT_WRITE_TIMEOUT_MS) || 30000;
+
+const deviceQueues = new Map();
+
+// Ключ физического устройства — ровно как его открывает getPrinterDevice (LAN всегда :9100).
+const deviceKey = (printer) => (printer.type === 'USB'
+    ? `usb:${+printer.vendor_id}:${+printer.product_id}`
+    : `lan:${printer.ip_address}`);
+
+const enqueue = (key, task) => {
+    const previous = deviceQueues.get(key) || Promise.resolve();
+    const run = previous.then(task);
+    const tail = run.catch(() => {});
+    deviceQueues.set(key, tail);
+    tail.then(() => {
+        if (deviceQueues.get(key) === tail) {
+            deviceQueues.delete(key);
+        }
+    });
+    return run;
+};
+
+const writeReceipt = (printer, images, body) => {
+    const printMethod = body.print_method || 'raster';
+    printer.align('CT');
+    images.forEach(image => {
+        if (printMethod === 'raster') {
+            printer.raster(image, body.mode);
+        } else {
+            printer.image(image, body.mode);
+        }
+    });
+    if (body.bell) {
+        printer.beep(body.bell_count || 2, body.bell_time || 3);
+    }
+    if (body.cashdraw) {
+        printer.cashdraw(body.cashdraw_pin || 2);
+    }
+    printer.newLine().newLine().cut();
+};
+
+/**
+ * LAN: колбэк записи значит лишь «байты ушли в ядро ОС» — весь чек помещается в буферы сокета,
+ * даже если принтер не прочитал ни байта. Поэтому шлём FIN и ждём, пока принтер закроет свою
+ * сторону (значит, дочитал всё). Не закрыл за PRINT_LAN_DRAIN_MS (бывают принтеры, которые
+ * соединение не закрывают) — считаем отправленным без подтверждения: confirmed = false.
+ * Для длинного чека это время печати — ответ приходит позже, зато следующее задание не
+ * открывает второе соединение поверх недочитанного первого.
+ * USB: bulk-transfer и так завершается, когда принтер принял данные, — confirmed сразу.
+ */
+const lanDrain = () => Number(process.env.PRINT_LAN_DRAIN_MS) || 3000;
+
+const releaseDevice = (device) => new Promise((resolve) => {
+    const close = (confirmed) => {
+        try {
+            device.close(() => {});
+        } catch (e) {
+        }
+        resolve(confirmed);
+    };
+    const socket = device.device;
+    if (!(socket instanceof net.Socket) || socket.destroyed) {
+        return close(true);
+    }
+    const timer = setTimeout(() => close(false), lanDrain());
+    socket.once('close', () => {
+        clearTimeout(timer);
+        close(true);
+    });
+    socket.end();
+});
+
+/**
+ * Печатает один чек. `report(result)` вызывается один раз — это ответ фронту/Laravel; сам промис
+ * резолвится, когда устройство свободно для следующего задания.
+ */
+const printHonestly = (device, images, body, report) => new Promise((resolve) => {
+    let reported = false;
+    let timer = null;
+    const finish = (result) => {
+        if (reported) {
+            return;
+        }
+        reported = true;
+        clearTimeout(timer);
+        report(result);
+    };
+    const fail = (result) => {
+        finish(result);
+        // Прерываем незавершённую передачу — ждать её нечего.
+        try {
+            device.close(() => {});
+        } catch (e) {
+        }
+        resolve();
+    };
+
+    timer = setTimeout(() => fail({success: false, error: 'timeout'}), body.timeout || 5000);
+
+    device.open((err) => {
+        if (reported) {
+            // Открылось после таймаута (или повторный error LAN-сокета) — устройство не держим.
+            try {
+                device.close(() => {});
+            } catch (e) {
+            }
+            return;
+        }
+        if (err) {
+            return fail({success: false, error: 'connection_error', message: err});
+        }
+        clearTimeout(timer);
+        timer = setTimeout(() => fail({success: false, error: 'write_timeout'}), writeTimeout());
+
+        const printer = new escpos.Printer(device, {});
+        try {
+            writeReceipt(printer, images, body);
+        } catch (e) {
+            return fail({success: false, error: 'write_error', message: e.message});
+        }
+        printer.flush((writeError) => {
+            if (reported) {
+                return;
+            }
+            if (writeError) {
+                return fail({success: false, error: 'write_error', message: writeError.message || String(writeError)});
+            }
+            // Таймер записи продолжает идти и на время LAN-дочитывания: зависший принтер → write_timeout.
+            releaseDevice(device).then((confirmed) => {
+                finish(confirmed ? {success: true} : {success: true, confirmed: false});
+                resolve();
+            });
+        });
+    });
+});
+
+// Итог печати — в мониторинг кассы (heartbeat → суперадминка). На сам ответ не влияет.
+const trackPrint = (req, res, next) => {
+    const json = res.json.bind(res);
+    res.json = (body) => {
+        monitor.recordPrint(body);
+        return json(body);
+    };
+    next();
+};
+
+// Телефон официанта на странице мастера (req.lanDevice, app/sync/lan.js): USB-принтер кассы
+// ему не нужен, а адрес сетевого принтера он задаёт сам — пускаем только в частную сеть IPv4.
+const PRIVATE_IPV4 = /^(10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3})$/;
+const devicePrinterAllowed = (printer) => Boolean(printer) && printer.type === 'LAN'
+    && PRIVATE_IPV4.test(String(printer.ip_address || ''));
+
+router.post('/printers.print', trackPrint, async (req, res) => {
+    if (req.lanDevice && !devicePrinterAllowed(req.body?.printer)) {
+        return res.status(403).json({success: false, error: 'forbidden', message: 'Forbidden'});
+    }
     if (process.env.APP_DEBUG === 'true') {
         await new Promise(resolve => setTimeout(resolve, 100));
         return res.json({ success: true, mock: true });
     }
+    if (printerAddress.enabled(req.body)) {
+        return printByMac(req, res);
+    }
+    // print() асинхронный: без catch исключение (битый PNG, сбой sharp) оставило бы запрос без
+    // ответа, и терминал ждал бы его до таймаута круга печати (90 с).
+    return print(req, res, req.body.printer).catch((e) => {
+        console.warn('[printers] print failed:', e && e.message);
+        if (!res.headersSent) {
+            res.json({success: false, error: 'print_error', message: (e && e.message) || String(e)});
+        }
+    });
+})
 
-    const device = getPrinterDevice(req.body.printer);
+/**
+ * Сетевой принтер с привязкой по MAC (app/printers/address.js): сначала узнаём, где он сейчас,
+ * потом печатаем обычным путём на найденный адрес. В честном режиме адрес ищется внутри очереди
+ * устройства — проба порта не пересекается с идущей печатью на тот же принтер.
+ *
+ * К успешному ответу добавляется:
+ *   resolved_ip — принтер найден не по записанному адресу (фронт → printers.syncAddress);
+ *   mac_address — MAC принтера (для принтера без привязки — прочитанный из ARP).
+ * Неудача сбрасывает проверку адреса: следующее задание проверит его заново.
+ */
+const printByMac = (req, res) => {
+    const printer = req.body.printer;
+    const mac = printerAddress.normalizeMac(printer.mac_address);
+    const run = async () => {
+        const target = await printerAddress.resolve(printer);
+        if (target.error) {
+            return res.json({success: false, error: target.error, message: `Printer ${mac} not found in the network`});
+        }
+        const json = res.json.bind(res);
+        res.json = (body) => {
+            if (body && typeof body === 'object' && body.success) {
+                const known = target.mac || target.learnedMac;
+                body = {
+                    ...body,
+                    ...(target.moved ? {resolved_ip: target.ip} : {}),
+                    ...(known ? {mac_address: known} : {}),
+                };
+            } else if (body && typeof body === 'object') {
+                printerAddress.invalidate(target.mac, target.ip);
+            }
+            return json(body);
+        };
+        return print(req, res, {...printer, ip_address: target.ip}, {queued: honestAck()});
+    };
+    const job = honestAck() ? enqueue(mac ? `lan:mac:${mac}` : deviceKey(printer), run) : run();
+    return job.catch((e) => {
+        console.warn('[printer-mac] print failed:', e.message);
+        if (!res.headersSent) {
+            res.json({success: false, error: 'print_error', message: e.message});
+        }
+    });
+};
+
+/**
+ * Печать на принтер `target`. `queued` — вызывающий уже держит очередь устройства (привязка по MAC):
+ * честная печать идёт сразу и возвращается, когда устройство свободно.
+ */
+const print = async (req, res, target, {queued = false} = {}) => {
+    const device = getPrinterDevice(target);
     const printMethod = req.body.print_method || 'raster';
     const printMode = req.body.mode;
     const partHeight = req.body.height || 576;
     const partWidth = req.body.width || 576;
     if (!device) {
-        return res.send('bad').status(404);
+        // Раньше здесь был `res.send('bad')` со статусом 200: фронт считал это успехом, и чек на
+        // неподключённый принтер пропадал молча. Мониторинг запишет ответ сам (trackPrint).
+        const where = target && target.type === 'USB'
+            ? `USB ${target.vendor_id}:${target.product_id}`
+            : String((target && target.ip_address) || '');
+        return res.json({
+            success: false,
+            error: 'no_device',
+            message: `Printer ${(target && target.name) || ''} (${where}) not found`,
+        });
     }
 
     const contentsBuffer = await splitImageByHeight(req.body.content, partHeight, partWidth);
@@ -149,6 +419,19 @@ router.post('/printers.print', async (req, res) => {
         }
         resolve(_images);
     });
+    if (honestAck()) {
+        let report;
+        const result = new Promise((resolve) => {
+            report = resolve;
+        });
+        const job = () => printHonestly(device, images, req.body, report);
+        if (queued) {
+            await job();
+        } else {
+            enqueue(deviceKey(target), job);
+        }
+        return res.json(await result);
+    }
     const printer = new escpos.Printer(device, {});
     const timeOut = req.body.timeout || 5000;
 
@@ -206,6 +489,6 @@ router.post('/printers.print', async (req, res) => {
             })
         }
     }, timeOut);
-})
+}
 
 module.exports = router;

package/routes/desktop/local.js

@@ -0,0 +1,130 @@
+const express = require('express');
+const router = express.Router();
+const sync = require('../../app/sync');
+const {isSyncEnabled} = require('../../app/sync/config');
+const {isLoopback} = require('../../app/sync/lan');
+const {strictOriginGuard} = require('../../app/security');
+const {getConfig} = require('../../app/config');
+const {normalizeApiUrl} = require('../../app/sync/cloud');
+
+/**
+ * Управление офлайн-контуром кассы (модель F, OFFLINE-FIRST-PLAN §11).
+ *
+ *   GET    /local/status   — куда сейчас ходить фронту (mode) и состояние синка;
+ *                            его же читает ведомый терминал у мастера (с ключом зала);
+ *   POST   /local/session  — фронт отдаёт токен и заголовки терминала: с ними синк ходит
+ *                            в облако;
+ *   DELETE /local/session  — выход терминала, токен забывается (старый фронт);
+ *   POST   /local/logout   — выход терминала: сессия паркуется, токен отзывается, когда
+ *                            очередь дослана и облако на связи;
+ *   POST   /local/resume   — вход обратно на запаркованную сессию по PIN сотрудника (без облака);
+ *   GET    /local/whoami   — мастер подписанно отвечает ведомому, который его ищет;
+ *   GET    /local/lan      — телефону на LAN-странице мастера: пора ли назад в облако.
+ *
+ * Только desktop: облачный Node эти пути не обслуживает, иначе старый Electron (у которого
+ * /local/* проксируется в облако) получил бы 200 и опрашивал облако каждые 2 секунды.
+ * Синк выключен — 404: фронт считает Node старым и перестаёт опрашивать.
+ */
+const disabled = (res) => res.status(404).json({success: false, message: 'Offline mode is disabled'});
+
+// Сессию задаёт только фронт этой же машины — даже с ключом зала чужой не подменит токен.
+const loopbackOnly = (req, res, next) => {
+    if (isLoopback(req.socket && req.socket.remoteAddress)) {
+        return next();
+    }
+    return res.status(403).json({success: false, message: 'Forbidden'});
+};
+
+/**
+ * Куда синк ходит в облако, решает не тело запроса, а конфиг самого Node (тот же apiUrl, что у
+ * прокси). Иначе страница, до которой дотянулся localhost, увела бы офлайн-чеки на свой сервер
+ * и залила бы в кассу свой снапшот. OFFLINE_TRUST_SESSION_API_URL=true — старое поведение (стенды).
+ */
+const pinApiUrl = (body) => {
+    const pinned = getConfig().apiUrl;
+    if (process.env.OFFLINE_TRUST_SESSION_API_URL === 'true' || !pinned) {
+        return body;
+    }
+    if (body.api_url && normalizeApiUrl(String(body.api_url)) !== normalizeApiUrl(pinned)) {
+        console.warn(`[sync] session api_url ${body.api_url} ignored, using ${pinned}`);
+    }
+    return {...body, api_url: pinned};
+};
+
+router.get('/local/status', (req, res) => {
+    if (!isSyncEnabled()) {
+        return disabled(res);
+    }
+    res.set('Cache-Control', 'no-store');
+    return res.json(sync.status());
+});
+
+// Ведомый ищет мастера (app/sync/discovery.js): подписанный ответ на nonce, без ключа зала.
+router.get('/local/whoami', (req, res) => {
+    const answer = isSyncEnabled() ? sync.whoami(req.query.nonce) : null;
+    if (!answer) {
+        return res.status(404).json({success: false});
+    }
+    res.set('Cache-Control', 'no-store');
+    return res.json(answer);
+});
+
+// Телефон официанта на LAN-странице мастера спрашивает, пора ли назад в облако. Без ключа
+// зала (app/sync/lan.js): режим и доступность облака секретом не являются.
+router.get('/local/lan', (req, res) => {
+    const info = isSyncEnabled() ? sync.lanInfo() : null;
+    if (!info) {
+        return res.status(404).json({success: false});
+    }
+    res.set('Cache-Control', 'no-store');
+    return res.json(info);
+});
+
+router.post('/local/session', loopbackOnly, strictOriginGuard, async (req, res) => {
+    if (!isSyncEnabled()) {
+        return disabled(res);
+    }
+    try {
+        const result = await sync.setSession(pinApiUrl(req.body || {}));
+        return res.status(result.success ? 200 : 422).json(result);
+    } catch (e) {
+        console.error('[sync] set session failed:', e);
+        return res.status(500).json({success: false, message: e.message});
+    }
+});
+
+router.delete('/local/session', loopbackOnly, strictOriginGuard, async (req, res) => {
+    if (!isSyncEnabled()) {
+        return disabled(res);
+    }
+    try {
+        return res.json(await sync.clearSession());
+    } catch (e) {
+        console.error('[sync] clear session failed:', e);
+        return res.status(500).json({success: false, message: e.message});
+    }
+});
+
+/** Ответ синка или его HttpError (409/422/429/503) как есть. */
+const respond = (name, fn) => async (req, res) => {
+    if (!isSyncEnabled()) {
+        return disabled(res);
+    }
+    try {
+        return res.json(await fn(req.body || {}));
+    } catch (e) {
+        if (e.name === 'HttpError') {
+            return res.status(e.status).json(e.body);
+        }
+        console.error(`[sync] ${name} failed:`, e);
+        return res.status(500).json({success: false, message: e.message});
+    }
+};
+
+router.post('/local/logout', loopbackOnly, strictOriginGuard,
+    respond('logout', (body) => sync.logout({token: body.token})));
+
+router.post('/local/resume', loopbackOnly, strictOriginGuard,
+    respond('resume', (body) => sync.resume({code: body.code})));
+
+module.exports = router;

package/routes/server/api/login.js

@@ -0,0 +1,37 @@
+const express = require('express');
+const router = express.Router();
+const {registerOfflineRoutes} = require('../../../app/core');
+const AuthService = require('../../../app/core/services/AuthService');
+
+/**
+ * Вход терминала (NODE-MIGRATION-PLAN, этап 2): AuthController::auth, loginTerminal, logoutApp,
+ * unlock. Только облако: на кассе `auth.unlock` обслуживает офлайн-обработчик из снапшота
+ * (`routes/desktop/api/offline.js`), а вход по логину без облака невозможен.
+ *
+ * Группы `app` и `auth` в Laravel ведут в один контроллер — регистрируем оба имени.
+ * Переключаются по одному через CORE_EVENTS, как и остальное ядро.
+ */
+const CLOUD_READ = {mutation: false, cloudOnly: true};
+const CLOUD_WRITE = {mutation: true, cloudOnly: true};
+
+const service = (services) => new AuthService(services);
+
+const loginTerminal = async (services, params, extra) => service(services).loginTerminal(params, extra);
+const logoutApp = async (services, params, extra) => service(services).logoutApp(params, extra);
+const unlock = async (services, params, extra) => service(services).unlock(params, extra);
+
+registerOfflineRoutes(router, '/api', {
+    /** Route::any('app.auth') — вне auth:sanctum: логин и пароль, выпуск токена. */
+    'app.auth': [{...CLOUD_READ, public: true}, async (services, params) => service(services).auth(params)],
+
+    'auth.loginTerminal': [CLOUD_WRITE, loginTerminal],
+    'app.loginTerminal': [CLOUD_WRITE, loginTerminal],
+
+    'auth.logoutApp': [CLOUD_WRITE, logoutApp],
+    'app.logoutApp': [CLOUD_WRITE, logoutApp],
+
+    'auth.unlock': [CLOUD_READ, unlock],
+    'app.unlock': [CLOUD_READ, unlock],
+});
+
+module.exports = router;