@kreiseck/kasseneck-api 0.31.0 → 1.0.0-rc.2

package/dist/esm/pos/settings.js

@@ -0,0 +1,367 @@
+/**
+ * Kassen-Einstellungen der Browser-Kasse und der Kassen-App in der Form des
+ * Drahts `/api/v3` (Nachtrag Stufe 4, §11.7.2): Schluessel und Katalogwerte
+ * englisch. Zwilling von `functions-kasse/kasse-settings-core.js` (Backend,
+ * dort mit Validator und in der inneren, deutschen Form).
+ *
+ * Betriebsweit (`business`, am Konto) und je Geraet (`device`). Die
+ * Standardwerte stehen hier UND im Backend; `fixtures/pos-settings-defaults.json`
+ * ist aus dem Vertrags-Export abgeleitet (Antwort fuer ein Konto ohne
+ * gespeicherte Einstellungen) und haelt beide deckungsgleich. Die innere Form
+ * derselben Werte liegt unter `fixtures/stored/`. Trinkgeld ist bewusst AUS,
+ * bis die Buchung geklaert ist (Spec kachel-kasse § 9).
+ */
+/*
+ * Jedes Enum steht als Liste zur Laufzeit da, der Typ leitet sich daraus ab
+ * (`typeof LISTE[number]`). So gibt es die Werte nur einmal, und die Zwillinge
+ * (Backend-Validator, Flutter-Paket) koennen gegen dieselben Listen pruefen,
+ * statt sie abzuschreiben. Der Name der Liste ist der Feldname in
+ * GROSSSCHRIFT (`tileStyle` -> `TILE_STYLE`): so fuehrt `fixtures/surface.json`
+ * jede Liste unter dem Namen des Feldes, zu dem sie gehoert.
+ */
+export const THEME = ['clear', 'warm', 'night', 'contrast'];
+export const FONT_SIZE = ['S', 'M', 'L', 'XL'];
+export const WATERMARK = ['off', 'login', 'everywhere'];
+export const QUANTITY = ['off', 'x', 'kg'];
+export const TIP_MODE = ['amount', 'total', 'both'];
+export const CHECKOUT_MODE = ['page', 'panel'];
+/** Kartenanbieter: Karte gibt es erst mit eingerichtetem Anbieter; 'external' = eigenes Terminal ohne Anbindung. */
+export const CARD_PROVIDER = ['none', 'external', 'gptom', 'hobex', 'mypos', 'stripe'];
+export const RECEIPT_OUTPUT = ['qr', 'print', 'email', 'sms', 'ask'];
+export const LAYOUT = ['right', 'left', 'fullscreen'];
+export const CATEGORY_POSITION = ['top', 'left'];
+export const TILE_HEIGHT = ['S', 'M', 'L'];
+/**
+ * `sdp` = Netzwerk ueber Epson Server Direct Print (der Drucker holt Jobs vom Backend, jeder Browser druckt).
+ * `network` = Epson direkt per IP (ePOS). `connect` = Kasseneck Connect (lokaler
+ * Agent auf dem Kassen-Rechner druckt fuer die Browser-Kasse).
+ */
+export const PRINTER_TYPE = ['sdp', 'network', 'bluetooth', 'usb', 'connect'];
+/** Terminal-Ansprache: direkt per IP oder ueber Kasseneck Connect (Agent leitet weiter). */
+export const TERMINAL_VIA = ['direct', 'connect'];
+/** Art des Kartenterminals an dieser Kasse: keines oder Hobex HPS (JSON-REST am Geraet). */
+export const TERMINAL_TYPE = ['none', 'hps'];
+export const PAPER_SIZE = ['mm58', 'mm80'];
+export const CODE_PAGE = ['CP1252', 'CP437'];
+export const CUT = ['partial', 'full', 'none'];
+export const DRAWER_AUTO_OPEN = ['cash', 'always', 'never'];
+/**
+ * Mit welchem Befehl der Signatur-QR auf den Bon kommt.
+ *
+ * `raster` = der QR wird als Bild gerastert (GS v 0) und geht darum durch jeden
+ * Drucker, der Bilder kann. `escpos` = der native QR-Befehl (GS ( k): schaerfer
+ * und schneller, aber aeltere Geraete drucken dann gar keinen QR oder
+ * Zeichensalat.
+ *
+ * `auto` ist die Vorgabe und heisst **unbestimmt**: an diesem Geraet hat noch
+ * niemand am Papier entschieden. Jede Kasse bleibt dann bei ihrer bisherigen
+ * Praxis, die Browser-Kasse beim ESC/POS-Befehl, die App beim Rasterbild.
+ * Eine harte Vorgabe waere hier eine stille Umstellung des Altbestands
+ * gewesen: jedes Geraet, das nie durch den Drucker-Wizard lief, druckte
+ * ploetzlich anders, und ueber BLE kostet ein Rasterbild mehrere Sekunden je
+ * Bon. Nur ein ausdruecklich gesetzter Wert aendert etwas.
+ *
+ * **Eine Geraete-Einstellung, keine des Betriebs:** derselbe Bon kommt an einer
+ * Kasse sauber heraus und an der Nebenkasse nicht. Und sie ist nicht
+ * kosmetisch: nach § 132a BAO ist der QR Teil des Belegs; wer den falschen
+ * Modus stehen laesst, erteilt Belege ohne lesbare Signatur.
+ */
+export const QR_MODE = ['auto', 'raster', 'escpos'];
+/** Groesse des Kuerzel-Logos in der Kopfzeile der Kasse. */
+export const LOGO_SIZE = ['S', 'M', 'L'];
+/** Schriftgroesse in den Chef-Einstellungen, getrennt von der Schrift der Kasse. */
+export const SETTINGS_FONT_SIZE = ['S', 'M', 'L'];
+/** Kachel-Optik: farbiger Streifen am Rand oder ganz gefuellte Kachel. */
+export const TILE_STYLE = ['stripe', 'full'];
+/** Automatisches Abmelden nach Minuten Ruhe; 0 = nie. */
+export const AUTO_LOGOUT_MINUTES = [0, 1, 5, 15, 30];
+/** Rabatt am Beleg erlaubt. */
+export const DISCOUNT = ['off', 'on'];
+/** Seite des Wasserzeichens; ALT, abgeloest von watermarkX. */
+export const WATERMARK_SIDE = ['left', 'center', 'right'];
+/** Deckkraft des Wasserzeichens in Prozent, bewusst Stufen, kein Schieberegler. */
+export const WATERMARK_STRENGTH = [3, 6, 10, 16];
+/** Groesse des Bild-Logos am Beleg. */
+export const LOGO_SCALE = ['S', 'M', 'L', 'XL'];
+/** Groesse des Wasserzeichens, getrennt vom Beleg-Logo. */
+export const WATERMARK_SCALE = ['S', 'M', 'L', 'XL'];
+/** Wie lange die Fertig-Seite stehen bleibt, in Sekunden; 0 = bis zum Tippen. */
+export const DONE_SCREEN_SECONDS = [0, 3, 5, 10, 15, 30, 60];
+/** Aktionen der Kasse, die eine Taste bekommen koennen (Schluessel von `device.shortcuts`). */
+export const POS_SHORTCUT_ACTIONS = [
+    'checkout', 'complete', 'cancel', 'customAmount', 'cash', 'card', 'exactAmount', 'receipts', 'undoLast',
+    'settings', 'logout', 'tip', 'fullscreen', 'clearTendered', 'clearCart', 'splitPayment',
+];
+export const POS_SHORTCUT_DEFAULTS = Object.freeze({
+    checkout: ['Enter'], complete: ['Enter'], cancel: ['Escape'],
+    // Mod+F gehoert dem Vollbild; Betrag frei liegt auf D. Bar bleibt auf B
+    // (Entscheidung vom 21.8., der Tausch von 0.6.25 ist zurueck).
+    customAmount: ['Mod+D'], cash: ['Mod+B'], card: ['Mod+K'], exactAmount: ['Mod+P'],
+    // NICHT Mod+E: das faengt Chrome auf dem Mac selbst ab („Auswahl fuer
+    // Suche verwenden"), am Geraet belegt. J wie Journal laesst er durch.
+    receipts: ['Mod+J'], undoLast: ['Mod+Backspace'],
+    // NICHT Mod+T: die Taste ist im Browser reserviert (neuer Tab) und kommt
+    // nie bei der Seite an. Mod+G laesst Chrome durch.
+    settings: ['Mod+S'], logout: ['Mod+L'], tip: ['Mod+G'],
+    fullscreen: ['Mod+F'],
+    // Mod+C = Kopieren des Browsers; im Kassieren-Schritt ist Kopieren fern,
+    // und die Bindung gilt nur dort (Bar + Rueckgeld-Rechner an).
+    clearTendered: ['Mod+C'],
+    // Bewusst DIESELBE Taste wie clearTendered: die beiden leben in
+    // verschiedenen Momenten (Korb vor dem Kassieren, Gegeben-Feld darin),
+    // der Verteiler laesst die nicht zustaendige Aktion durchfallen.
+    clearCart: ['Mod+C'],
+    // Bewusst ohne Vorgabe: jede freie Mod-Taste ist in irgendeinem Browser
+    // belegt oder am Geraet unerprobt. Der Chef vergibt sie, wenn er sie braucht.
+    splitPayment: [],
+});
+/**
+ * Aktionen, die sich eine Taste teilen duerfen (Backend `TASTEN_PAARE`): sie
+ * leben in verschiedenen Momenten, der Verteiler laesst die nicht zustaendige
+ * durchfallen. Jede andere Doppelbelegung weist der Server ab, und dieses
+ * Paket schon vor dem Senden.
+ */
+export const POS_SHORTCUT_SHARED_PAIRS = Object.freeze([
+    ['checkout', 'complete'],
+    ['clearTendered', 'clearCart'],
+]);
+const darfTeilen = (a, b) => POS_SHORTCUT_SHARED_PAIRS.some(([x, y]) => (x === a && y === b) || (x === b && y === a));
+/**
+ * Die erste Doppelbelegung einer Tastenkarte: `{ action, key, heldBy }` oder
+ * `null`. Geprueft wird die ganze Karte, so wie der Server sie nach dem
+ * Speichern haelt (er selbst prueft nur die gesendeten Eintraege).
+ */
+export function posShortcutConflict(shortcuts) {
+    const belegt = new Map();
+    for (const aktion of Object.keys(shortcuts)) {
+        const tasten = shortcuts[aktion];
+        if (!Array.isArray(tasten))
+            continue;
+        for (const t of tasten) {
+            const vorher = belegt.get(t);
+            if (vorher !== undefined && vorher !== aktion && !darfTeilen(vorher, aktion))
+                return { action: aktion, key: t, heldBy: vorher };
+            belegt.set(t, aktion);
+        }
+    }
+    return null;
+}
+export const POS_BUSINESS_DEFAULTS = Object.freeze({
+    // Das Petrol der Marke: die Aktionsfarbe des Design-Systems (Rolle `brand`).
+    logoText: 'K', logoEnabled: true, logoSize: 'M', watermark: 'login', color: '#136B6B',
+    theme: 'clear', fontSize: 'M', settingsFontSize: 'S', tileStyle: 'stripe', clock: true,
+    lockScreen: true, staffPhotos: true, autoLogoutMinutes: 0, logoutAfterSale: false, fastLogin: true,
+    showPrices: true, showVat: false, emoji: true, categoryColors: true, customAmountAllowed: true,
+    vatRates: { 20: true, 13: true, 10: true, 4.9: true, 0: true, 19: false },
+    quantity: 'x', note: false, search: false, discount: 'off',
+    payCash: true, payCard: false, paySplit: false, cardProvider: 'none', tip: false, tipMode: 'both',
+    tipSteps: { 5: true, 10: true, 15: false, 20: false }, tipSplit: true, change: true,
+    tipChips: [5, 10], exactCash: false, checkoutMode: 'panel',
+    // 'ask' = Fertig-Seite bietet QR und Bon an, sicherster Standard.
+    receiptOutput: 'ask', doneScreenSeconds: 0,
+    logoImage: '', watermarkSide: 'center', watermarkX: 50, watermarkY: 50, watermarkStrength: 6, logoScale: 'M', watermarkScale: 'M',
+    glass: true, hints: true,
+    discountChips: [5, 10, 15, 20],
+});
+export const POS_DEVICE_DEFAULTS = Object.freeze({
+    layout: 'right', categoryPosition: 'top', extraColumns: 0, tileHeight: 'M', touch: false,
+    shortcuts: { ...POS_SHORTCUT_DEFAULTS },
+    printerEnabled: false, printerType: 'sdp', printerIp: '', printerPort: 9100, printerBluetoothId: '', printerName: '',
+    printerId: '', printerDeviceId: 'local_printer', connectPrinterId: '',
+    paperSize: 'mm80', codePage: 'CP1252', cut: 'partial', qrMode: 'auto',
+    drawerEnabled: false, drawerAutoOpen: 'cash',
+    terminalIp: '', terminalPort: 8080, terminalTid: '', terminalVia: 'direct',
+    terminalType: 'none', shortcutHints: true,
+});
+/**
+ * Die Wertemenge je Feld, soweit das Feld eine hat: dagegen prueft der
+ * Schreibweg vor dem Senden (ein deutscher Wert wie `'nacht'` geht so gar
+ * nicht erst hinaus). Die Wahrheit ueber Gueltigkeit hat weiter das Backend.
+ */
+export const POS_BUSINESS_VALUES = Object.freeze({
+    logoSize: LOGO_SIZE, watermark: WATERMARK, theme: THEME, fontSize: FONT_SIZE, settingsFontSize: SETTINGS_FONT_SIZE,
+    tileStyle: TILE_STYLE, autoLogoutMinutes: AUTO_LOGOUT_MINUTES, quantity: QUANTITY, discount: DISCOUNT,
+    cardProvider: CARD_PROVIDER, tipMode: TIP_MODE, checkoutMode: CHECKOUT_MODE, receiptOutput: RECEIPT_OUTPUT,
+    doneScreenSeconds: DONE_SCREEN_SECONDS, watermarkSide: WATERMARK_SIDE, watermarkStrength: WATERMARK_STRENGTH,
+    logoScale: LOGO_SCALE, watermarkScale: WATERMARK_SCALE,
+});
+/** Wie [POS_BUSINESS_VALUES] fuer die Geraete-Einstellungen. */
+export const POS_DEVICE_VALUES = Object.freeze({
+    layout: LAYOUT, categoryPosition: CATEGORY_POSITION, tileHeight: TILE_HEIGHT, printerType: PRINTER_TYPE,
+    paperSize: PAPER_SIZE, codePage: CODE_PAGE, cut: CUT, qrMode: QR_MODE, drawerAutoOpen: DRAWER_AUTO_OPEN,
+    terminalVia: TERMINAL_VIA, terminalType: TERMINAL_TYPE,
+});
+/** Eigene Eigenschaft, nie eine geerbte (`toString`, `constructor`, `__proto__`). */
+const eigen = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+/**
+ * Werte der inneren Form (0.x, deutsch), die unter einem Feldnamen stehen
+ * koennten, den auch die Drahtform traegt. Wichtig sind `layout` und
+ * `terminalVia` (innen und aussen gleich benannt); die Tabelle fuehrt aber jeden
+ * Katalog, damit ein zwischengespeicherter Mischstand nie einen deutschen Wert
+ * ins englische Modell traegt. Ein Test haelt sie deckungsgleich mit den
+ * Katalogen des Vokabulars (innere Werte ohne die gleichlautenden).
+ */
+const ALTWERTE_0X = Object.freeze({
+    watermark: ['aus', 'anmeldung', 'ueberall'],
+    theme: ['klar', 'nacht', 'kontrast'],
+    tileStyle: ['streifen', 'voll'],
+    quantity: ['aus'],
+    discount: ['aus', 'an'],
+    cardProvider: ['keiner', 'extern'],
+    tipMode: ['betrag', 'gesamt', 'beides'],
+    checkoutMode: ['seite'],
+    receiptOutput: ['druck', 'mail', 'fragen'],
+    watermarkSide: ['links', 'mitte', 'rechts'],
+    layout: ['rechts', 'links', 'vollbild'],
+    categoryPosition: ['oben', 'links'],
+    printerType: ['netz', 'bt'],
+    drawerAutoOpen: ['bar', 'immer', 'nie'],
+    terminalVia: ['direkt'],
+    terminalType: ['keins'],
+});
+/** Tasten-Aktionen der inneren Form (0.x). */
+const ALTAKTIONEN_0X = new Set([
+    'kassieren', 'abschliessen', 'abbrechen', 'frei', 'bar', 'karte', 'passend', 'belege', 'letzteZurueck',
+    'einstellungen', 'abmelden', 'trinkgeld', 'vollbild', 'gegebenLeeren', 'korbLeeren', 'getrennt',
+]);
+/** Ein Wert der inneren Form 0.x fuer dieses Feld? (paketintern, fuer die Meldung der Vorab-Pruefung) */
+export function _istAltwert0x(feld, wert) {
+    const alte = eigen(ALTWERTE_0X, feld) ? ALTWERTE_0X[feld] : undefined;
+    return !!alte && alte.includes(wert);
+}
+/** Nur fuer den Test: die beiden Tabellen der inneren Form. */
+export const _ALTFORM_0X = Object.freeze({ werte: ALTWERTE_0X, aktionen: [...ALTAKTIONEN_0X] });
+/**
+ * Standard + stored. Landkarten (`vatRates`, `tipSteps`, `shortcuts`)
+ * werden je Schluessel gemischt, damit neue Saetze beim Altbestand ankommen;
+ * Schluessel, die der Standard nicht fuehrt, bleiben draussen.
+ *
+ * **Immer** (unabhaengig davon, welches Standard-Objekt uebergeben wird, auch
+ * eine Kopie oder das einer zweiten Paketkopie) faellt ein Wert der inneren
+ * Form 0.x auf den Standard zurueck (`layout: 'rechts'`, `terminalVia:
+ * 'direkt'`), und deutsche Tasten-Aktionen (`kassieren`) kommen nicht in die
+ * Tastenkarte. Ein unbekannter **englischer** Wert (`theme: 'sepia'`) bleibt
+ * dagegen stehen: er kann ein neuer Wert des Servers sein.
+ */
+export function mergePosSettings(standard, stored) {
+    const out = JSON.parse(JSON.stringify(standard));
+    if (stored && typeof stored === 'object') {
+        for (const key of Object.keys(stored)) {
+            if (!eigen(out, key))
+                continue;
+            const wert = stored[key];
+            const alt = out[key];
+            if (alt && typeof alt === 'object' && !Array.isArray(alt) && wert && typeof wert === 'object' && !Array.isArray(wert)) {
+                const neu = {};
+                for (const k of Object.keys(wert)) {
+                    if (key === 'shortcuts' && ALTAKTIONEN_0X.has(k))
+                        continue;
+                    if (k === '__proto__')
+                        continue;
+                    neu[k] = wert[k];
+                }
+                out[key] = { ...alt, ...neu };
+            }
+            else if (wert !== undefined) {
+                const alte = eigen(ALTWERTE_0X, key) ? ALTWERTE_0X[key] : undefined;
+                if (alte && alte.includes(wert))
+                    continue;
+                out[key] = wert;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Einen gespeicherten oder zwischengespeicherten Stand `{business, device}`
+ * lesen: gemischt mit den Standardwerten, ohne Werte und Tasten-Aktionen der
+ * inneren Form 0.x (siehe [mergePosSettings]). Der Weg fuer jeden Stand, den
+ * ein Verbraucher selbst abgelegt hat; ein Stand in der inneren Form ergibt
+ * die Standardwerte, nie einen deutschen Wert und nie einen Absturz.
+ */
+export function sanitizePosSettings(stored) {
+    const roh = stored !== null && typeof stored === 'object' ? stored : {};
+    const teil = (k) => {
+        const w = eigen(roh, k) ? roh[k] : undefined;
+        return w !== null && typeof w === 'object' && !Array.isArray(w) ? w : null;
+    };
+    return {
+        business: mergePosSettings(POS_BUSINESS_DEFAULTS, teil('business')),
+        device: mergePosSettings(POS_DEVICE_DEFAULTS, teil('device')),
+    };
+}
+/**
+ * Die Felder, deren Wert dieses Paket nicht kennt (neuer Wert des Servers),
+ * als Pfade (`business.theme`, `device.printerType`). Die Oberflaeche kann sie
+ * als „vom Server, hier nicht einstellbar" zeigen; sie bleiben erhalten, solange
+ * nur geaenderte Felder geschrieben werden ([posSettingsChanges]).
+ */
+export function unknownPosSettingValues(settings) {
+    const raus = [];
+    const pruefe = (teil, block, mengen) => {
+        for (const k of Object.keys(mengen)) {
+            const erlaubt = mengen[k];
+            if (!erlaubt || !eigen(block, k))
+                continue;
+            if (!erlaubt.includes(block[k]))
+                raus.push(`${teil}.${k}`);
+        }
+    };
+    pruefe('business', settings.business, POS_BUSINESS_VALUES);
+    pruefe('device', settings.device, POS_DEVICE_VALUES);
+    // Tasten-Aktionen, die dieses Paket nicht kennt (eine kuenftige des Servers).
+    const bekannt = new Set(POS_SHORTCUT_ACTIONS);
+    const tasten = eigen(settings.device, 'shortcuts') ? settings.device.shortcuts : undefined;
+    if (tasten && typeof tasten === 'object') {
+        for (const aktion of Object.keys(tasten))
+            if (!bekannt.has(aktion))
+                raus.push(`device.shortcuts.${aktion}`);
+    }
+    return raus;
+}
+/**
+ * Was sich zwischen zwei Staenden eines Teils geaendert hat, als Nutzlast fuer
+ * `setMyPosSettings` bzw. `setMyRegisterDeviceSettings`: **nur geaenderte
+ * Felder** (der Server mischt, ein nicht geaenderter, hier unbekannter Wert
+ * geht so nie verloren). `vatRates` geht bei einer Aenderung als ganze Karte
+ * (Nachtrag §11.7.2), `shortcuts` ebenfalls ganz, aber nur mit den Aktionen,
+ * die dieses Paket kennt: so sieht die Doppelbelegungspruefung des Servers die
+ * ganze Belegung, und eine unbekannte Aktion bleibt per Mischen am Server
+ * stehen. `tipSteps` geht nur mit den geaenderten Eintraegen.
+ */
+export function posSettingsChanges(before, after) {
+    const raus = {};
+    const gleich = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+    for (const k of Object.keys(after)) {
+        if (k === '__proto__')
+            continue;
+        const neu = after[k];
+        const alt = eigen(before, k) ? before[k] : undefined;
+        if (gleich(alt, neu))
+            continue;
+        if (k === 'shortcuts' && neu && typeof neu === 'object' && !Array.isArray(neu)) {
+            const bekannt = new Set(POS_SHORTCUT_ACTIONS);
+            const ganz = {};
+            for (const aktion of Object.keys(neu))
+                if (bekannt.has(aktion))
+                    ganz[aktion] = neu[aktion];
+            raus[k] = ganz;
+            continue;
+        }
+        if (k !== 'vatRates' && neu && typeof neu === 'object' && !Array.isArray(neu) && alt && typeof alt === 'object' && !Array.isArray(alt)) {
+            const teil = {};
+            for (const e of Object.keys(neu)) {
+                if (e === '__proto__')
+                    continue;
+                const a = eigen(alt, e) ? alt[e] : undefined;
+                if (!gleich(a, neu[e]))
+                    teil[e] = neu[e];
+            }
+            if (Object.keys(teil).length)
+                raus[k] = teil;
+            continue;
+        }
+        raus[k] = neu;
+    }
+    return raus;
+}