@kreiseck/kasseneck-api 1.11.0 → 1.12.0

package/dist/esm/receipt/gutschein-plan.js

@@ -0,0 +1,352 @@
+import { VoucherCode } from '@kreiseck/validator';
+import { isNewFormVoucher, voucherIsValid, voucherServerFields } from '../models/voucher.js';
+/**
+ * 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 const VOUCHER_ZERO_RATE_BUCKET_FROM = '2099-12-31';
+const KINDS = ['voucher', 'voucher_float'];
+const ARTEN = ['multi_purpose', 'single_purpose', 'service', 'promotion'];
+/** `vat-buckets.bucketFuerSatz`. */
+export 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';
+    }
+}
+const TOPF_REIHENFOLGE = ['amountRateStandard', 'amountRateReduced1', 'amountRateReduced2', 'amountRateZero', 'amountRateSpecial', 'amountRatOthers'];
+function istGutscheinZeile(p) {
+    return p.kind !== undefined && KINDS.includes(p.kind);
+}
+/** Position, die ein Gutschein decken darf: weder Trinkgeld noch Gutscheinzeile. */
+export function istDeckbar(p) {
+    return p.tip == null && p.kind !== 'tip' && !istGutscheinZeile(p);
+}
+/** Wie beleg-toepfe: Euro in Positionsreihenfolge aufsummieren, erst die Summe auf Cent runden. */
+export function centSumme(liste) {
+    return Math.round(liste.reduce((s, it) => s + it.priceOne * it.amount, 0) * 100);
+}
+/** `gutschein-core.satzBpAusVat`. */
+function satzBp(vat) {
+    return Math.round(Number(vat) * 100);
+}
+function position(satzBpWert, cents, kind) {
+    return { amount: 1, priceOne: cents / 100, vat: satzBpWert / 100, tip: null, kind };
+}
+/** Code in Normalform (tolerant eingelesen, Pruefzeichen stimmt) oder null. */
+function normalerCode(code) {
+    if (typeof code !== 'string')
+        return null;
+    const v = VoucherCode.validate(code);
+    return v.ok ? v.normalized : null;
+}
+/** Ist der Eintrag ein Wunsch der neuen Form (nicht vom Server gelesen)? */
+function istWunsch(v) {
+    return isNewFormVoucher(v) && voucherServerFields(v).length === 0;
+}
+/** Ein gelesener Eintrag (Serverfelder gesetzt): nur Wert und Rabatt tragen Geld ausserhalb der Positionen. */
+function istGelesen(v) {
+    return voucherServerFields(v).length > 0;
+}
+const STATUS_FEHLER = {
+    used_up: 'voucher_used_up', paid_out: 'voucher_used_up', cancelled: 'voucher_cancelled', blocked: 'voucher_blocked', expired: 'voucher_expired',
+};
+/** Die Saetze, auf die `kuTeile` verteilt: je Satz `centSumme` der deckbaren Positionen, nur positive. */
+export function kuSaetze(kunde) {
+    const jeSatz = new Map();
+    for (const it of kunde) {
+        if (!istDeckbar(it))
+            continue;
+        const s = satzBp(it.vat);
+        if (!jeSatz.has(s))
+            jeSatz.set(s, []);
+        jeSatz.get(s).push(it);
+    }
+    return [...jeSatz].map(([s, liste]) => ({ satzBp: s, basis: centSumme(liste) })).filter((x) => x.basis > 0);
+}
+/** `gutschein-core.kuTeile`: anteilig zur Positionssumme je Satz, groesster Rest, Topf-Reihenfolge bei Gleichstand. */
+function kuTeile(kunde, betragCents) {
+    const jeSatz = new Map();
+    for (const it of kunde) {
+        if (!istDeckbar(it))
+            continue;
+        const s = satzBp(it.vat);
+        if (!jeSatz.has(s))
+            jeSatz.set(s, []);
+        jeSatz.get(s).push(it);
+    }
+    const rang = (s) => TOPF_REIHENFOLGE.indexOf(topfFuerSatz(s / 100));
+    const saetze = [...jeSatz]
+        .map(([s, liste]) => ({ satzBp: s, basis: centSumme(liste), cents: 0, rest: 0 }))
+        .filter((s) => s.basis > 0)
+        .sort((a, b) => (rang(a.satzBp) - rang(b.satzBp)) || (b.satzBp - a.satzBp));
+    const summe = saetze.reduce((s, x) => s + x.basis, 0);
+    if (summe <= 0 || betragCents > summe)
+        return null;
+    for (const s of saetze) {
+        s.cents = Math.floor((betragCents * s.basis) / summe);
+        s.rest = (betragCents * s.basis) % summe;
+    }
+    let offen = betragCents - saetze.reduce((s, x) => s + x.cents, 0);
+    const nachRest = saetze.map((s, i) => ({ s, i })).sort((a, b) => (b.s.rest - a.s.rest) || (a.i - b.i));
+    for (let k = 0; offen > 0; k++, offen--)
+        nachRest[k].s.cents += 1;
+    return saetze.filter((s) => s.cents > 0).map((s) => ({ satzBp: s.satzBp, cents: s.cents }));
+}
+/**
+ * Wuensche und gelesene Eintraege in Positionen und Belegeintraege, wie
+ * `plane` sie baut. `kunde` sind Ware und Trinkgeld in innerer Form.
+ */
+export function planeGutscheine(kunde, vouchers, art, o) {
+    const nein = (fehler, text) => ({ fehler, text });
+    const storno = art === 'cancellation';
+    const wuensche = vouchers.filter(istWunsch);
+    const zusatz = [];
+    const gutscheine = [];
+    // Wert und Rabatt der Altform bzw. gelesener Belege: Euro aus ganzen Cent.
+    const altEintrag = (v, i) => {
+        if (!Number.isSafeInteger(v.valueCents))
+            return nein('voucher_invalid', `Gutschein ${i + 1} hat keinen ganzen Cent-Wert.`);
+        return { action: String(v.action), type: String(v.type), value: Math.round(v.valueCents) / 100, ...(v.zeroRateBucket === true ? { imNullTopf: true } : {}) };
+    };
+    if (wuensche.length === 0) {
+        const nulltopf = !storno && o.today >= (o.zeroRateBucketFrom ?? VOUCHER_ZERO_RATE_BUCKET_FROM);
+        // `gutschein-transaktion.brauchtPlan`: ab dem Stichtag laeuft plane auch fuer einen Altform-Verkauf.
+        const mitPlan = nulltopf && vouchers.some((v) => !istGelesen(v) && v.action === 'sell' && v.type === 'value');
+        if (mitPlan && kunde.some(istGutscheinZeile))
+            return nein('voucher_invalid', 'Gutschein-Positionen setzt nur der Server.');
+        for (const [i, v] of vouchers.entries()) {
+            // Gelesene Eintraege der neuen Form ohne Wert/Rabatt: ihr Geld steht in den Positionen.
+            if (istGelesen(v) && v.type !== 'value' && v.type !== 'promo')
+                continue;
+            const g = altEintrag(v, i);
+            if ('fehler' in g)
+                return g;
+            // Altform-Verkauf ab dem Stichtag: Betrag in den 0-%-Topf.
+            if (nulltopf && !istGelesen(v) && g.action === 'sell' && g.type === 'value') {
+                zusatz.push(position(0, Math.round(v.valueCents), 'voucher_float'));
+                g.imNullTopf = true;
+            }
+            gutscheine.push(g);
+        }
+        return { zusatz, gutscheine, auszahlungCents: 0, mitPlan, minusJeTopf: new Map() };
+    }
+    // Ab hier: mindestens ein Wunsch der neuen Form (createReceipt fuehrt `plane` aus).
+    if (storno)
+        return nein('voucher_invalid', 'Gutscheine der neuen Form gibt es am Storno nur gespiegelt vom Server.');
+    if (art === 'training')
+        return nein('voucher_invalid', 'Gutscheine der neuen Form gibt es nicht auf Schulungsbelegen.');
+    if (kunde.some(istGutscheinZeile))
+        return nein('voucher_invalid', 'Gutschein-Positionen setzt nur der Server.');
+    for (const [i, v] of vouchers.entries()) {
+        if (istGelesen(v))
+            return nein('voucher_invalid', `Gutschein ${i + 1}: Serverfelder an einem Wunsch.`);
+        if (isNewFormVoucher(v) && !voucherIsValid(v))
+            return nein('voucher_invalid', `Gutschein ${i + 1} ist unvollstaendig.`);
+    }
+    // Kein Gutschein mit Gutschein bezahlen, sobald einer der beiden die neue Form hat.
+    const handel = vouchers.filter((v) => v.action === 'sell' || v.action === 'redeem');
+    if (handel.some((v) => v.action === 'sell') && handel.some((v) => v.action === 'redeem') && handel.some(isNewFormVoucher))
+        return nein('voucher_invalid', 'Gutscheine verkaufen und einloesen gehen nicht am selben Beleg.');
+    if (wuensche.some((v) => v.type === 'promotion') && vouchers.length > 1)
+        return nein('voucher_invalid', 'Ein Aktionsgutschein steht allein am Beleg.');
+    if (wuensche.some((v) => v.action === 'payout') && vouchers.some((v) => !isNewFormVoucher(v) && v.type === 'promo')) {
+        return nein('voucher_invalid', 'Rabatt und Auszahlung gehen nicht am selben Beleg.');
+    }
+    const codes = wuensche.filter((v) => v.action !== 'sell').map((v) => normalerCode(v.code));
+    if (codes.some((c) => c == null))
+        return nein('voucher_invalid', 'Ein Gutscheincode ist ungueltig.');
+    if (new Set(codes).size !== codes.length)
+        return nein('voucher_invalid', 'Derselbe Gutschein steht zweimal am Beleg.');
+    const ku = o.smallBusiness === true;
+    const nulltopf = o.today >= (o.zeroRateBucketFrom ?? VOUCHER_ZERO_RATE_BUCKET_FROM);
+    const minusJeTopf = new Map();
+    const minus = (s, c) => {
+        const topf = topfFuerSatz(s / 100);
+        minusJeTopf.set(topf, (minusJeTopf.get(topf) ?? 0) + c);
+    };
+    const belegt = new Set();
+    let auszahlungCents = 0;
+    const einstellung = (gewollt) => {
+        const e = o.voucherSettings;
+        // Der Server verkauft nur mit bestaetigter Einstellung (`voucher_settings_missing`), auch Mehrzweck.
+        if (e == null || e.valueVoucherType == null) {
+            return nein('voucher_settings_missing', 'Die Gutschein-Einstellung der Kasse fehlt (voucherSettings).');
+        }
+        return e.valueVoucherType === gewollt ? null : nein('voucher_invalid', 'Die Gutschein-Einstellung der Kasse verkauft eine andere Art.');
+    };
+    const pruefung = (v, i) => {
+        const code = normalerCode(v.code);
+        const info = (o.voucherInfo ?? []).find((x) => normalerCode(x.code) === code);
+        if (info == null)
+            return nein('voucher_not_found', `Gutschein ${i + 1}: keine Pruefung zum Code (checkVoucher).`);
+        if (info.check.type !== v.type)
+            return nein('voucher_invalid', `Gutschein ${i + 1}: die Art passt nicht zur Pruefung.`);
+        return info.check;
+    };
+    const saldo = (check, c, i) => Number.isInteger(check.balanceCents) && c <= check.balanceCents
+        ? null
+        : nein('voucher_insufficient_balance', `Gutschein ${i + 1}: der Betrag uebersteigt den Saldo.`);
+    for (const [i, v] of vouchers.entries()) {
+        if (!isNewFormVoucher(v)) {
+            const g = altEintrag(v, i);
+            if ('fehler' in g)
+                return g;
+            if (nulltopf && g.action === 'sell' && g.type === 'value') {
+                zusatz.push(position(0, Math.round(v.valueCents), 'voucher_float'));
+                g.imNullTopf = true;
+            }
+            gutscheine.push(g);
+            continue;
+        }
+        if (!ARTEN.includes(String(v.type)))
+            return nein('voucher_invalid', `Gutschein ${i + 1}: unbekannte Art.`);
+        if (v.action === 'sell') {
+            if (v.type === 'multi_purpose') {
+                const f = einstellung('multi_purpose');
+                if (f)
+                    return f;
+                const c = v.amountCents;
+                if (nulltopf) {
+                    zusatz.push(position(0, c, 'voucher_float'));
+                    gutscheine.push({ action: 'sell', type: 'value', value: c / 100, imNullTopf: true });
+                }
+                else {
+                    gutscheine.push({ action: 'sell', type: 'value', value: c / 100 });
+                }
+            }
+            else if (v.type === 'single_purpose') {
+                const f = einstellung('single_purpose');
+                if (f)
+                    return f;
+                const satz = ku ? 0 : o.voucherSettings.vatRateBp;
+                if (!Number.isInteger(satz) || satz < 0)
+                    return nein('voucher_settings_missing', 'Der Satz des Einzweckgutscheins fehlt (Gutschein-Einstellung der Kasse).');
+                zusatz.push(position(satz, v.amountCents, 'voucher'));
+            }
+            else {
+                const a = (o.voucherArticles ?? []).find((x) => x.id === v.articleId);
+                if (a == null)
+                    return nein('voucher_item_mismatch', `Gutschein ${i + 1}: der Artikel fehlt (voucherArticles).`);
+                if (!Number.isInteger(a.priceCents) || a.priceCents <= 0 || !Number.isInteger(a.vatRateBp) || a.vatRateBp < 0) {
+                    return nein('voucher_invalid', `Gutschein ${i + 1}: Artikel ohne Preis oder Satz.`);
+                }
+                const c = v.quantity * a.priceCents;
+                if (c > 1_000_000)
+                    return nein('voucher_invalid', `Gutschein ${i + 1}: Betrag zu hoch.`);
+                zusatz.push(position(ku ? 0 : a.vatRateBp, c, 'voucher'));
+            }
+            continue;
+        }
+        const check = pruefung(v, i);
+        if ('fehler' in check)
+            return check;
+        if (v.action === 'payout') {
+            // `gutschein-core.darfAuszahlen`: aktiv, oder abgelaufen bis zum Ende der Rueckzahlbarkeit.
+            if (!((check.balanceCents ?? 0) > 0))
+                return nein('voucher_used_up', `Gutschein ${i + 1}: kein Saldo.`);
+            if (check.status === 'expired') {
+                const bis = check.validity?.refundableUntil;
+                if (bis && o.today > bis)
+                    return nein('voucher_expired', `Gutschein ${i + 1}: nicht mehr rueckzahlbar.`);
+            }
+            else if (check.status !== 'active') {
+                return nein(STATUS_FEHLER[check.status] ?? 'voucher_invalid', `Gutschein ${i + 1}: Status ${check.status}.`);
+            }
+            const c = v.amountCents;
+            const f = saldo(check, c, i);
+            if (f)
+                return f;
+            if (v.type === 'multi_purpose') {
+                zusatz.push(position(0, -c, 'voucher_float'));
+                gutscheine.push({ action: 'payout', type: 'value', value: c / 100, imNullTopf: true });
+            }
+            else {
+                if (!Number.isInteger(check.vatRateBp))
+                    return nein('voucher_invalid', `Gutschein ${i + 1}: Satz fehlt in der Pruefung.`);
+                zusatz.push(position(check.vatRateBp, -c, 'voucher'));
+            }
+            auszahlungCents += c;
+            continue;
+        }
+        if (check.status !== 'active')
+            return nein(STATUS_FEHLER[check.status] ?? 'voucher_invalid', `Gutschein ${i + 1}: Status ${check.status}.`);
+        if (v.type === 'multi_purpose' || v.type === 'single_purpose') {
+            const c = v.amountCents;
+            const f = saldo(check, c, i);
+            if (f)
+                return f;
+            if (v.type === 'multi_purpose') {
+                gutscheine.push({ action: 'redeem', type: 'value', value: c / 100 });
+            }
+            else if (check.exempt === true || ku) {
+                // Befreit verkauft (`kuEingefroren`) oder Kleinunternehmer-Konto: der gedeckte Teil
+                // verlaesst anteilig alle Toepfe des Korbs.
+                const teile = kuTeile(kunde, c);
+                if (!teile)
+                    return nein('voucher_rate_mismatch', `Gutschein ${i + 1}: der Korb deckt den Betrag nicht.`);
+                for (const t of teile) {
+                    zusatz.push(position(t.satzBp, -t.cents, 'voucher'));
+                    minus(t.satzBp, t.cents);
+                }
+            }
+            else {
+                if (!Number.isInteger(check.vatRateBp))
+                    return nein('voucher_invalid', `Gutschein ${i + 1}: Satz fehlt in der Pruefung.`);
+                zusatz.push(position(check.vatRateBp, -c, 'voucher'));
+                minus(check.vatRateBp, c);
+            }
+        }
+        else if (v.type === 'service') {
+            const artikelId = check.article?.id;
+            let stueck = 0;
+            const jeSatz = new Map();
+            for (const k of v.positions ?? []) {
+                const it = kunde[k];
+                if (it == null || it.kind !== undefined || it.tip != null || !artikelId || it.articleId !== artikelId
+                    || !Number.isInteger(it.amount) || it.amount < 1 || belegt.has(k)) {
+                    return nein('voucher_item_mismatch', `Gutschein ${i + 1}: Position ${k + 1} passt nicht zum Leistungsgutschein.`);
+                }
+                belegt.add(k);
+                stueck += it.amount;
+                const s = satzBp(it.vat);
+                if (!jeSatz.has(s))
+                    jeSatz.set(s, []);
+                jeSatz.get(s).push(it);
+            }
+            if (!Number.isInteger(check.remainingQuantity) || stueck > check.remainingQuantity) {
+                return nein('voucher_insufficient_balance', `Gutschein ${i + 1}: nicht genug offene Stueck.`);
+            }
+            for (const [s, liste] of jeSatz) {
+                const c = centSumme(liste);
+                zusatz.push(position(s, -c, 'voucher'));
+                minus(s, c);
+            }
+        }
+        else {
+            // Aktion: Rabatt ueber die Altmechanik promo.
+            const basis = centSumme(kunde.filter(istDeckbar));
+            const roh = Number.isInteger(check.discountCents) && check.discountCents > 0
+                ? check.discountCents
+                : Math.floor((basis * (Number(check.discountPercentBp) || 0)) / 10000);
+            const rabatt = Math.min(roh, basis);
+            if (!(rabatt > 0))
+                return nein('voucher_invalid', `Gutschein ${i + 1}: kein Rabatt auf diesen Korb.`);
+            gutscheine.push({ action: 'redeem', type: 'promo', value: rabatt / 100 });
+        }
+    }
+    // Einloese-Minuszeilen eines Topfs uebersteigen nie die deckbaren Positionen dieses Topfs.
+    for (const [topf, c] of minusJeTopf) {
+        const basis = centSumme(kunde.filter((it) => istDeckbar(it) && topfFuerSatz(it.vat) === topf));
+        if (c > basis)
+            return nein('voucher_rate_mismatch', 'Ein Gutschein deckt mehr als die Positionen seines Steuersatzes.');
+    }
+    return { zusatz, gutscheine, auszahlungCents, mitPlan: true, minusJeTopf };
+}

