open-eur-buchhaltung/README.md

open-eur-webapp

Einnahmen-Überschuss-Rechnung nach §4 Abs. 3 EStG für Einzelunternehmen und Freiberufler – mit Kleinunternehmerregelung, Umsatzsteuer-Voranmeldung, BWA, ELSTER-Anbindung und DATEV-/GoBD-Export.

Die Anwendung läuft lokal: ein Node-Prozess, eine SQLite-Datei, keine Cloud-Anbindung.

npm install
npm run seed          # Beispieldaten mit Regimewechsel 2025 -> 2026
npm run dev           # Backend (3311) + Frontend (5173) im Entwicklungsmodus

Für den Dauerbetrieb:

npm run build
npm start             # liefert API und Oberfläche auf http://127.0.0.1:3311

npm test prüft die Steuerlogik (Regimewechsel, EÜR, UStVA, AfA, Steuernummernumsetzung).

npm run seed bricht ab, wenn bereits Buchungen vorhanden sind – sonst würden die Beispieldaten ein zweites Mal eingespielt und alle Auswertungen verdoppeln. npm run seed -- reset setzt die Bewegungsdaten zurück und legt sie neu an; dabei gehen auch selbst erfasste Buchungen verloren.

Betrieb mit Docker

cp .env.beispiel .env          # optional, für ELSTER
export UID GID=$(id -g)        # damit ./data dem eigenen Konto gehört
docker-compose up -d --build

Danach läuft die Anwendung auf http://localhost:3311.

Keine benannten Volumes. Der einzige Mount ist ./data:/app/data – die Buchhaltung liegt als gewöhnliche SQLite-Dateien im Projektverzeichnis und lässt sich sichern, kopieren und einsehen, ohne Docker zu bemühen. Der Container läuft mit der UID des aufrufenden Kontos, deshalb gehören die Dateien nicht root.

Weitere Festlegungen:

• Port nur auf 127.0.0.1 veröffentlicht. Die Anwendung kennt keine Benutzeranmeldung, und hier liegen Steuernummer und Umsätze. Für den Zugriff aus dem Netz gehört ein Reverse Proxy mit Authentifizierung davor.
• Das Dateisystem des Containers ist schreibgeschützt (read_only), beschreibbar ist nur /app/data und ein tmpfs unter /tmp.
• .env wird nicht ins Image gebacken. docker-compose liest die Datei für die Variablenersetzung und reicht die Werte als Umgebungsvariablen weiter.
• ERiC ist nicht enthalten und darf es auch nicht sein. Wer echt übermitteln will, hebt in docker-compose.yml die Zeilen für /opt/eric und das Zertifikat auf und setzt die Pfade in .env.

Beim Start meldet der Container, woher die Konfiguration stammt und ob ERiC eingebunden ist:

open-eur-webapp läuft auf http://localhost:3311
Konfiguration aus der Prozessumgebung.
ELSTER: Simulationsmodus, es wird nichts übermittelt (…).
Mandanten: standard – aktiv ohne Angabe: standard

Ohne Docker bindet sich der Server weiterhin an 127.0.0.1; im Container setzt HOST=0.0.0.0, weil die Portfreigabe den Prozess sonst nicht erreicht.

Mandanten

Jeder Mandant hat eine eigene SQLite-Datei unter data/mandanten/. Das ist Absicht: bei einer gemeinsamen Datenbank mit mandant_id-Spalte genügt ein einziges vergessenes WHERE, damit Testbuchungen in der echten EÜR oder in einer ELSTER-Übermittlung auftauchen. Getrennte Dateien machen das strukturell unmöglich.

Umgeschaltet wird oben in der Seitenleiste. Die Anwendung lädt dabei neu, damit keine Formularstände des vorherigen Mandanten stehen bleiben.

Testmandanten sind als solche markiert, auf jeder Seite sichtbar gekennzeichnet und können nichts an das Finanzamt übermitteln – es sei denn, ELSTER_TESTMERKER ist gesetzt, dann sind Probeübermittlungen ohne steuerliche Wirkung möglich.

npm run seed -- --mandant=test    # legt einen Testmandanten an und befüllt ihn

Technisch hängt der Mandant am Request: Header X-Mandant, für Download-Links (die keine Header setzen können) alternativ ?mandant=<bezeichner>. Der Server führt den Handler in einem AsyncLocalStorage-Kontext aus, sodass jeder Datenbankzugriff automatisch auf der richtigen Datei landet.

