3447nazmul/smb-bookkeeper-repo

SMB Rechnung + Buchhaltung

Eine unstrukturierte Nachricht → Rechnung, Ausgabenprotokoll und den nächsten Erinnerungsentwurf. Kein Konto, kein Abonnement, keine Bindung – dein Geld, in Dateien, die dir gehören.

Kleinunternehmen scheitern nicht an der Arbeit. Sie scheitern am Warten: etwa 55 % der B2B-Rechnungen in Nordamerika werden verspätet bezahlt (Atradius, über Crestmont Capital, aktualisiert 2026), US-Kleinunternehmen warteten im zweiten Quartal 2026 durchschnittlich 29,3 Tage auf Zahlung, ~9 Tage nach Fälligkeit (Xero Small Business Insights, über Foundrly, Aug. 2026), und 82 % der Insolvenzen von Kleinunternehmen sind auf Cashflow-Probleme zurückzuführen (US Chamber of Commerce, über Crestmont, 2026). Die Wahrscheinlichkeit einer erfolgreichen Beitreibung sinkt mit zunehmendem Alter rapide – über 95 % in den ersten 30 Tagen mit proaktiver Nachverfolgung, auf 20–30 % jenseits von 120 Tagen (Crestmont, 2026). Die Rechnung ist der einfache Teil. Das Nachfassen ist das eigentliche Produkt – und überall sonst ist das Nachfassen kostenpflichtig: Automatische Erinnerungen sind bei Wave (19 $/Monat) und Invoice Ninja (14 $/Monat) nur in der Pro-Version verfügbar (Preisseiten der Anbieter, Nov. 2026), Wave kann keine Rechnungen außerhalb der USA/Kanadas versenden (Wave-Support, 8. Sep. 2026), und Zoho Invoices kostenloses Kontingent ist auf 500 Rechnungen/Jahr begrenzt und löscht unbenutzte Daten nach 180 Tagen (zoho.com/invoice/pricing, abgerufen am 11.11.2026). Diese Fähigkeit erstellt die Nachverfolgung kostenlos.

Version 0.2.0. Neu aufgebaut aus der kritischen Überprüfung von v0.1.0 (20 Lücken, alle behoben oder in MEASUREMENTS.md §11 dokumentiert) und den Korrekturen aus der Tiefenrecherche (research-notes-v2.md §1). Was sich geändert hat, steht in CHANGELOG.md. Die unten stehenden Zahlen sind reale Durchläufe mit den beigefügten Beispieldaten, keine Schätzungen.

Keine Rechts-, Steuer- oder Finanzberatung. Diese Fähigkeit hilft dir, Rechnungen zu erstellen und Geld zu verfolgen. Steuersätze, Registrierungsschwellen und Rechnungsanforderungen unterscheiden sich je nach Land und ändern sich im Laufe der Zeit. Lege deinen eigenen Steuersatz fest und bestätige die Regeln für dein Unternehmen bei deiner lokalen Steuerbehörde (in Bangladesch: dem National Board of Revenue, nbr.gov.bd) oder einem qualifizierten Buchhalter. Dieser Haftungsausschluss wird auch in der Fußzeile jeder erstellten Rechnung und Quittung abgedruckt – auf den bengalischen Dokumenten auf Bengalisch. Für die zugrunde liegenden Aufbewahrungsregeln (was aufbewahrt werden muss, TIN/BIN auf Rechnungen, Mushak-Formulare, Aufbewahrungsfristen) siehe das Referenz-Handbuch: OpenAccountants' bd-bookkeeping-Fähigkeit (openaccountants/openaccountants, 484★, aktualisiert am 11.11.2026) – ein englischsprachiges Nachschlagewerk, ausdrücklich „nur allgemeine Referenz… nicht auf die Fakten einer bestimmten Person überprüft“. Es erstellt keine Rechnungen. Diese Fähigkeit tut das.

Ausführen

python3 scripts/bookkeeper.py <Befehl>

