mivita/dev/2026-07-17-steuern/UMSETZUNG-fixes.md

Steuerberater-Abgleich 08+09/2025 — Analyse & Umsetzung der Fixes

Datum: 17.07.2026 Anlass: Korrektur-CSVs des Steuerberaters (Abgleich 08._09.2025-Konto-*.csv in diesem Ordner) zum DATEV-Export aus admin/payments/taxadvisor. Betroffene Exporte: datev_exports #9 (08/2025) und #10 (09/2025), generiert am 08.05.2026.

---

Lesehilfe zu den Abgleich-CSVs

Die Spalte „Betrag Test" des Steuerberaters ist nicht unser Exportbetrag, sondern der Saldo auf dem Erlöskonto nach DATEV-Steuerautomatik: Wir exportieren Bruttobeträge mit BU-Schlüssel (9 = 19 %, 8 = 7 %), DATEV rechnet die USt automatisch heraus.

Beispiel: Export 277,92 € brutto (BU 9) → 233,55 € netto auf 8400 = „Betrag Test".

Mit diesem Schlüssel lassen sich fast alle gemeldeten Zeilen exakt nachvollziehen.

---

Befund 1: Beträge ≥ 1.000 € massiv zu niedrig (kritisch)

Gemeldete Fälle: 202536817 (1.434,71 statt 230,28), 202536968 (1.044,69 statt 167,67), 202537532 (1.075,04 statt 172,55)

Ursache: ShoppingOrder::makeTaxSplit() speicherte net_split/tax_split mit number_format($value, 2) — also mit Tausendertrennzeichen ("1,434.70"). DatevExportService::parseNumber() machte daraus per str_replace(',', '.') den String "1.434.70" → floatval() = 1,43 €. Jede Rechnung mit ≥ 1.000 € Netto pro Steuersatz war im Export um den Faktor ~1000 zu niedrig.

Fix:

• app/Services/DatevExportService.php → parseNumber() erkennt jetzt US-Format (1,434.70), deutsches Format (1.434,70) und reine Tausendertrenner (1,434) korrekt. Nötig, weil die Altdaten in der DB das fehlerhafte Format behalten.
• app/Models/ShoppingOrder.php → makeTaxSplit() und makeHomepartyTaxSplit() schreiben neu mit number_format($value, 2, '.', '') (ohne Tausendertrenner).

---

Befund 2: Falsche Kontenzuordnung 8125 (igL) ↔ 8400/8300

Gemeldete Fälle (Auswahl): 202536848, 202536858, 202536910, 202537173, 202537290, 202538011, 202538144, 202538445/446, 202539399 (gehörten auf 8125, standen auf 8400) — umgekehrt 202536841, 202537251, 202537460, 202537543, 202538398 (standen auf 8125, gehörten auf 8400/8300).

Ursachen (mehrere):

1. Export nutzte den aktuellen Account-Zustand statt des Rechnungszustands. Die betroffenen Berater (z. B. User 781, 850, 974) hatten ihre USt-ID nach dem Kauf wieder gelöscht (reverse_charge_delete leert alle Felder). Die Rechnungen wurden damals korrekt ohne USt (igL) ausgestellt, der Export fand aber keine USt-ID mehr und buchte auf 8400.
2. Keinerlei Validierung der USt-ID: hasValidUstid prüfte nur „nicht leer". Dadurch lösten auch deutsche USt-IDs (202536841: DE296797691), offensichtliche Dummy-IDs (202538398: DE123456789) und formal ungültige Werte (202537460: 53618009 — gar kein USt-ID-Format) eine igL-Buchung auf 8125 aus.
3. Abgelaufene/ungültige IDs: Die VIES-Prüfung lief nur einmalig bei der Eingabe (202537251: ESY9284953M, validiert 08/2023, laut StB inzwischen ungültig).

Datenlage als Beleg: In 08+09/2025 hat jede DE-Bestellung ein tax_split; EU-Bestellungen ohne tax_split sind exakt die steuerfrei verkauften (AT: 71, ES: 14).

