bench get-app https://github.com/saschafo/beverage_management

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=saschafo%2Fbeverage_management)](https://frappegems.com/gems/apps/saschafo/beverage_management)

Beverage Management

Pfand-, Gebinde- und Leergutverwaltung für ERPNext / Frappe Framework v16.

Zum Anschauen: pfand.industrie-4-0.org Ein Klick, kein Kennwort. Die Demo setzt sich jede Nacht zurück.

Die App trennt drei Dinge, die im Getränkefachhandel getrennt gehören:

1. Warenwert, der Preis des Getränks (Vollgut), unverändert ERPNext-Standard.
2. Pfandgeld, eigene Belegzeilen mit eigenem Artikel, eigener Steuer und eigener Kontierung.
3. Gebindeumlauf, ein mengenmäßiges Leergutkonto je Kunde und Lieferant, unabhängig vom Geldbetrag.

In brief (English)

German beverage retail keeps three things apart that ERPNext treats as one: the price of the drink, the statutory deposit on each bottle and crate, and the physical count of containers a customer still holds. This app adds all three.

Deposit lines are generated from a per-item container matrix, so an invoice for twelve crates of beer automatically carries 240 bottle deposits and 12 crate deposits, taxed correctly, since under German VAT rules the deposit on a bottle follows the tax rate of the drink inside it, while a pallet is a supply of its own. A quantity ledger, modelled on ERPNext's Stock Ledger Entry, tracks what every customer and supplier holds.

On top sits a purpose-built web UI at /pfand for the people who actually do the work: counter sales with a barcode scanner, empties intake, documents, master data and reporting, usable without ever opening the ERPNext desk.

The interface, the code comments and the rest of this document are in German, because that is where the domain and its tax law live.

Selbst installieren

git clone https://github.com/saschafo/beverage_management.git
cd beverage_management/docker
./start.sh

Docker mit Compose genügt, kein Python, kein Node, kein bench auf dem eigenen Rechner. Nach einigen Minuten steht ERPNext v16 mit der App und einem Demo-Betrieb aus der Fränkischen Schweiz unter .

Für eine bestehende Instanz:

bench get-app https://github.com/saschafo/beverage_management.git
bench --site  install-app beverage_management

Einzelheiten und der öffentliche Demo-Betrieb: docker/README.md.

Datenmodell

DocType	Zweck
Deposit Type	Pfandstammdaten: Kategorie, Standardwert, Pfandartikel, Kontierung
Item Deposit Structure	Child Table am Artikel — die Gebindematrix (20 × Flasche, 1 × Kasten)
Deposit Ledger Entry	Mengenbuchung je Partner und Pfandartikel, analog zum Stock Ledger Entry
Deposit Settings	Vorbelegung für die Leergut-Oberfläche: Buchungskreis, Lager für Annahme und Lieferung, Fußtext

Custom Fields (werden bei jedem bench migrate nachgezogen, siehe install.py):

• Item: eigener Reiter Pfand mit is_deposit_item, has_deposit, deposit_structures
• Sales Invoice, POS Invoice, Delivery Note, Purchase Invoice, Purchase Receipt: auto_expand_deposits, deposit_total
• die zugehörigen Positionstabellen: is_deposit_row, parent_item_code

Ablauf

Artikel "Bier 20x0,5l"  (has_deposit = 1)
  └── Gebindestruktur
        ├── 20 × Flaschenpfand 0,08 €  → Pfandartikel "Pfand Flasche 0,5l"
        └──  1 × Kastenpfand   1,50 €  → Pfandartikel "Pfand Kasten 20er"

Beleg
  ├── before_validate → Pfandzeilen erzeugen  (deposit_handler.expand_deposits)
  ├── validate        → Pfandanteil summieren (deposit_handler.set_deposit_total)
  ├── on_submit       → Leergutkonto buchen   (deposit_ledger.make_deposit_ledger_entries)
  └── on_cancel       → Buchung entfernen     (deposit_ledger.cancel_deposit_ledger_entries)

Entwurfsentscheidungen

Ein paar Stellen sind nicht so gebaut, wie man es zuerst vermuten würde. Die Gründe, damit sie beim nächsten Anfassen nicht wieder eingerissen werden:

Auflösung im before_validate statt validate. Ein über doc_events registriertes validate läuft erst nach der Controller-Validierung von ERPNext und damit nach calculate_taxes_and_totals(). Pfandzeilen, die dort entstehen, werden gespeichert, fließen aber nie in grand_total ein, die Rechnung wäre um den gesamten Pfandbetrag zu niedrig.

Konten aus der Pfandart, nicht aus der Gebindestruktur. Das Konto steht am Deposit Type. Über die Buchungsart wird entschieden, ob die Zeile gegen ein Erlöskonto oder gegen das Pfandverbindlichkeitskonto läuft.

Kein Konto auf der Einkaufsseite. Für lagergeführte Artikel setzt ERPNext das Aufwandskonto selbst (Stock Received But Not Billed). Ein Überschreiben zerlegt die Bestandsbuchung. expense_account am Deposit Type dokumentiert deshalb nur.

Gebucht wird, wo die Ware sich bewegt. Lieferschein und Wareneingang buchen immer, Rechnungen nur mit update_stock. Sonst bucht die Rechnung zum Lieferschein denselben Kasten ein zweites Mal auf das Kundenkonto. Konsolidierte POS-Rechnungen (is_consolidated) werden übersprungen, weil die einzelnen POS Invoices bereits gebucht haben.

Salden werden neu aufgebaut, nicht fortgeschrieben. Den letzten Saldo zu lesen und darauf zu addieren ist falsch, sobald ein Beleg rückdatiert oder storniert wird, und das kommt vor. Stattdessen wird die betroffene Kette ab dem frühesten berührten Tag neu gerechnet (repost_balances), mit for update gegen parallele Buchungen. Die Abfrage filtert nach Buchungskreis, sonst vermischen sich Mandanten.

Storno löscht statt gegenzubuchen. Gegenbuchungen würden den Kontoauszug des Kunden mit Bewegungen füllen, die es physisch nie gab. Die App entfernt die Buchungen des Belegs und baut die Salden neu auf, dasselbe Verhalten wie beim Stock Ledger.

Umrechnungsfaktor. Der Multiplikator der Gebindestruktur bezieht sich auf die Lagereinheit. Wird der Hauptartikel in einer abweichenden Einheit verkauft (Palette statt Kasten), fließt der Umrechnungsfaktor mit ein.

Steuerliche Einordnung statt Ja/Nein. Ein Kennzeichen „steuerpflichtig" reicht nicht: Pfand ist immer steuerbar, die Frage ist der Satz, und der hängt bei Warenumschließungen an der Hauptware. Deshalb das Feld tax_treatment mit den zwei Fällen des BMF-Schreibens.

Automatik im Einkauf standardmäßig aus. Lieferantenbelege weisen das Pfand in aller Regel selbst aus. Würde die App dort zusätzlich auflösen, stünde jeder Kasten doppelt im Beleg.

Zwei Wege für zurückkommendes Leergut

Welcher richtig ist, hängt nicht am Gebinde, sondern daran, wann das Pfand abgerechnet wird.

	Annahme (Gutschrift)	Rücknahme (Rücklieferung)
Wo	/pfand → Annahme, oder Straßenverkauf	/pfand → Belege → Leergut zurücknehmen
Wann	Der Kunde bekommt sein Pfand jetzt — bar oder als Gutschrift	Kunde auf Rechnung; das Pfand wird mit der Sammelrechnung verrechnet
Beleg	Sales Invoice mit is_return und update_stock	Delivery Note mit is_return
Geld	fließt zurück	bewegt sich nicht
Mengen	kommen ins Lager, Leergutkonto sinkt	ebenso
Bezugsbeleg	keiner nötig	Pflicht — ERPNext verlangt ihn und begrenzt die Menge darauf

Der Bezugsbeleg ist der eigentliche Unterschied in der Bedienung. Eine Rücklieferung ohne ihn weist ERPNext beim Buchen ab, deshalb führt die Maske in drei Schritten: erst der Kunde, dann die Lieferung, dann was daraus zurückkommt. Zu jedem Gebinde steht die offene Menge, geliefert minus bereits zurückgenommen —, und ein Knopf übernimmt sie ganz. Kommt Leergut aus mehreren Lieferungen zurück, wird je Lieferschein ein Beleg erfasst; wo das stört, ist die Annahme der richtige Weg, denn die kennt diese Grenze nicht.

Von Hand im Desk

Wer einen solchen Beleg im Desk erfasst, muss dort Pfand automatisch auflösen abschalten und die Pfandartikel als normale Zeilen mit negativer Menge eintragen. Der Grund: Die Automatik leitet Pfandzeilen aus den Hauptartikeln ab. Steht kein Getränk im Beleg, gibt es nichts, woraus sich eine Zeile ableiten ließe -- und eine Pfandzeile ohne Hauptartikel wird beim nächsten Speichern als verwaist entfernt. Die Oberfläche unter /pfand nimmt einem das ab.

Umsatzsteuer

Pfand ist in Deutschland nicht steuerfrei, aber es gibt auch keinen einheitlichen Satz. Das BMF-Schreiben vom 20.10.2014 unterscheidet zwei Fälle, und die App bildet beide ab. Am Deposit Type steht dafür das Feld Umsatzsteuerliche Einordnung:

Einordnung	Beispiele	Behandlung
Warenumschließung	Flasche, Getränkekasten	Nebenleistung — das Pfand teilt den Steuersatz der Hauptware
Transporthilfsmittel	Palette, Rollcontainer	eigenständige Lieferung zum Regelsteuersatz

Bei einer Warenumschließung übernimmt die erzeugte Pfandzeile deshalb die Item Tax Template des Getränks. Zu einer Milch mit 7 % gehört ein Flaschenpfand mit 7 %, zu einem Bier mit 19 % dasselbe Flaschenpfand mit 19 % — und beides kann im selben Lieferschein stehen.

Damit das aufgeht, muss der Pfandartikel jede Vorlage führen, mit der er vorkommen kann: ERPNext prüft in validate_item_tax_template, ob die Vorlage einer Belegzeile zum Artikel gehört, und ersetzt sie sonst durch dessen eigene. Die App zieht das deshalb beim Speichern des Getränks nach, die Vorlagen des Getränks werden auf seine Warenumschließungen übertragen. Nicht beim Buchen des Belegs: Stammdaten aus einer Belegprüfung heraus zu ändern wäre eine Nebenwirkung an einer Stelle, an der niemand mit ihr rechnet.

Grenze: Bei einer Rücknahme ohne Getränk im Beleg, der Gutschrift an der Rampe, gibt es keine Hauptware, von der sich der Satz ableiten ließe. Dann greift die Vorlage am Pfandartikel selbst. Wer es genauer braucht, nutzt die Vereinfachungsregelung des BMF-Schreibens, nach der die Pfandbeträge auf Antrag zum Jahresende netto abgerechnet werden. Diese Entscheidung gehört zum Steuerberater und nicht in die Software.

Die Einordnung des einzelnen Gebindes ebenfalls: Dass Flaschen und Kästen Warenumschließungen sind und Paletten Transporthilfsmittel, ist die Regel, für Fässer und Sonderformen ist es eine Frage an den Berater. Deshalb steht sie je Pfandart und ist nicht fest verdrahtet.

Kontierung

Die App gibt keine Kontonummern vor. Sie verwendet ausschließlich die am Deposit Type hinterlegten Konten. Welche das sind, gehört zum Kontenrahmen des Mandanten und damit zum Steuerberater.

Oberfläche

Zwei Einstiege, für zwei verschiedene Arbeitsplätze.

Im Desk gibt es den Arbeitsbereich Pfand und Leergut mit Kurzwegen zu den Leergutkonten, den Pfandarten und den Berichten sowie Karten für Stammdaten, Belege und Auswertungen. Das ist der Platz für Buchhaltung und Stammdatenpflege.

Unter /pfand liegt die Pfandverwaltung, eine eigene Oberfläche für den Betrieb, also Rampe, Verkauf und Fahrzeug. Sie trägt unten eine feste Fußzeile mit dem Urheberhinweis und dem Verweis auf industrie-4-0.org; im Druck entfällt sie, auf einem Kundenbeleg hat sie nichts verloren.

Die Ansichten:

Ansicht	Wofür
Übersicht	Wie viele Kunden offenes Leergut haben, wie viele Gebinde draußen sind
Annahme	Kunde suchen, zurückgebrachte Gebinde zählen, als Gutschrift buchen
Konten	Saldo je Partner, Kontoauszug, druckbarer Leergutbeileger
Inventur	Gebindepool gegen die Zählung stellen, Differenz je Artikel
Tour	Was heute hinausgeht und was beim jeweiligen Kunden abzuholen ist
Belege	Lieferschein anlegen, Belege ansehen, buchen, stornieren
Straßenverkauf	Verkaufen, Leergut gegenrechnen, bar kassieren — ohne Kundenkonto
Auswertung	Bewegung im Zeitraum, Umlauf, Lagerbestand, Werte und Straßenverkauf — mit Diagrammen
Stammdaten	Kunden, Lieferanten, Pfandarten und Getränke anlegen und ändern

Die Zählmaske zeigt zu jedem Pfandartikel, wie viel der Kunde davon hält, und sortiert danach, was er hält, bringt er in aller Regel auch zurück.

Belege

Der Bereich Belege deckt das Tagesgeschäft ab, ohne dass jemand ins Desk wechseln muss. Anlegen lassen sich