Python ≥ 3.9, nur Standardbibliothek. Kein Installationsschritt, keine Abhängigkeiten, kein Netzwerkaufruf, kein API-Schlüssel, kein Konto. Die Daten leben in einfachen JSON-Dateien, die du öffnen, kopieren und überallhin mitnehmen kannst.

Geldregeln – vor dem Vertrauen in Zahlen lesen

Dies sind die Regeln, die die Gesamtsummen vertrauenswürdig machen und die bei der Überprüfung von v0.1.0 beanstandet wurden, dass diese Fähigkeit sie verletzt hat:

• Geld wird kaufmännisch gerundet (ROUND_HALF_UP), so wie ein Ladenbesitzer mit einem Taschenrechner rundet – niemals Banker-Rundung. ৳2.345 ist ৳2.35.
• Mengen sind exakt, niemals als Geld gerundet. Eine Menge von 1.005 ist 1.005; nur der Positionsbetrag wird gerundet. Mengen werden ohne nachgestellte Nullen ausgegeben (3, niemals 3.00).
• Steuer wird pro Position auf den rabattierten Positionsbetrag berechnet – die Steuer jeder Position wird kaufmännisch auf diese Position gerundet und dann summiert (so wie es Wave / Xero / FreshBooks machen). 3 Positionen zu ৳0.35 bei 15 % Steuer ergeben ৳0.15, nicht ৳0.16.
• Bezahlt-Sein leitet sich vom Saldo ab, niemals von der Status-Zeichenkette. Eine als „bezahlt“ markierte Rechnung mit noch geschuldeten ৳4.000 meldet ৳4.000 als offen, und der Bericht sagt, dass der Status falsch ist. Der Status ist ein Hinweis; der überfällige Zustand wird aus dem Fälligkeitsdatum und dem Saldo abgeleitet.
• Geld wird niemals über Währungen hinweg summiert. Ein Hauptbuch mit gemischten Währungen meldet Gesamtsummen pro Währung (৳5.000 + 100 $) und verweigert eine zusammengefasste Gesamtsumme und einen zusammengefassten Nettobetrag – die Fähigkeit hat keinen Devisenhandel und teilt dies mit.
• Ein Problem im Hauptbuch ist laut und führt zu Exit-Code 2. overdue und cashflow beenden mit Exit-Code 2, wenn eine Zeile übersprungen wird (ungültige Daten), eine Nummer dupliziert ist, eine „bezahlte“ Rechnung noch einen Saldo aufweist, eine Zahlung zu viel geleistet wird oder eine Zahlung kein paid_date hat. Der Bericht wird trotzdem ausgegeben; der Exit-Code sagt, dass das Hauptbuch repariert werden muss, bevor man ihm vertrauen kann.
• Negative Geldbeträge werden mit vorangestelltem Minus ausgegeben: −৳4.100 – eine Konvention, überall.

Der Workflow: eine Eingabe → Rechnung → Quittung → Erinnerung → Cashflow

1. Rechnung, Angebot oder Quittung aus einer JSON-Eingabe

python3 scripts/bookkeeper.py invoice --input samples/invoice-input.json --out out/invoice.html --config config/bd.json
python3 scripts/bookkeeper.py invoice --input samples/invoice-input-bn.json --out out/invoice-bn.html --config config/bd.json --lang bn
python3 scripts/bookkeeper.py invoice --input my-quote.json --out out/quote.html --format md
python3 scripts/bookkeeper.py receipt --input samples/invoice-input.json --out out/receipt.html --paid-date 2026-11-05 --amount-paid 4500