package/dist/esm/receipt/index.d.ts

@@ -7,4 +7,4 @@ export { rasterizeLogo } from './bild.js';
 export { type BrandMarkRaster, BRAND_MARK_RASTERS, BRAND_MARK_PATHS } from './marke-daten.js';
 export { brandMarkImage } from './marke.js';
 export { type CodeTableTestSheetInput, type CodeTableTestSheetRow, type CodeTableTestSheet, CODE_TABLE_TEST_SHEET_CHARS, codeTableTestSheet, codeTableTestSheetBytes, codeTableReferenceImage, } from './code-table-test-sheet.js';
-export { type ReceiptDueTip, type ReceiptDueTipRecipient, type ReceiptDueOptions, type ReceiptDueBuckets, type ReceiptDueBreakdown, type ReceiptDueErrorReason, receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, } from './due.js';
+export { type ReceiptDueTip, type ReceiptDueTipRecipient, type ReceiptDueOptions, type ReceiptDueBuckets, type ReceiptDueBreakdown, type ReceiptDueErrorReason, receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, type VoucherDueInfo, type VoucherDueArticle, type VoucherRedeemContext, voucherRedeemMaxCents, VOUCHER_ZERO_RATE_BUCKET_FROM, } from './due.js';

package/dist/esm/receipt/index.js

