@kreiseck/kasseneck-api 1.11.1 → 1.12.0

package/dist/esm/receipt/due.js

@@ -1,4 +1,8 @@
 import { ReceiptType, VoucherAction, VoucherType } from '../enums/index.js';
+import { VoucherCode } from '@kreiseck/validator';
+import { toViennaWallClock } from '../vienna-time.js';
+import { centSumme, istDeckbar, kuSaetze, planeGutscheine, topfFuerSatz, } from './gutschein-plan.js';
+export { VOUCHER_ZERO_RATE_BUCKET_FROM } from './gutschein-plan.js';
 /**
  * Warum sich der Zahlbetrag nicht rechnen laesst. Fest wie ein Backend-Code;
  * dieselbe Liste im Dart-Zwilling und in `fixtures/receipt-due-errors.json`.
@@ -34,9 +38,17 @@ export class ReceiptDueError extends Error {
     reason;
     /** Immer `'rejected'`: es ging nichts hinaus. */
     outcome = 'rejected';
-    constructor(reason, message) {
+    /**
+     * Nur bei `invalid_voucher`: der Gutschein-Code, mit dem der Server
+     * denselben Beleg abwiese (`voucher_rate_mismatch`, `voucher_exceeds_total`,
+     * `voucher_not_found` …), fuer die Meldung an der Kasse.
+     */
+    voucherErrorCode;
+    constructor(reason, message, voucherErrorCode) {
         super(`Zahlbetrag: ${message}`);
         this.reason = reason;
+        if (voucherErrorCode !== undefined)
+            this.voucherErrorCode = voucherErrorCode;
     }
 }
 export function isReceiptDueError(error) {
@@ -51,35 +63,192 @@ export function receiptDueCents(items, vouchers, receiptType, options = {}) {
 }
 /** Wie [receiptDueCents], dazu Zaehler-Delta, Wertgutschein-Anteil und Toepfe. */
 export function receiptDueBreakdown(items, vouchers, receiptType, options = {}) {
+    return rechne(items, vouchers, receiptType, options).ergebnis;
+}
+function rechne(items, vouchers, receiptType, options) {
     const art = belegArt(receiptType);
     const trinkgelder = trinkgeldAuftraege(options);
     if (trinkgelder.length > 0 && !TRINKGELD_ERLAUBT.has(art)) {
         throw new ReceiptDueError('tip_not_allowed', `Trinkgeld gibt es nur bei standard und training, nicht bei "${art}".`);
     }
     if (!UMSATZ.has(art)) {
-        return { dueCents: 0, counterDeltaCents: 0, valueVoucherFlowCents: 0, bucketsCents: null };
+        return { ergebnis: { dueCents: 0, counterDeltaCents: 0, valueVoucherFlowCents: 0, bucketsCents: null }, kunde: [], minusJeTopf: new Map(), auszahlungCents: 0 };
     }
     const positionen = items.map(innen);
-    const gutscheine = vouchers.map(gutscheinInnen);
     // index.js createReceipt: erst `tip`, dann je Zahlart aus payments[].tipCents;
     // jede Runde haengt ihre Positionen hinten an (die Basis bleibt die Ware).
     for (const auftrag of trinkgelder)
         positionen.push(...trinkgeldPositionen(auftrag, positionen, options.tipRecipient));
+    // Danach der Gutschein-Plan (gutschein-beleg.plane): seine Positionen stehen hinter Ware und Trinkgeld.
+    const plan = planeGutscheine(positionen, vouchers, art, {
+        voucherInfo: options.voucherInfo,
+        voucherSettings: options.voucherSettings,
+        voucherArticles: options.voucherArticles,
+        smallBusiness: options.smallBusiness,
+        zeroRateBucketFrom: options.zeroRateBucketFrom,
+        today: options.today ?? wienerTag(),
+    });
+    if ('fehler' in plan)
+        throw new ReceiptDueError('invalid_voucher', plan.text, plan.fehler);
+    const kunde = positionen.slice();
+    positionen.push(...plan.zusatz);
+    // gutschein-beleg.zahlbetrag: nur Wert und Rabatt, ohne Mehrzweck-Verkaeufe im 0-%-Topf.
+    const gutscheine = plan.gutscheine.filter((g) => !(g.action === VoucherAction.sell && g.imNullTopf === true));
     const t = belegToepfe(positionen, gutscheine);
     const fluss = wertgutscheinFlussCents(gutscheine, art);
+    const dueCents = t.zaehlerDeltaCents + fluss;
+    // Ohne Auszahlungen darf der Zahlbetrag nicht negativ werden (Einloesung hoeher als die Summe).
+    if (plan.mitPlan && dueCents + plan.auszahlungCents < 0) {
+        throw new ReceiptDueError('invalid_voucher', 'die Gutscheine uebersteigen die Summe des Belegs.', 'voucher_exceeds_total');
+    }
     return {
-        dueCents: t.zaehlerDeltaCents + fluss,
-        counterDeltaCents: t.zaehlerDeltaCents,
-        valueVoucherFlowCents: fluss,
-        bucketsCents: {
-            amountRateStandard: euroToCent(t.amountRateStandard),
-            amountRateReduced1: euroToCent(t.amountRateReduced1),
-            amountRateReduced2: euroToCent(t.amountRateReduced2),
-            amountRateZero: euroToCent(t.amountRateZero),
-            amountRateSpecial: euroToCent(t.amountRateSpecial),
-            amountRatOthers: euroToCent(t.amountRatOthers),
+        ergebnis: {
+            dueCents,
+            counterDeltaCents: t.zaehlerDeltaCents,
+            valueVoucherFlowCents: fluss,
+            bucketsCents: {
+                amountRateStandard: euroToCent(t.amountRateStandard),
+                amountRateReduced1: euroToCent(t.amountRateReduced1),
+                amountRateReduced2: euroToCent(t.amountRateReduced2),
+                amountRateZero: euroToCent(t.amountRateZero),
+                amountRateSpecial: euroToCent(t.amountRateSpecial),
+                amountRatOthers: euroToCent(t.amountRatOthers),
+            },
         },
+        kunde,
+        minusJeTopf: plan.minusJeTopf,
+        auszahlungCents: plan.auszahlungCents,
+    };
+}
+/**
+ * Hoechstbetrag zum Vorbelegen einer Einloesung an der Kasse, in Cent, nie
+ * negativ: der groesste Betrag, den der Server fuer diesen Gutschein annimmt.
+ *
+ * Obergrenze: Saldo, offener Betrag; bei Einzweck die deckbaren Positionen im
+ * Topf seines Satzes abzueglich der schon gewaehlten Einloesungen dort. Befreit
+ * verkauft bzw. als Kleinunternehmer verteilt der Server anteilig auf alle
+ * Saetze (`kuTeile`); dann begrenzt jeder Topf: sein Anteil plus die schon
+ * gewaehlten Einloesungen dort darf seine Positionen nicht uebersteigen.
+ *
+ * Unter dieser Grenze wird jeder Kandidat mit genau der Rechnung von
+ * [receiptDueCents] geprueft (Rundung halber Cent, groesster Rest), zuerst
+ * Cent fuer Cent abwaerts (64 Schritte). Findet das nichts, sucht eine
+ * Bisektion ueber [1, Grenze] und prueft danach 16 Cent aufwaerts: am Rand
+ * des groessten Rests ist die Annahme nicht monoton. Leistung (wird ueber
+ * Positionen eingeloest), Aktion (Rabatt rechnet der Server) und jeder nicht
+ * aktive Gutschein: 0.
+ */
+export function voucherRedeemMaxCents(items, voucher, before = {}) {
+    if (voucher.status !== 'active')
+        return 0;
+    if (voucher.type !== 'multi_purpose' && voucher.type !== 'single_purpose')
+        return 0;
+    const saldo = Number.isInteger(voucher.balanceCents) ? voucher.balanceCents : 0;
+    const options = before.options ?? {};
+    const vorher = before.vouchers ?? [];
+    const r = rechne(items, vorher, 'standard', options);
+    // Rundung je Topf: hoechstens ein halber Cent je Topf ueber dem offenen Betrag.
+    let oben = Math.min(saldo, r.ergebnis.dueCents + r.auszahlungCents + 6, HOECHSTBETRAG_CENTS);
+    if (voucher.type === 'single_purpose') {
+        const deckbar = r.kunde.filter(istDeckbar);
+        const topfBasis = (topf) => centSumme(deckbar.filter((it) => topfFuerSatz(it.vat) === topf));
+        if (voucher.exempt === true || options.smallBusiness === true) {
+            oben = Math.min(oben, kuGrenze(r.kunde, topfBasis, r.minusJeTopf));
+        }
+        else {
+            if (!Number.isInteger(voucher.vatRateBp))
+                return 0;
+            const topf = topfFuerSatz(voucher.vatRateBp / 100);
+            oben = Math.min(oben, topfBasis(topf) - (r.minusJeTopf.get(topf) ?? 0));
+        }
+    }
+    if (oben <= 0)
+        return 0;
+    const code = probeCode(vorher);
+    const info = [...(options.voucherInfo ?? []), { code, check: voucher }];
+    const passt = (cents) => {
+        try {
+            rechne(items, [...vorher, { action: 'redeem', type: voucher.type, code, amountCents: cents }], 'standard', { ...options, voucherInfo: info });
+            return true;
+        }
+        catch (fehler) {
+            if (fehler instanceof ReceiptDueError)
+                return false;
+            throw fehler;
+        }
     };
+    return groessterBetrag(oben, passt);
+}
+/** Schritte der linearen Suche, bevor die Bisektion uebernimmt. */
+const LINEAR_SCHRITTE = 64;
+/** Cent, die nach der Bisektion aufwaerts geprueft werden (nicht monotoner Rand). */
+const NACHPRUEFEN = 16;
+/** Groesster Betrag in [1, oben], den `passt` annimmt; 0, wenn keiner gefunden wird. */
+function groessterBetrag(oben, passt) {
+    const untenLinear = Math.max(0, oben - LINEAR_SCHRITTE);
+    for (let cents = oben; cents > untenLinear; cents--) {
+        if (passt(cents))
+            return cents;
+    }
+    // Bisektion ueber [1, untenLinear]: `ja` angenommen (0 gilt als angenommen), `nein` abgewiesen.
+    let ja = 0;
+    let nein = untenLinear + 1;
+    while (nein - ja > 1) {
+        const mitte = ja + Math.floor((nein - ja) / 2);
+        if (passt(mitte))
+            ja = mitte;
+        else
+            nein = mitte;
+    }
+    let bester = ja;
+    for (let cents = ja + 1; cents <= Math.min(untenLinear, ja + NACHPRUEFEN); cents++) {
+        if (passt(cents))
+            bester = cents;
+    }
+    return bester;
+}
+/**
+ * Obergrenze fuer eine anteilige Einloesung (`kuTeile`): je Satz ist der Anteil
+ * mindestens `floor(c * basis / summe)`, je Topf also mehr als
+ * `c * basisTopf / summe - saetzeImTopf`. Mit dem freien Rest des Topfs
+ * (Positionen minus schon gewaehlte Einloesungen) folgt
+ * `c <= (frei + saetzeImTopf) * summe / basisTopf`.
+ */
+function kuGrenze(kunde, topfBasis, minusJeTopf) {
+    const saetze = kuSaetze(kunde);
+    const summe = saetze.reduce((a, x) => a + x.basis, 0);
+    let grenze = summe;
+    const jeTopf = new Map();
+    for (const x of saetze) {
+        const topf = topfFuerSatz(x.satzBp / 100);
+        const t = jeTopf.get(topf) ?? { basis: 0, anzahl: 0 };
+        t.basis += x.basis;
+        t.anzahl += 1;
+        jeTopf.set(topf, t);
+    }
+    for (const [topf, t] of jeTopf) {
+        const frei = topfBasis(topf) - (minusJeTopf.get(topf) ?? 0);
+        grenze = Math.min(grenze, Math.floor(((frei + t.anzahl) * summe) / t.basis));
+    }
+    return Math.max(0, grenze);
+}
+const HOECHSTBETRAG_CENTS = 1_000_000;
+/** Ein gueltiger Code, der unter den schon gewaehlten Gutscheinen nicht vorkommt (nur fuer die Probe-Rechnung). */
+function probeCode(vorher) {
+    const belegt = new Set(vorher.map((v) => {
+        const g = typeof v.code === 'string' ? VoucherCode.validate(v.code) : null;
+        return g && g.ok ? g.normalized : null;
+    }));
+    for (let i = 0;; i++) {
+        const code = VoucherCode.generate(Uint8Array.from({ length: 11 }, (_, k) => (i + k * 7) & 31));
+        if (!belegt.has(code))
+            return code;
+    }
+}
+/** Heute in Wien als `YYYY-MM-DD`. */
+function wienerTag() {
+    const w = toViennaWallClock(new Date());
+    return `${w.year}-${String(w.month).padStart(2, '0')}-${String(w.day).padStart(2, '0')}`;
 }
 function belegArt(wert) {
     const text = typeof wert === 'object' && wert !== null ? wert.value : wert;
@@ -102,12 +271,15 @@ function innen(item, i) {
     if (typeof item.quantity !== 'number' || !Number.isFinite(item.quantity))
         throw new ReceiptDueError('invalid_item', `Position ${i + 1} hat keine gueltige Menge.`);
     const tip = item.kind === 'tip' ? (item.recipient?.owner === true ? 'owner' : 'staff') : null;
-    return { amount: item.quantity, priceOne: Math.round(item.priceCents) / 100, vat: satz, tip };
-}
-function gutscheinInnen(v, i) {
-    if (!Number.isSafeInteger(v.valueCents))
-        throw new ReceiptDueError('invalid_voucher', `Gutschein ${i + 1} hat keinen ganzen Cent-Wert.`);
-    return { action: String(v.action), type: String(v.type), value: Math.round(v.valueCents) / 100 };
+    return {
+        amount: item.quantity,
+        priceOne: Math.round(item.priceCents) / 100,
+        vat: satz,
+        tip,
+        // `kind: null` ist wie keines (der Server prueft `!it.kind`).
+        ...(item.kind != null ? { kind: item.kind } : {}),
+        ...(item.articleId != null ? { articleId: item.articleId } : {}),
+    };
 }
 /** Trinkgeld-Auftraege in der Reihenfolge des Servers: `tip`, dann je Zahlart die Summe der `tipCents`. */
 function trinkgeldAuftraege(options) {
@@ -227,18 +399,6 @@ function splitOwnerTip(cents, jeSatz) {
     return verteilt.map(({ vat, cents: c }) => ({ vat, cents: c }));
 }
 const FUENF = ['amountRateStandard', 'amountRateReduced1', 'amountRateReduced2', 'amountRateZero', 'amountRateSpecial'];
-/** `vat-buckets.bucketFuerSatz`. */
-function topfFuerSatz(vat) {
-    switch (vat) {
-        case 20: return 'amountRateStandard';
-        case 10: return 'amountRateReduced1';
-        case 13: return 'amountRateReduced2';
-        case 0: return 'amountRateZero';
-        case 19: return 'amountRateSpecial';
-        case 4.9: return 'amountRateSpecial';
-        default: return 'amountRatOthers';
-    }
-}
 /** `beleg-toepfe.belegToepfe`, Schritt fuer Schritt. */
 function belegToepfe(positionen, gutscheine) {
     const t = { amountRateStandard: 0, amountRateReduced1: 0, amountRateReduced2: 0, amountRateZero: 0, amountRateSpecial: 0, amountRatOthers: 0 };
@@ -283,17 +443,21 @@ function belegToepfe(positionen, gutscheine) {
         euroToCent(t.amountRateZero) + euroToCent(t.amountRateSpecial) + euroToCent(t.amountRatOthers);
     return { ...t, zaehlerDeltaCents };
 }
-/** `zahlungen-core.wertgutscheinFlussCents`. */
+/**
+ * `zahlungen-core.wertgutscheinFlussCents`: Eintraege im 0-%-Topf
+ * (`imNullTopf`) stehen schon als Position; eine Auszahlung ohne
+ * Topf-Position mindert den Zahlbetrag.
+ */
 function wertgutscheinFlussCents(gutscheine, art) {
     const vz = art === 'cancellation' ? -1 : 1;
     let cents = 0;
     for (const v of gutscheine) {
-        if (v.type !== VoucherType.value || !Number.isFinite(v.value))
+        if (v.type !== VoucherType.value || v.imNullTopf === true || !Number.isFinite(v.value))
             continue;
         const c = euroToCent(v.value);
         if (v.action === VoucherAction.sell)
             cents += c;
-        else if (v.action === VoucherAction.redeem)
+        else if (v.action === VoucherAction.redeem || v.action === VoucherAction.payout)
             cents -= c;
     }
     return vz * cents + 0;

package/dist/esm/receipt/grid.js

@@ -57,10 +57,22 @@ export function renderReceiptGrid(layout, options = {}) {
     const lines = [];
     for (const z of layout.lines) {
         switch (z.kind) {
-            case 'text':
+            case 'text': {
+                // Haengender Einzug: ein linksbuendiger Text mit fuehrenden Leerzeichen
+                // (Vermerke unter einer Gutscheinzeile, „  Grund: …“) bricht mit
+                // demselben Einzug um, auf 32 wie auf 48 Zeichen. Passt er in eine
+                // Zeile, ergibt das dieselben Zeichen wie ohne Einzugsregel.
+                const einzug = z.align === 'left' ? z.text.length - z.text.trimStart().length : 0;
+                if (einzug > 0 && einzug < zeichen && z.text.trimStart() !== '') {
+                    const vorn = ' '.repeat(einzug);
+                    for (const t of wrapText(z.text.slice(einzug), zeichen - einzug))
+                        lines.push({ text: ausrichten(vorn + t, zeichen, 'left'), kind: 'text', bold: z.bold });
+                    break;
+                }
                 for (const t of wrapText(z.text, zeichen))
                     lines.push({ text: ausrichten(t, zeichen, z.align), kind: 'text', bold: z.bold });
                 break;
+            }
             case 'banner': {
                 // Der Rahmen ist Teil des Rasters: eine Zeile '=' ueber die volle Breite
                 // davor und danach. So setzt ihn jeder Weg -- Bildschirm, Bon, ePOS, PDF,

package/dist/esm/receipt/gutschein-plan.d.ts

@@ -0,0 +1,104 @@
+import type { Voucher } from '../models/voucher.js';
+import type { PosVoucherSettings, VoucherArticle, VoucherCheck } from '../pos/gutschein.js';
+/**
+ * Gutscheine der neuen Form im Zahlbetrag: Zwilling von
+ * `gutschein-beleg.plane` im Backend, soweit er den Zahlbetrag bestimmt.
+ *
+ * Der Server macht aus den Wuenschen zusaetzliche Positionen (`kind`
+ * `voucher` bzw. `voucher_float`, hinten an Ware und Trinkgeld angehaengt, in
+ * der Reihenfolge der Wuensche) und Eintraege in Belegform; nur Eintraege der
+ * Art Wert (`value`) und Rabatt (`promo`) gehen danach in die Toepfe und in
+ * den Wertgutschein-Fluss (`gutschein-beleg.zahlbetrag`). Genau das steht
+ * hier, mit derselben Euro-Arithmetik:
+ *
+ * - Mehrzweck einloesen: Eintrag `value`, mindert den Zahlbetrag als Fluss.
+ * - Mehrzweck verkaufen: Eintrag `value` (+Fluss); ab dem Stichtag des
+ *   0-%-Topfs stattdessen Position im 0-%-Satz ohne Fluss.
+ * - Mehrzweck auszahlen: immer Position im 0-%-Satz (minus), kein Fluss.
+ * - Einzweck: Position im Satz (Verkauf aus der Einstellung der Kasse,
+ *   Einloesung und Auszahlung aus der Pruefung des Gutscheins); als
+ *   Kleinunternehmer eingeloest anteilig auf alle Saetze des Korbs.
+ * - Leistung verkaufen: Stueck mal Artikelpreis im Artikelsatz; einloesen: je
+ *   Satz eine Minuszeile ueber die gewaehlten Positionen.
+ * - Aktion: Rabatt wie `promo`, Betrag aus der Pruefung, hoechstens die Summe.
+ *
+ * Kein Fehler wird still geschluckt: was der Server mit einem Gutschein-Code
+ * abwiese, liefert `fehler` mit genau diesem Code (`voucher_*`). Der
+ * Klartext-Code steht nie in einem Text.
+ */
+/** Position in der inneren Form des Backends (`beleg-toepfe.interneForm`). */
+export interface Innen {
+    amount: number;
+    priceOne: number;
+    vat: number;
+    tip: 'staff' | 'owner' | null;
+    /** `kind` der Position (Trinkgeld, Rabatt, Gutscheinzeile); Ware hat keines. */
+    kind?: string;
+    articleId?: string;
+}
+/** Gutschein-Eintrag in Belegform, soweit Toepfe und Fluss ihn lesen. */
+export interface Gutschein {
+    action: string;
+    type: string;
+    value: number;
+    /** Betrag steht schon als Position im 0-%-Topf: kein Fluss mehr. */
+    imNullTopf?: boolean;
+}
+/** Je Einloesung bzw. Auszahlung die gepruefte Sicht des Gutscheins (aus `checkVoucher`), zugeordnet ueber den Code. */
+export interface VoucherDueInfo {
+    /** Der Code, wie er gesendet wird (tolerant: Gross/klein, Bindestriche, `O`/`0`, `I`/`L`/`1`). */
+    code: string;
+    check: VoucherCheck;
+}
+/** Artikel fuer den Verkauf eines Dienstleistungsgutscheins: Preis und Satz wie im Artikelstamm. */
+export type VoucherDueArticle = Pick<VoucherArticle, 'id' | 'priceCents' | 'vatRateBp'>;
+/**
+ * Stichtag des 0-%-Topfs fuer Mehrzweck-Verkaeufe (Backend
+ * `gutschein-core.NULLTOPF_AB`). Solange er in der Zukunft liegt, zaehlt ein
+ * Mehrzweck-Verkauf als Fluss; ab dem Tag als Position im 0-%-Satz. Der
+ * Zahlbetrag bleibt gleich, Toepfe und Fluss verschieben sich.
+ */
+export declare const VOUCHER_ZERO_RATE_BUCKET_FROM = "2099-12-31";
+export interface PlanOptionen {
+    voucherInfo?: readonly VoucherDueInfo[];
+    voucherSettings?: PosVoucherSettings;
+    voucherArticles?: readonly VoucherDueArticle[];
+    smallBusiness?: boolean;
+    zeroRateBucketFrom?: string;
+    /** Wiener Tag `YYYY-MM-DD`; der Aufrufer setzt den heutigen, wenn er fehlt. */
+    today: string;
+}
+export interface Plan {
+    /** Positionen, die der Server hinten anhaengt. */
+    zusatz: Innen[];
+    /** Eintraege, die Toepfe und Fluss lesen (`gutschein-beleg.zahlbetrag`). */
+    gutscheine: Gutschein[];
+    /** Summe der Auszahlungen in Cent. */
+    auszahlungCents: number;
+    /** Mindestens ein Wunsch der neuen Form: der Server rechnet mit `plane`. */
+    mitPlan: boolean;
+    /** Summe der Einloese-Minuszeilen je Topf (Deckung, Vorbelegung). */
+    minusJeTopf: Map<string, number>;
+}
+export interface PlanFehler {
+    fehler: string;
+    text: string;
+}
+type TopfName = 'amountRateStandard' | 'amountRateReduced1' | 'amountRateReduced2' | 'amountRateZero' | 'amountRateSpecial' | 'amountRatOthers';
+/** `vat-buckets.bucketFuerSatz`. */
+export declare function topfFuerSatz(vat: number): TopfName;
+/** Position, die ein Gutschein decken darf: weder Trinkgeld noch Gutscheinzeile. */
+export declare function istDeckbar(p: Innen): boolean;
+/** Wie beleg-toepfe: Euro in Positionsreihenfolge aufsummieren, erst die Summe auf Cent runden. */
+export declare function centSumme(liste: readonly Innen[]): number;
+/** Die Saetze, auf die `kuTeile` verteilt: je Satz `centSumme` der deckbaren Positionen, nur positive. */
+export declare function kuSaetze(kunde: readonly Innen[]): Array<{
+    satzBp: number;
+    basis: number;
+}>;
+/**
+ * Wuensche und gelesene Eintraege in Positionen und Belegeintraege, wie
+ * `plane` sie baut. `kunde` sind Ware und Trinkgeld in innerer Form.
+ */
+export declare function planeGutscheine(kunde: readonly Innen[], vouchers: readonly Voucher[], art: string, o: PlanOptionen): Plan | PlanFehler;
+export {};