• Die Eingabe ist eine kleine JSON-Datei: Unternehmen + Kunde + Positionen (Beschreibung, Menge, Einzelpreis) + Rechnungsnummer + Ausstellungsdatum + Fälligkeitsdatum. Siehe samples/invoice-input.json für die genaue Struktur.
• Angebot → Rechnung → Quittung ist ein Lebenszyklus, ein Datenmodell. type: "quote" benötigt valid_until anstelle eines Fälligkeitsdatums; eine Rechnung benötigt ein echtes Kalender-Fälligkeitsdatum, nicht nur „Netto 30“; eine Quittung wird aus einer bezahlten Rechnung mit --paid-date und --amount-paid erstellt und zeigt den verbleibenden বাকি (Restbetrag), wenn die Zahlung teilweise erfolgte. Eine Quittung mit einem Betrag von 0 wird abgelehnt – eine Quittung bestätigt erhaltenes Geld. Ein Angebot zeigt niemals bezahlte/offene Zeilen (bei einem Vorschlag ist nichts geschuldet), weder in HTML noch in Markdown, und seine Nummer wird als „Angebotsnummer“, nicht als „Rechnungsnummer“ bezeichnet.
• Die Rechnung enthält die Felder, die jede Rechnung benötigt (Forschungshinweise §3.1): das Wort „Rechnung“, eine eindeutige fortlaufende Nummer, Ausstellungsdatum, Fälligkeitsdatum, Verkäuferdetails, Käuferdetails, spezifische Beschreibungen, Positionen, Steuer als eigene Zeile, Zahlungsanweisungen + fälliger Gesamtbetrag. Eine Angebotsnummer wird auf der Rechnung referenziert, wenn eine vorhanden ist; eine Bestellnummer des Kunden und die Steuernummer des Verkäufers (tax_id – in Bangladesch die 13-stellige BIN) werden auf der Rechnung ausgegeben, wenn angegeben.
• Die Nummerierung ist fortlaufend (INV-2026-001, INV-2026-002, …). Niemals eine Nummer überspringen oder wiederverwenden – eine Lücke oder Doppelung sieht bei der Steuererklärung wie fehlende Einnahmen oder erfundene Ausgaben aus. Hauptbuch-Befehle warnen laut und beenden mit Exit-Code 2 bei einer doppelten Nummer. Das numbering_prefix der Konfiguration wird gegen die Rechnungsnummer geprüft (eine Warnung, kein Fehler); default_terms füllt die Zahlungsbedingungenzeile, wenn die Eingabe keine hat.
• Die Ausgabe ist sauberes, druckbares HTML (im Browser öffnen, als PDF drucken) oder Markdown (--format md). Keine externen Ressourcen im HTML, sodass es genau so gedruckt wird, wie es aussieht – die mitgelieferten Beispiele wurden in einem kopflosen Chromium gerendert und einmal als PDF gedruckt (siehe MEASUREMENTS.md §11.6, Screenshots in docs/).
• Geld wird mit Decimal berechnet, niemals mit Float. Der Rabatt ist ein Prozentsatz des Nettobetrags, der pro Position angewendet wird; die Steuer wird pro Position auf den rabattierten Betrag berechnet (siehe „Geldregeln“).
• Die Validierung ist streng und der Exit-Code ist 2 bei fehlerhafter Eingabe: fehlendes Fälligkeitsdatum, negative Menge oder Preis, Steuersatz außerhalb von 0–100 %, ungültige Daten, fehlerhaftes JSON, fehlende Datei, ein Fälligkeitsdatum vor dem Ausstellungsdatum, ein Zahlungsdatum vor dem Ausstellungsdatum. Eine Rechnung mit null Positionen ist erlaubt (Gesamtsumme ৳0), gibt aber eine Warnung aus – es handelt sich um einen Entwurf, keinen Fehler, den es zu verbergen gilt. Eine Überzahlung eines Dokuments gibt eine Warnung bei beiden Dokumentbefehlen aus (eine Quittung sollte niemals „Restbetrag: ৳-825“ anzeigen).

2. Steuer – eine Einstellung, die du eingibst, niemals ein fest codierter Satz

# In der Rechnungseingabe (dies ist der EINZIGE Ort, an dem ein Satz lebt):
"tax": {"name": "VAT", "rate_percent": 15}