Fix:

• app/Services/DatevExportService.php → determineRevenueAccount(): Maßgeblich ist jetzt, wie die Rechnung tatsächlich ausgestellt wurde:
  • EU-Bestellung ohne tax_split (= ohne USt verkauft) → 8125 / BU 1 (igL) — unabhängig vom heutigen Account-Zustand.
  • EU-Bestellung mit tax_split (= mit USt berechnet) → 8400/8300 nach Steuersatz, nie 8125.
  • Drittland unverändert 8120 / BU 11.
• resolveEuUstid() verwirft deutsche und formal unplausible USt-IDs (neuer zentraler App\Services\VatIdService). Fehlt bei einer igL-Zeile die USt-ID, erscheint wie bisher eine Validierungs-Warnung im Export (validation_summary).

---

Befund 3: „Betrag fehlerhaft" durch doppelte Rechnungsnummern

Gemeldete Fälle: 202537208, 202537572, 202538182, 202538332 — exakt die vier Nummern, die in 08+09/2025 doppelt vergeben wurden (je zwei verschiedene Rechnungen/Bestellungen). Der StB sah unter einer Belegnummer die Summe zweier Rechnungen.

Ursache: Historisches Race bei der Nummernvergabe (Zähler-Setting invoice-number). Für Rechnungen ist das seit Invoice::makeNextInvoiceNumber() behoben (DB::transaction + lockForUpdate). Gutschriften nutzten aber denselben Zähler weiterhin ungesichert: CreditRepository::create() las die Nummer (plain read) und zählte erst viel später in finishUserCredit() hoch — dazwischen konnten parallele Läufe dieselbe Nummer ziehen. Folge in den Bestandsdaten: 38 Gutschriften teilen sich ihre laufende Nummer mit einer Rechnung.

Fix:

• app/Services/Credit.php → makeNextCreditNumber() delegiert an Invoice::makeNextInvoiceNumber() (atomar, gelockt).
• app/Repositories/CreditRepository.php → Nummer wird direkt bei der Erstellung atomar reserviert; das nachträgliche Hochzählen in finishUserCredit() entfällt.

Bestehende Duplikate in den Altdaten bleiben unverändert (nicht rückwirkend korrigierbar).

---

Befund 4: Gutschriften auf 4764 mit falschem BU-Schlüssel

Gemeldete Fälle: GS202536995 (67,47 statt 56,70), GS202538597 (14,88 statt 12,50)

Ursache: Beide Gutschriften wurden mit taxable = 3 (nicht USt-pflichtig / Ausland) ausgestellt — der Beleg weist keine USt aus. Der Export leitete den BU-Schlüssel aber vom aktuellen Account-Status ab und exportierte BU 9 (19 %) → DATEV rechnete fälschlich 19 % aus dem steuerfreien Betrag heraus.

Fix:

• app/Services/DatevExportService.php → determineCommissionTaxStatus() nutzt jetzt den taxable-Snapshot der Gutschrift (1 = BU 9, 2 = Kleinunternehmer BU 50, 3 = Ausland → Reverse Charge BU 94 bei EU). Nur Alt-Gutschriften ohne Snapshot (taxable = 0) fallen auf die Account-Logik zurück. Der Brutto-Aufschlag nutzt den in der Gutschrift gespeicherten tax_rate.

---

Befund 5: USt-ID-Prüfung nur einmalig (Anforderung Kevin)

Anforderung: USt-ID bei jeder Verwendung prüfen (v. a. im Checkout); bei ungültiger ID Hinweis anzeigen und mit USt berechnen; deutsche USt-IDs nie anerkennen.

Umsetzung — neuer zentraler Service app/Services/VatIdService.php:

• normalize(), isPlausibleFormat() (EU-Länderpräfix + Nummernteil), qualifiesForReverseCharge() (Format ok und nicht DE...), checkVies() (SOAP gegen ec.europa.eu VIES, Timeout konfigurierbar), checkViesCached() (24 h Cache; VIES-Ausfall nur 10 Min. gecacht).
• Eingabe im Account (UserRepository::reverse_charge_activate): nutzt den Service; deutsche USt-IDs → eigene Fehlermeldung (msg.VATID_german_not_allowed, in de/en/es/fr ergänzt). SSL-Verifikation ist jetzt aktiv (vorher deaktiviert).
• Checkout (UserService::performUserTaxShippingCountry): Wenn Reverse-Charge greifen würde, wird die USt-ID live (gecacht) geprüft:
  • ungültig / DE / Format falsch → Reverse-Charge-Status wird entzogen (reverse_charge = 0, reverse_charge_valid = null; die USt-ID selbst bleibt zur Neu-Validierung erhalten), Growl-Hinweis msg.VATID_no_longer_valid_taxes_applied, Bestellung läuft mit USt weiter.
  • VIES nicht erreichbar → gespeicherter Status gilt (Checkout wird nie blockiert), Log-Warnung.
• Konfiguration: services.vies.enabled (VIES_ENABLED, Default true) und services.vies.timeout (VIES_TIMEOUT, Default 10 s). In phpunit.xml deaktiviert.

---

Nicht im Code fixbar / offene Punkte

Punkt	Status
202506145 / 202506147: existieren nicht in user_invoices — stammen aus einem fremden Nummernkreis des Kunden (dort werden teils eigene Rechnungen + Stornorechnungen erstellt)	Im Abgleich ignorieren und als „extern" markieren (Vorgabe Kevin)
Stornos 2025 (202536978, 202537144, 202537513 teilweise, 202539501): im System nicht als Storno erfasst — Stornorechnungen (cancellation = 1) existieren erst ab 01/2026	Manuelle Abstimmung mit dem StB / Datenpflege
202535876: Juli-Rechnung, Gutschrift im September — monatsübergreifende Korrekturen kennt der Export konzeptionell nicht	Offen, bei Bedarf separates Konzept
202539011: „Rechnung liegt uns nicht vor" — Daten sind im System vorhanden (66,22 € + 285,18 €)	PDF an StB nachliefern
Exporte 08+09/2025 neu generieren, sobald die Fixes deployed sind	To-do nach Merge

---

Tests

• tests/Unit/Services/DatevExportServiceTest.php — erweitert: Tausendertrenner-Parsing, igL-Semantik (soldTaxFree), Ablehnung deutscher/unplausibler USt-IDs, taxable-Snapshot-Logik der Gutschriften.
• tests/Unit/Services/VatIdServiceTest.php — neu: Normalisierung, Formatprüfung, DE-Ablehnung, VIES-Verhalten (deaktiviert/unplausibel).
• tests/Feature/CheckoutVatIdRevalidationTest.php — neu: 6 Checkout-Szenarien (VIES ok / ungültig / ausgefallen, DE-ID, Format-Müll, Ländercode-Mismatch).

Alle 63 betroffenen Tests grün; ./vendor/bin/pint sauber. Vorbestehende, unabhängige Testfehler (InvoiceServiceTest, tests/Unit/BusinessPlan/*, makeUser()-Kollision der Gesamtsuite) bestehen unverändert auch auf dem Stand vor diesen Änderungen.

Geänderte Dateien

• app/Services/DatevExportService.php — parseNumber, Kontenlogik, USt-ID-Filter, Gutschrift-BU
• app/Services/VatIdService.php — neu, zentrale USt-ID-Prüfung
• app/Services/UserService.php — Live-Prüfung im Checkout + Entzug + Hinweis
• app/Services/Credit.php, app/Repositories/CreditRepository.php — atomare Nummernvergabe
• app/Repositories/UserRepository.php — VIES via Service, DE-Ablehnung bei Eingabe
• app/Models/ShoppingOrder.php — number_format ohne Tausendertrenner
• config/services.php, phpunit.xml — VIES-Konfiguration
• resources/lang/{de,en,es,fr}/msg.php — neue Meldungen