# 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. ```bash npm install npm run seed # Beispieldaten mit Regimewechsel 2025 -> 2026 npm run dev # Backend (3311) + Frontend (5173) im Entwicklungsmodus ``` Für den Dauerbetrieb: ```bash 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 ```bash 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 . **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. ```bash 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=`. 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-`). ## 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///` 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: ```bash cat /proc/sys/fs/inotify/max_user_instances # meist 128 find /proc/*/fd -lname anon_inode:inotify | wc -l # tatsächlich belegt ``` Dauerhafte Abhilfe: ```bash 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: ```bash 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`](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](https://www.elster.de/elsterweb/entwickler) 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`](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`](server/src/domain/euerZeilen.ts), getrennt von der Berechnung. Stand: an der Fassung 2024/2025 orientiert. - **ELSTER-Schemaversion** – die Datenart-Version (`UStVA_`) 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.