• Kein Tool hat einen fest codierten Satz, und diese Fähigkeit auch nicht. Jedes Rechnungstool (Zoho, FreshBooks, Wave, Xero – Forschungshinweise §5.1) lässt den Benutzer eine benannte Steuer + Prozentsatz definieren, wendet sie pro Position an und zeigt sie als separate Zeile an. Diese Fähigkeit kopiert das genau: Die Steuer ist eine benannte Steuer + Prozentsatz in der Eingabe, Standard 0 % / keine Steuer.
• Länder-Voreinstellungen in config/ liefern die Steuerbezeichnung, die Währung, die Zahlungsmethoden, die Standard-Zahlungsbedingungen und das Nummerierungspräfix – niemals einen Satz. config/bd.json (Bangladesch: ৳, „VAT“, bKash / Nagad / Rocket / Banküberweisung / Bar) und config/us.json (USA: $, „Sales tax“, Netto 30). tax_rate_percent in beiden Konfigurationen ist absichtlich null. Eine tax_id in der Konfiguration (deine BIN) füllt die Rechnung aus, wenn die Eingabe keine hat.
• Die Beispielrechnung verwendet 15 % Mehrwertsteuer, weil die Beispieleingabe dies so angibt – Bangladeschs Standard-Mehrwertsteuersatz beträgt 15 % gemäß dem VAT and Supplementary Duty Act 2012 (ArthiKalap, aktualisiert am 25. Jul. 2026; TRW, GJ 2026-27; TaxDo, 2026; SDTT Academy, Anfang 2026) – aber die Fähigkeit weiß das nicht und darf niemals so zitiert werden, als wüsste sie es. Mehrwertsteuererklärungen sind wieder monatlich (fällig innerhalb von 15 Tagen): Das Finance Act 2026 machte sie ab dem 1. Jul. 2026 vierteljährlich, aber eine am 14. Okt. 2026 veröffentlichte Änderungsverordnung stellte die monatlichen Erklärungen wieder her (TRW „Doing Business in Bangladesh 2026“, Rechtsstand 24. Okt. 2026; entrepreneurs.bd, 2026). Jede Angabe „vierteljährlich“ in älteren Notizen ist nun falsch.
• Registrierungsschwellen sind in dieser Fähigkeit NICHT fest codiert. Drei unabhängige Leitfäden von Okt.–Nov. 2026 stimmen nun bei denselben Zahlen überein – Pflichtregistrierung ab Tk 50 Lakh Jahresumsatz; Eintragung für Tk 30–50 Lakh mit 4 % Umsatzsteuer; einige Tätigkeiten müssen sich unabhängig vom Umsatz registrieren (TRW „VAT in Bangladesh 2026“, Stand 18. Okt. 2026; TRW „VAT Registration“; entrepreneurs.bd, 2026; Aniday, verifiziert Sep. 2026). Eine direkte Überprüfung gegen die NBR wurde nicht erreicht: Die NBR-Startseite (geladen am 11.11.2026) enthält keinen Schwellentext, und vat.gov.bd war an diesem Tag nicht erreichbar. Daher werden diese Zahlen hier als konvergierende Sekundärquellen, nicht als NBR-verifizierte Tatsache gemeldet – die Fähigkeit gibt niemals einen Schwellenwert als ihren eigenen an und verweist die Benutzer an nbr.gov.bd. Die BIN ist 13-stellig (NBR-Startseite Service-Auflistung, 11.11.2026 – eine Bezeichnung, kein Gesetzesblatt; bestätige die Stellenanzahl im NBR-Mehrwertsteuer- Registrierungsleitfaden, wenn du die Schwellenwerte überprüfst).
• Steuerinklusive Preise werden unterstützt: "tax": {"name": "VAT", "rate_percent": 15, "inclusive": true} extrahiert die Steuer aus dem Bruttopreis (VAT = brutto × 15 ÷ 115). Gemessen in MEASUREMENTS.md §5: ৳1.150 brutto → ৳150 VAT, Gesamtsumme bleibt ৳1.150.

3. Ausgabenprotokoll – Klartext, einfache Dateien

python3 scripts/bookkeeper.py expense add --ledger expenses.json --date 2026-11-11 --category Materials --amount 1200 --note "Kupferdraht, 20 m"
python3 scripts/bookkeeper.py expense list --ledger expenses.json --month 2026-11
python3 scripts/bookkeeper.py expense export --ledger expenses.json --out expenses.csv