Beim Entfernen eines Mandanten wird die Datei nicht gelöscht, sondern mit Zeitstempel beiseitegelegt (…​.sqlite.entfernt-<zeit>).

Kontenrahmen: SKR03 und SKR04

Beide stehen zur Wahl – beim Anlegen eines Mandanten, danach nicht mehr. Kontonummern und Bezeichnungen stammen aus den amtlichen DATEV-Kontenrahmen (Stand 2026); die Zuordnung zu EÜR-Posten, BWA-Gruppen und UStVA-Kennzahlen ist fachliche Auslegung dieser Anwendung und gehört vor dem ersten Export mit der Steuerkanzlei abgestimmt.

Der Wechsel ist gesperrt, weil dieselbe Kontonummer in beiden Rahmen etwas anderes bedeutet:

Konto	SKR03	SKR04
1800	Privatentnahmen allgemein	Bank
2100	Zinsen und ähnliche Aufwendungen	Privatentnahmen allgemein
4830	Abschreibungen auf Sachanlagen	Sonstige betriebliche Erträge
4970	Nebenkosten des Geldverkehrs	Zinserträge

Aus demselben Grund ist das Standard-Gegenkonto rahmenabhängig (SKR03 1200, SKR04 1800) und das Feld kontenrahmen in den Stammdaten schreibgeschützt – sonst könnte der DATEV-Export einen Rahmen melden, den die Buchungszeilen nicht verwenden.

Belege

Zu jeder Buchung lässt sich ein Beleg hinterlegen – per Durchsuchen-Schaltfläche, Ziehen-und-Ablegen oder Strg+V. Nachträglich geht es über die Schaltfläche „+ Beleg" in der Buchungsliste.

Zum Einfügen mit Strg+V: Screenshots liegen als Bild in der Zwischenablage und funktionieren überall. Beim Kopieren einer Datei im Dateimanager hängt es vom System ab: Windows und macOS legen die Datei selbst ab, dann klappt es auch für PDFs. Unter Linux liefern viele Dateimanager nur einen file://-Verweis, den der Browser aus Sicherheitsgründen nicht lesen darf – dort bleibt Ziehen-und-Ablegen der verlässliche Weg für PDFs.

Zulässig sind PDF, JPEG, PNG, WebP, TIFF und HEIC bis 20 MB. Der Typ wird aus der Dateisignatur bestimmt, nicht aus Endung oder Browserangabe – eine als rechnung.pdf benannte Textdatei wird abgewiesen. SVG ist ausgeschlossen, weil es Skripte enthalten kann, die beim Anzeigen ausgeführt würden.

Die Dateien liegen unter data/belege/<mandant>/<jahr>/ und damit im selben Bind-Mount wie die Datenbanken; ein Backup des data-Ordners erfasst Buchungen und Belege gemeinsam. Zur Aufbewahrungspflicht (§147 AO): Belege werden nie überschrieben und nie gelöscht. Wird ein Beleg ersetzt oder die Verknüpfung gelöst, bleibt die Datei erhalten – der Dateiname enthält den SHA-256-Anfang, die Buchung den vollständigen Hash.

Anlagevermögen oder Sofortabzug

Ob eine Ausgabe abzuschreiben ist, entscheidet das Konto (Kontotyp anlage), nicht der Betrag – eine Werbekampagne für 3.000 € bleibt sofort abziehbar, ein Drucker für 900 € nicht. Eine Buchung auf ein Anlagekonto wird deshalb immer aktiviert; ein stiller Vollabzug ist nicht möglich.

Der Betrag entscheidet erst über die Methode (bei Kleinunternehmern zählt der Bruttobetrag, weil die Umsatzsteuer dann zu den Anschaffungskosten gehört):

Anschaffungskosten	Behandlung
≤ 800 €	GWG, im Anschaffungsjahr voll abgesetzt (§6 Abs. 2 EStG)
≤ 1.000 €	Sammelposten, über 5 Jahre aufgelöst (§6 Abs. 2a EStG)
> 1.000 €	linear über die Nutzungsdauer (§7 Abs. 1 EStG) – Nutzungsdauer ist Pflichtangabe

Buchungen auf Anlagekonten ohne hinterlegtes Anlagegut (etwa aus einer früheren Fassung) werden in der EÜR gesondert als prüfbedürftig ausgewiesen. Die Zahlen werden dabei bewusst nicht stillschweigend korrigiert.

Konfiguration