@@ -7,4 +7,4 @@ export { rasterizeLogo } from './bild.js';
 export { BRAND_MARK_RASTERS, BRAND_MARK_PATHS } from './marke-daten.js';
 export { brandMarkImage } from './marke.js';
 export { CODE_TABLE_TEST_SHEET_CHARS, codeTableTestSheet, codeTableTestSheetBytes, codeTableReferenceImage, } from './code-table-test-sheet.js';
-export { receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, } from './due.js';
+export { receiptDueCents, receiptDueBreakdown, ReceiptDueError, RECEIPT_DUE_ERROR_REASONS, isReceiptDueError, voucherRedeemMaxCents, VOUCHER_ZERO_RATE_BUCKET_FROM, } from './due.js';

package/dist/esm/receipt/layout.js

@@ -1,5 +1,5 @@
 import { VatRate, VoucherAction, VoucherType } from '../enums/index.js';
-import { CANCELLATION_REASONS, isCancellationReason, receiptCompanyTaxInfo, receiptItemTotalCents, isDiscountItem, isTipItem, receiptSubSumCents, receiptSumCents, voucherIsValid, } from '../models/index.js';
+import { CANCELLATION_REASONS, isCancellationReason, receiptCompanyTaxInfo, receiptItemTotalCents, isDiscountItem, isTipItem, receiptSubSumCents, receiptSumCents, receiptValueVoucherSign, voucherIsValid, } from '../models/index.js';
 import { parseServerTimeStamp, toViennaWallClock } from '../vienna-time.js';
 import { KasseneckValidationError } from '../client/errors.js';
 export const CURRENT_LAYOUT_RULESET = 2;