• Eine Ausgabe = Datum, Kategorie, Betrag, Notiz. Das Hauptbuch ist eine JSON- Liste; export schreibt eine CSV, die sich in jeder Tabellenkalkulation öffnen lässt.
• Kategorien sind Klartext, kein Kontenrahmen: Materialien, Transport, Werkzeuge, Mobil/Internet, Verpflegung, Miete, Arbeit, Verpackung, Sonstiges. Eine unbekannte Kategorie ist ein Fehler, niemals stillschweigend akzeptiert. Negative Beträge werden abgelehnt. --month muss ein echtes YYYY-MM sein (2026-1 wird abgelehnt – ein roher Präfixabgleich würde Oktober und November stillschweigend zusammenführen).
• Eine Hauptbuchzeile, die kein Objekt ist, wird mit einer Warnung und Exit-Code 2 lautstark übersprungen – niemals ein Traceback, niemals stillschweigend. expense add weigert sich, ein Hauptbuch neu zu schreiben, das eine beschädigte Zeile enthält (zuerst reparieren).

4. Überwachungs-Tracker + Erinnerungsentwürfe – das Herzstück der Fähigkeit

python3 scripts/bookkeeper.py overdue --invoices samples/invoices.json --as-of 2026-11-11
python3 scripts/bookkeeper.py overdue --invoices samples/invoices.json --as-of 2026-11-11 --lang bn --json

• Scannt das Rechnungshauptbuch, listet jede offene Rechnung nach Alterskategorie auf (aktuell / 1–30 / 31–60 / 61–90 / 90+ Tage überfällig) und erstellt für jede den nächsten Erinnerungsentwurf in der richtigen Phase.
• Die 6-stufige Sequenz (der 5-Kontakt-Konsens laut Raoura, verifiziert Jul. 2026; InvoiceCub, 31. Okt. 2026; InvoiceFly, ~Nov. 2026; HeroThemes, ~Aug. 2026; FreelanceDesk, ~Jun. 2026 – vor Fälligkeit, am Fälligkeitstag, 7, 14, 30 Tage – plus der frühe freundliche Hinweis für 1–6 Tage Überfälligkeit aus der 7-Kontakt-Version; der zusätzliche 21-Tage-Kontakt der 7-Kontakt- Version ist keine separate Stufe, sein Bereich wird durch den 14-Tage-Entwurf mit dem nächsten Kontakt an Tag 30 abgedeckt): 3 Tage vor Fälligkeit, am Fälligkeitstag, 7 Tage überfällig, 14 Tage überfällig, 30 Tage letzte Mahnung, plus der 1–6-Tage-Hinweis. Abgestufte Eskalation, niemals zuerst Anschuldigung: Gehe früh von guter Absicht aus (vergessen / untergegangen / in der Genehmigungswarteschlange); erwähne eine Verzugsgebühr nur, wenn die Vereinbarung eine vorsieht und die Rechnung ~2 Wochen überfällig ist. Jeder Entwurf wiederholt Rechnungsnummer, Betrag, das ursprüngliche Fälligkeitsdatum – und die tatsächliche Anzahl der überfälligen Tage (einer 8 Tage überfälligen Rechnung wird „8 Tage überfällig“ mitgeteilt, niemals die Stufennummer).
• Nur Entwürfe – die Fähigkeit versendet niemals etwas. Du sendest die Erinnerung. Der Bericht gibt auch das nächste Kontaktdatum aus, sodass die Eskalation nicht vom Erinnern abhängt. Ein bereits verstrichenes nächstes Kontaktdatum wird als „jetzt senden (war fällig am …)“ ausgegeben, niemals als bloßes vergangenes Datum. Die letzte Mahnung gibt eine Frist von frühestens 7 Tagen ab heute vor (max(fällig + 37 Tage, heute + 7 Tage)) – eine Aufforderung, deren Frist bereits verstrichen ist, ist schlimmer als keine Aufforderung.
• Gemessen an den Beispielen (Stand 11.11.2026): 6 offene Rechnungen, ৳48.650 dir geschuldet (বাকি), 4 überfällig mit insgesamt ৳28.250 – eine in jeder Phase vom Hinweis bis zur letzten Mahnung. Siehe MEASUREMENTS.md §3.
• Entwurfsrechnungen sind von „dir geschuldet“ ausgeschlossen – eine nicht gesendete Rechnung ist noch kein geschuldetes Geld. Bezahlte Rechnungen (Saldo 0) sind ebenfalls ausgeschlossen.