.env.beispiel nach .env kopieren und anpassen. Die Datei wird beim Start automatisch gelesen; bereits gesetzte Umgebungsvariablen haben Vorrang. Relative Pfade darin beziehen sich immer auf das Projektverzeichnis, nicht auf das Verzeichnis, aus dem der Prozess gestartet wurde – sonst entstünden je nach Startort verschiedene Datenbanken.

Ohne .env läuft alles außer der ELSTER-Übermittlung; diese arbeitet dann im Simulationsmodus.

Wenn der Start fehlschlägt

EMFILE: too many open files, watch ... (Linux, betrifft tsx watch und Vite gleichermaßen)

Nicht das Dateideskriptor-Limit, sondern die Zahl der erlaubten inotify-Instanzen ist erschöpft – typischerweise, weil VS Code und andere Werkzeuge sie bereits aufgebraucht haben:

cat /proc/sys/fs/inotify/max_user_instances            # meist 128
find /proc/*/fd -lname anon_inode:inotify | wc -l      # tatsächlich belegt

Dauerhafte Abhilfe:

sudo sysctl -w fs.inotify.max_user_instances=1024
echo 'fs.inotify.max_user_instances=1024' | sudo tee /etc/sysctl.d/60-inotify.conf

Ohne Root-Rechte stattdessen:

npm run dev:polling   # Server ohne Watcher, Vite mit Polling statt inotify

Der Server startet dann nicht automatisch neu – nach Änderungen am Backend manuell neu starten.

---

Der Kern: die Zeitachse der Besteuerungsform

Der Wechsel von der Kleinunternehmerregelung zur Regelbesteuerung ist nicht als Schalter umgesetzt, sondern als Zeitachse:

Gültig ab	Besteuerungsform
15.01.2024	Kleinunternehmer (§19 UStG)
01.01.2026	Regelbesteuerung

Jede Buchung wird nach dem Regime behandelt, das zu ihrem Leistungsdatum galt. Daraus folgt:

• Altbuchungen bleiben unverändert, wenn ein Wechsel eingetragen wird.
• Ein unterjähriger Wechsel ist möglich – nötig etwa beim Überschreiten der 100.000-EUR-Grenze, seit 2025 endet die Kleinunternehmerregelung dann sofort mit dem überschreitenden Umsatz (§19 Abs. 1 Satz 3 UStG).
• Ein Jahr mit Wechsel weist Umsätze davor und danach in der EÜR getrennt aus.

Die Umsatzgrenzen werden laufend überwacht (25.000 EUR Vorjahr / 100.000 EUR laufendes Jahr ab 2025; 22.000 / 50.000 bis 2024) und melden sich, bevor der Wechsel fällig wird.

Die Regeln stehen an einer Stelle: server/src/domain/regime.ts.

Was die Anwendung kann

Erfassung

• Buchungen mit Beleg-, Leistungs- und Zahlungsdatum; jedes Datum hat eine eigene steuerliche Aufgabe (Regime, Soll-Versteuerung, Zuflussprinzip).
• Live-Vorschau: das Backend entscheidet über Steuersatz, Behandlung und Vorsteuerabzug – nicht das Formular.
• Reverse Charge (§13b), innergemeinschaftliche Erwerbe und Lieferungen, steuerfreie und nicht steuerbare Umsätze.
• Privatanteile, Bewirtung (70 %), offene Posten.
• Anlagevermögen mit linearer AfA zeitanteilig, GWG-Sofortabschreibung und Sammelposten; Kleinunternehmer schreiben vom Bruttobetrag ab.
• GoBD: keine Löschung, sondern Storno per Gegenbuchung; Festschreibung; Änderungsprotokoll.

Auswertungen

• EÜR in der Gliederung der Anlage EÜR, mit Anlagenverzeichnis.
• UStVA mit den amtlichen Kennzahlen, Ist- oder Soll-Versteuerung, monatlich oder vierteljährlich, mit Aufriss auf die Einzelbuchungen.
• BWA im Aufbau der BWA Form 01: Monat, kumuliert, Vorjahresvergleich, Quoten – wahlweise nach Zahlungs- oder Leistungszeitpunkt.

Ausgabe

• ELSTER über ERiC (siehe unten).
• DATEV Buchungsstapel im EXTF-Format (Version 700, Formatversion 13) plus Kontenbeschriftungen – das Paket für die Steuerkanzlei.
• GoBD-Datenträgerüberlassung (GDPdU, Format Z3) mit index.xml und CSV – das Paket für die Betriebsprüfung.
• EÜR und BWA zusätzlich als CSV.

ELSTER-Übermittlung

Ohne ERiC ist keine Übermittlung möglich – auch nicht mit einem eigenen XML-Versand. ERiC ist die einzige zugelassene Schnittstelle zur Finanzverwaltung. Die Bibliothek ist proprietär, darf nicht weitergegeben werden und ist deshalb hier nicht enthalten.

So wird sie eingebunden:

1. Im ELSTER-Entwicklerportal registrieren und ERiC für die eigene Plattform herunterladen.
2. .env.beispiel nach .env kopieren und ausfüllen: ERIC_LIB_PATH, ERIC_PLUGIN_PATH, ELSTER_ZERTIFIKAT, ELSTER_PIN, ELSTER_HERSTELLER_ID.
3. Erste Versuche mit ELSTER_TESTMERKER=700000004 – solche Übermittlungen haben keine steuerliche Wirkung.

Ist ERiC nicht eingerichtet, läuft die Anwendung im Simulationsmodus: das XML wird erzeugt, auf Wohlgeformtheit und Vollständigkeit geprüft und unter data/elster-ausgang/ abgelegt. Es wird nichts gesendet, und die Oberfläche sagt das ausdrücklich.

Die Übermittlung ist verbindlich und nicht zurückzunehmen. Der Endpunkt verlangt deshalb "bestaetigt": true, die Oberfläche eine Rückfrage.

Die Steuernummer wird automatisch vom Länderformat (123/456/78901) in das 13-stellige Bundesschema umgesetzt, das ELSTER erwartet – für alle 16 Bundesländer, siehe server/src/elster/steuernummer.ts.

Was vor dem Produktiveinsatz zu prüfen ist

Die Rechenwege sind mit Tests abgesichert, aber einige Angaben ändern sich jährlich und müssen gegen die amtlichen Vorgaben abgeglichen werden:

• Zeilennummern der Anlage EÜR – sie ändern sich fast jedes Jahr. Der fachliche Aufbau ist stabil, nur die Nummerierung nicht. Gepflegt werden sie in ZEILEN_NUMMERN in server/src/domain/euerZeilen.ts, getrennt von der Berechnung. Stand: an der Fassung 2024/2025 orientiert.
• ELSTER-Schemaversion – die Datenart-Version (UStVA_<Jahr>) und der Aufbau des Nutzdatenblocks müssen zu der Version passen, die im installierten ERiC steckt. Der erste Lauf sollte mit gesetztem Testmerker erfolgen.
• DATEV-Formatversion – der Export folgt Version 700 / Formatversion 13. Vor der ersten Übergabe eine Probedatei mit der Kanzlei einlesen.
• Kontenrahmen – server/src/kontenrahmen/skr04.ts ist ein praxisnaher Auszug aus dem SKR04, kein vollständiger Kontenrahmen. Konten lassen sich in der Oberfläche ergänzen und umwidmen.

Die Anwendung ersetzt keine steuerliche Beratung. Für die Richtigkeit der Erklärung bleibt die abgebende Person verantwortlich.

Aufbau

server/src/
  db.ts                 SQLite-Schema, Änderungsprotokoll
  domain/
    regime.ts           Zeitachse der Besteuerungsform, USt-Ermittlung, §19-Grenzen
    euer.ts             Einnahmen-Überschuss-Rechnung
    euerZeilen.ts       Gliederung + Zeilennummern je Veranlagungsjahr
    ustva.ts            Voranmeldung, Kennzahlen, Ist/Soll
    bwa.ts              BWA Form 01
    afa.ts              lineare AfA, GWG, Sammelposten
    geld.ts             Cent-Arithmetik, kaufmännische Rundung
  elster/
    steuernummer.ts     Länderformat -> Bundesschema (alle 16 Länder)
    ustvaXml.ts         ELSTER-Datenteil für die UStVA
    eric.ts             ERiC-Anbindung über koffi + Simulationsmodus
  export/
    datev.ts            EXTF-Buchungsstapel und Kontenbeschriftungen
    gdpdu.ts            GoBD-Datenträgerüberlassung
    zip.ts              minimaler ZIP-Writer
  routes/               HTTP-Schnittstelle
web/src/                Oberfläche (React, Vite)

Alle Beträge werden als ganzzahlige Cent geführt, Steuersätze als Basispunkte (1900 = 19 %). Damit gibt es keine Fließkommafehler in der Steuerberechnung.