@@ -561,6 +561,152 @@ function gutscheinText(voucher) {
     }
     return text;
 }
+/*
+ * Gutscheine der neuen Form (Spec 2026-10-14, „Bon und Beleg“). Der Dart-
+ * Zwilling uebernimmt Texte und Spaltenbreiten (Zwoelftel) genau so:
+ *
+ *   Verkauf Einzweck/Leistung  Positionszeile 7:5 „1  x <Name> <Code>“ | „50,00 A“
+ *   Verkauf Mehrzweck          dieselbe Zeile (Position im 0-%-Topf oder, vor dem
+ *                              Stichtag, aus dem Eintrag) + Text „  USt bei Einlösung“
+ *   Einloesung Einzweck/       8:4 „Gutschein ····-9DWT“ | „-30,50 A“, nach der letzten
+ *   Leistung                   Zeile dieses Gutscheins Text „  Einzweck, versteuert mit
+ *                              Beleg K1-ID-4711“ (bzw. „Leistung, …“, „…, befreit
+ *                              verkauft (Kleinunternehmer)“, 47 Zeichen: passt auf
+ *                              80 mm) und 8:4 „  Rest am Gutschein“ | „19,50  “ bzw.
+ *                              „2 Stück“
+ *   Einloesung Mehrzweck       nach „Zwischensumme“ 8:4 „Gutschein ····-9DWT“ |
+ *                              „-17,50 €“ und „  Rest am Gutschein“ | „32,50 €“
+ *   Auszahlung                 8:4 „Auszahlung Gutschein ····-9DWT“ | „-12,00 D“,
+ *                              Text „  Grund: <Grund>“
+ *   Aktion                     Rabattzeile wie bisher (Promotionsgutschein)
+ *
+ * Vermerke sind Textzeilen mit zwei fuehrenden Leerzeichen; das Raster bricht
+ * sie mit demselben Einzug um (grid.ts, haengender Einzug), auf 58 mm etwa
+ * „  Einzweck, versteuert mit“ / „  Beleg K1-ID-4711“.
+ *
+ * Die Zusatzzeilen kommen nur aus dem Eintrag: ein Beleg, den der Server fuer
+ * ein aelteres Paket aufbereitet hat (Eintraege mit Position entfernt, Code an
+ * der Position, functions/beleg-layout.js `gutscheineFuerPaket`), zeigt seine
+ * Positionen wie jede andere Position. Ein Betrag zaehlt immer genau einmal:
+ * Positionen in der Steuertabelle, Eintraege mit `zeroRateBucket` nie.
+ */
+/** Steht der Betrag des Eintrags als Position am Beleg (Einzweck, Leistung, 0-%-Topf)? */
+function gutscheinStehtAlsPosition(voucher) {
+    return voucher.type === VoucherType.single_purpose || voucher.type === VoucherType.service || voucher.zeroRateBucket === true;
+}
+/** Mehrzweckgutschein mit Code (Altart `value`, vom Server als `multi_purpose` gekennzeichnet). */
+function istMehrzweckMitCode(voucher) {
+    return voucher.type === VoucherType.value && voucher.voucherType === VoucherType.multi_purpose;
+}
+/**
+ * Code fuer die Belegzeile: die Maske des Eintrags, ohne den Platzhalter
+ * `no-code`, den der Server Alt-Eintraegen ohne Code setzt (index.js
+ * checkVouchersIsValid). Leer, wenn es keinen gibt.
+ */
+function gutscheinCodeZusatz(voucher) {
+    return typeof voucher.code === 'string' && voucher.code !== '' && voucher.code !== 'no-code' ? ` ${voucher.code}` : '';
+}
+/** Die vier letzten Zeichen des Codes (`codeSuffix`, sonst aus der Maske), oder null. */
+function gutscheinEndung(voucher) {
+    if (typeof voucher.codeSuffix === 'string' && voucher.codeSuffix !== '')
+        return voucher.codeSuffix;
+    return typeof voucher.code === 'string' && voucher.code.length >= 4 && voucher.code !== 'no-code' ? voucher.code.slice(-4) : null;
+}
+const MEHRZWECK_UST_TEXT = '  USt bei Einlösung';
+/**
+ * Welche Gutscheinposition (`voucher`/`voucher_float`) gehoert zu welchem
+ * Eintrag? Jede Position hoechstens einem Eintrag, Eintraege in ihrer
+ * Reihenfolge (der Server haengt die Positionen in derselben Reihenfolge an).
+ * Verkauf: erste freie Position der Art mit demselben Betrag und ohne Code im
+ * Namen (wie `gutscheineFuerPaket` des Servers). Einloesung: freie Positionen
+ * mit genau dem Namen `Gutschein ····-<Endung>`, Auszahlung: `Auszahlung
+ * Gutschein ····-<Endung>` (gutschein-beleg.plane) -- der Reihe nach, bis
+ * ihr Betrag den des Eintrags erreicht (ein Kleinunternehmer-Einzweck oder
+ * eine Leistung ueber mehrere Saetze hat je Satz eine Position; zwei
+ * Gutscheine mit derselben Endung teilen sich so nie eine Position). Ohne
+ * Betrag am Eintrag genau eine Position.
+ */
+function gutscheinPositionen(receipt) {
+    const zuordnung = new Map();
+    const istGutscheinzeile = (it) => it.kind === 'voucher' || it.kind === 'voucher_float';
+    for (const voucher of receipt.vouchers) {
+        if (!gutscheinStehtAlsPosition(voucher))
+            continue;
+        if (voucher.action === VoucherAction.sell) {
+            const art = voucher.zeroRateBucket === true ? 'voucher_float' : 'voucher';
+            const cents = Number.isInteger(voucher.amountCents) ? Math.abs(voucher.amountCents) : Math.abs(voucher.valueCents ?? 0);
+            const i = receipt.items.findIndex((it, k) => !zuordnung.has(k) && it.kind === art
+                && Math.abs(receiptItemTotalCents(it)) === cents && !it.name.includes('····'));
+            if (i >= 0)
+                zuordnung.set(i, { voucher, letzte: true });
+            continue;
+        }
+        const endung = gutscheinEndung(voucher);
+        if (endung == null || (voucher.action !== VoucherAction.redeem && voucher.action !== VoucherAction.payout))
+            continue;
+        const name = `${voucher.action === VoucherAction.payout ? 'Auszahlung ' : ''}Gutschein ····-${endung}`;
+        const ziel = Number.isInteger(voucher.amountCents) ? Math.abs(voucher.amountCents) : Math.abs(voucher.valueCents ?? 0);
+        const genommen = [];
+        let summe = 0;
+        receipt.items.forEach((it, k) => {
+            if (zuordnung.has(k) || !istGutscheinzeile(it) || it.name !== name)
+                return;
+            if (genommen.length > 0 && (ziel <= 0 || summe >= ziel))
+                return;
+            genommen.push(k);
+            summe += Math.abs(receiptItemTotalCents(it));
+        });
+        genommen.forEach((k, n) => zuordnung.set(k, { voucher, letzte: n === genommen.length - 1 }));
+    }
+    return zuordnung;
+}
+/**
+ * Zeilen einer Gutscheinposition mit ihrem Eintrag. Verkauf als gewoehnliche
+ * Positionszeile mit dem Code des Eintrags; Einloesung und Auszahlung ohne
+ * Menge in der Breite der Rabattzeilen (8:4), damit „Gutschein ····-9DWT“ auch
+ * auf 58 mm in einer Zeile steht.
+ */
+function gutscheinPositionsZeilen(item, satz, zu) {
+    const v = zu.voucher;
+    if (v.action === VoucherAction.sell) {
+        const zeilen = [positionsZeile({ ...item, name: `${item.name}${gutscheinCodeZusatz(v)}` }, satz)];
+        if (v.type === VoucherType.value)
+            zeilen.push(textZeile(MEHRZWECK_UST_TEXT));
+        return zeilen;
+    }
+    const zeilen = [{
+            kind: 'columns',
+            columns: [
+                { text: item.name, width: 8, align: 'left' },
+                { text: `${formatCents(receiptItemTotalCents(item))} ${satz.category}`, width: 4, align: 'right' },
+            ],
+        }];
+    if (!zu.letzte)
+        return zeilen;
+    if (v.action === VoucherAction.payout) {
+        const grund = typeof v.reason === 'string' ? v.reason.trim() : '';
+        if (grund !== '')
+            zeilen.push(textZeile(`  Grund: ${grund}`));
+        return zeilen;
+    }
+    const art = v.type === VoucherType.service ? 'Leistung' : 'Einzweck';
+    if (typeof v.taxedWith === 'string' && v.taxedWith !== '') {
+        zeilen.push(textZeile(`  ${art}, versteuert mit Beleg ${v.taxedWith}`));
+    }
+    else if (v.exempt === true) {
+        zeilen.push(textZeile(`  ${art}, befreit verkauft (Kleinunternehmer)`));
+    }
+    // Rest: Betrag fluchtet mit den Positionsbetraegen (zwei Zeichen statt
+    // „ A“), Stueck rechtsbuendig. Die Gesamtzahl kennt der Beleg nicht.
+    if (v.type === VoucherType.service) {
+        if (Number.isInteger(v.remainingQuantityAfter))
+            zeilen.push(paarZeile('  Rest am Gutschein', `${v.remainingQuantityAfter} Stück`, 8, 4));
+    }
+    else if (Number.isInteger(v.balanceAfterCents)) {
+        zeilen.push(paarZeile('  Rest am Gutschein', `${formatCents(v.balanceAfterCents)}  `, 8, 4));
+    }
+    return zeilen;
+}
 // ----------------------------------------------------------------- Bauteile
 function textZeile(text, align = 'left', bold = false) {
     return { kind: 'text', text, align, bold };
@@ -905,13 +1051,15 @@ export function buildReceiptLayout(receipt, company, options = {}) {
         .filter((it) => !isTipItem(it) && !isDiscountItem(it))
         .reduce((summe, it) => summe + receiptItemTotalCents(it), 0);
     let zwischensummeGezeigt = false;
+    const gutscheinZuordnung = gutscheinPositionen(receipt);
     let i = 0;
     while (i < receipt.items.length) {
         const item = receipt.items[i];
         if (!isTipItem(item) && !isDiscountItem(item)) {
             const satz = steuersatz(item.vat);
             gruppeVon(satz).bruttoCents += receiptItemTotalCents(item);
-            lines.push(positionsZeile(item, satz));
+            const gutschein = gutscheinZuordnung.get(i);
+            lines.push(...(gutschein ? gutscheinPositionsZeilen(item, satz, gutschein) : [positionsZeile(item, satz)]));
             i += 1;
             continue;
         }
@@ -946,28 +1094,44 @@ export function buildReceiptLayout(receipt, company, options = {}) {
     }
     // --- Gutscheine: verkaufte Wertgutscheine sind Umsatz zu 0 %, eingeloeste
     //     Promotionsgutscheine mindern die Steuergruppen anteilig.
+    //     Am Storno-Beleg zaehlen Wertgutscheine mit umgekehrtem Vorzeichen
+    //     (receiptValueVoucherSign): der verkaufte wird zurueckgezahlt.
+    //     Eintraege mit `zeroRateBucket` stehen schon als Position (0-%-Topf).
+    const wgVz = receiptValueVoucherSign(receipt);
     let promoCents = 0;
     for (const voucher of receipt.vouchers) {
+        // Betrag steht als Position (Einzweck, Leistung, 0-%-Topf): weder Zeile noch 0-%-Zeile aus dem Eintrag.
+        if (gutscheinStehtAlsPosition(voucher))
+            continue;
         const wert = voucher.valueCents ?? 0;
+        const vz = voucher.type === VoucherType.value ? wgVz : 1;
         if (voucherIsValid(voucher) && voucher.action === VoucherAction.sell) {
-            gruppeVon(steuersatz(VatRate.vat0)).bruttoCents += wert;
+            gruppeVon(steuersatz(VatRate.vat0)).bruttoCents += vz * wert;
         }
         if (voucher.action === VoucherAction.sell && voucher.type === VoucherType.value) {
+            // Mehrzweck mit Code (vor dem Stichtag nur als Eintrag): wie die Position im 0-%-Topf.
+            const mehrzweck = istMehrzweckMitCode(voucher);
+            const code = gutscheinCodeZusatz(voucher);
             lines.push({
                 kind: 'columns',
                 columns: [
-                    { text: `1  x ${gutscheinText(voucher)}`, width: 7, align: 'left' },
-                    { text: `${formatCents(wert)} ${VatRate.vat0.category}`, width: 5, align: 'right' },
+                    { text: `1  x ${mehrzweck ? `Mehrzweckgutschein${code}` : gutscheinText(voucher)}`, width: 7, align: 'left' },
+                    { text: `${formatCents(vz * wert)} ${VatRate.vat0.category}`, width: 5, align: 'right' },
                 ],
             });
+            if (mehrzweck)
+                lines.push(textZeile(MEHRZWECK_UST_TEXT));
         }
         if (voucher.action === VoucherAction.redeem && voucher.type === VoucherType.promo) {
-            promoCents += wert;
+            // Am Storno-Beleg steht der Promotionsgutschein nur als Bezug: den Rabatt
+            // nimmt dort die Position „Gutschein-Ausgleich“ zurueck (receiptSubSumCents).
+            if (wgVz === 1)
+                promoCents += wert;
             lines.push({
                 kind: 'columns',
                 columns: [
                     { text: gutscheinText(voucher), width: 7, align: 'left' },
-                    { text: `-${formatCents(wert)} €`, width: 5, align: 'right' },
+                    { text: wgVz === 1 ? `-${formatCents(wert)} €` : '', width: 5, align: 'right' },
                 ],
             });
         }
@@ -1015,10 +1179,22 @@ export function buildReceiptLayout(receipt, company, options = {}) {
     if (summeCents !== zwischensummeCents) {
         lines.push(paarZeile('Zwischensumme', `${formatCents(zwischensummeCents)} €`));
         for (const voucher of receipt.vouchers) {
-            if (voucher.action === VoucherAction.redeem && voucher.type === VoucherType.value) {
-                // Breite 8:4 — "Wertgutschein GS-1" (Label + Code) passt so auf 58 mm
-                // in die Zeile, statt den Code in eine Folgezeile fliessen zu lassen.
-                lines.push(paarZeile(gutscheinText(voucher), `-${formatCents(voucher.valueCents ?? 0)} €`, 8, 4));
+            if (voucher.type !== VoucherType.value || voucher.zeroRateBucket === true)
+                continue;
+            if (voucher.action !== VoucherAction.redeem && voucher.action !== VoucherAction.payout)
+                continue;
+            // Breite 8:4 — "Wertgutschein GS-1" (Label + Code) passt so auf 58 mm
+            // in die Zeile, statt den Code in eine Folgezeile fliessen zu lassen.
+            // Am Storno-Beleg geht der Wert auf den Gutschein zurueck: ohne Minus.
+            // Mehrzweck mit Code: „Gutschein ····-9DWT“ und darunter der Rest
+            // (Zahlungszeile laut Spec); eine Auszahlung ohne `zeroRateBucket`
+            // (schreibt der Server nicht) zaehlt wie in receiptSumCents.
+            const wert = voucher.valueCents ?? 0;
+            const endung = istMehrzweckMitCode(voucher) ? gutscheinEndung(voucher) : null;
+            const text = endung != null ? `Gutschein ····-${endung}` : gutscheinText(voucher);
+            lines.push(paarZeile(voucher.action === VoucherAction.payout ? `Auszahlung ${text}` : text, wgVz === 1 ? `-${formatCents(wert)} €` : `${formatCents(wert)} €`, 8, 4));
+            if (endung != null && wgVz === 1 && Number.isInteger(voucher.balanceAfterCents)) {
+                lines.push(paarZeile('  Rest am Gutschein', `${formatCents(voucher.balanceAfterCents)} €`, 8, 4));
             }
         }
         lines.push({ kind: 'rule', char: '-' });