5. Einfache Cashflow-Ansicht – die Zahlen, die der Inhaber tatsächlich prüft

python3 scripts/bookkeeper.py cashflow --invoices samples/invoices.json --ledger expenses.json --as-of 2026-11-11
python3 scripts/bookkeeper.py cashflow --invoices samples/invoices.json --ledger expenses.json --as-of 2026-11-11 --lang bn

python3 scripts/bookkeeper.py cashflow --invoices samples/invoices.json

• Der Cashflow-Bericht fasst auf einem Bildschirm zusammen:
  • Geld rein (bezahlte Rechnungen) – gesamter Betrag, der vor dem Stichtag eingegangen ist, plus Aufschlüsselung nach Monat (optional mit --month).
  • Geld raus (Ausgaben) – gesamte Ausgaben vor dem Stichtag.
  • Geschuldet (offene Rechnungen) – Saldo aller unbezahlten Rechnungen, getrennt nach „aktuell“ und „überfällig“.
• Der Bericht weigert sich, gemischte Währungen zu einer einzigen Zahl zu addieren. Wenn sowohl ৳5.000 als auch 100 $ vorhanden sind, zeigt er Währung wird gemischt (৳ + $) – Gesamtsumme nicht möglich. an und beendet mit Exit-Code 2.
• Der Bericht ist bar von der Ausgabeanweisung: Er enthält den fettgedruckten Abschnitt Nächstes Verfalls-/Fälligkeitsdatum – das Datum, an dem eine aktuelle Rechnung überfällig wird, das erste Datum einer überfälligen Rechnung und das nächste Mahndatum. Dies ersetzt die Notwendigkeit, separate Erinnerungen zu durchsuchen.
• Gemessen an den Beispielen (Stand 11.11.2026): ৳30.000 bezahlt (Rechnungen vom September), ৳6.100 Ausgaben (bisheriger Monat), ৳48.650 geschuldet (davon ৳28.250 überfällig). Siehe MEASUREMENTS.md §3.

Unterstützte Sprachen

• Englisch (Standard)
• Bengalisch (--lang bn) – alle Befehle, alle Ausgaben, alle Erinnerungsentwürfe. Der Befehl overdue enthält in bengalischer Ausgabe eine angepasste Anrede (প্রিয় [Name]).

Konfiguration

Jede Rechnung, jedes Angebot und jede Quittung benötigt eine Konfigurationsdatei,

[truncated - rest of SKILL.md would continue here with remaining sections]

Integration in Agenten: Diese Fähigkeit ist als Python-Skript implementiert. Agenten (Claude Code, Cursor, Codex usw.) können sie über die Befehlszeile aufrufen, indem sie python3 scripts/bookkeeper.py <Befehl> ausführen. Der Agent muss sich im Stammverzeichnis der Fähigkeit befinden (wo scripts/ existiert). Der Agent kann die --json-Flagge für Befehle wie overdue und cashflow nutzen, um strukturierte Ausgaben für die weitere Verarbeitung zu erhalten.

Hinweis für Agenten: Diese Fähigkeit ist für nicht-technische Kleinunternehmer konzipiert. Wenn du sie in einem Agenten-Workflow verwendest, erkläre dem Benutzer die Befehle und Ausgaben in einfacher Sprache. Führe keine Aktionen aus, die Rechnungen, Quittungen oder Zahlungserinnerungen versenden – diese Fähigkeit erstellt nur Entwürfe. Überprüfe immer, ob die Eingabedaten gültig sind (insbesondere Daten und Beträge), bevor du sie verarbeitest.