kundencenter/docs/management-auswertung.md
Claude (KI) bcf188df34 Management-Auswertung: Rolle nur mit analytics.read, lesender MVP (#133)
- Konzept docs/management-auswertung.md: Rechte, Kennzahlen mit
  Definitionen und Quellen, fachlich offene Punkte (nichts erfunden).
- Neue Personalrolle management (Migration 045) mit genau analytics.read;
  niemandem automatisch zugewiesen, vergeben nur durch Superadmin.
- GET /analytics/summary (nur lesend): Kunden/Verträge, Rechnungen
  ausgestellt/Storno/nach Storno, als bezahlt markiert, offen/überfällig,
  nach Steuersatz, Kategorie und Monat; Datenstand, EUR, Definitionen.
- Seite /auswertung mit Zeitraumfilter.
Tests an festen Daten (Storno, 19/7 %, Zeitraumgrenze, Entwurf) und
Rechte-/Schreibweg-Tests. Drift-Test nutzt vorhandene Steuersätze.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 16:01:31 +02:00

3.5 KiB
Raw Blame History

Management-Auswertung („CEO-Zugang“) – Konzept und MVP

Stand: 07.10.2026 · Plane #133 (aus Björns Feedback in #117). Ersetzt weder die Lizenzmatrix (#113) noch Preise/Bundles (#117).

Ziel

Ein rein lesender Überblick über Kunden, Verträge und Rechnungen für die Geschäftsführung – aus den vorhandenen Daten, ohne externes Analysesystem, ohne Schreibrechte und ohne Zugriff auf Einzelvorgänge.

Rechte

  • Neue Personalrolle Management (staff_role = 'management') mit genau einem Recht: analytics.read. Sie hat keine weiteren Rechte (keine Kunden-, Rechnungs-, Verwaltungs- oder Schreibrechte) – per Test nachgewiesen.
  • Die Rolle wird niemandem automatisch zugewiesen; vergeben darf sie nur ein Superadmin (wie admin/superadmin). Bestehende Rollen bekommen analytics.read nicht.
  • Auswertungen sind organisationsübergreifend und deshalb nur für Personal mit dieser Rolle. Ein Kundenzugang zu eigenen Kennzahlen ist nicht Teil des MVP (wäre mandantenbezogen über canInOrg zu bauen).

Seite /auswertung (MVP, umgesetzt)

Zeitraumfilter (Rechnungsdatum von–bis, beide Tage einschließlich), Datenstand und Währung sichtbar. Kacheln und Tabellen:

Kennzahl Definition Quelle
Aktive Kunden (jetzt), gesperrt, neu im Zeitraum organizations.status; neu = created_at im Zeitraum organizations
Aktive Verträge (jetzt), neu, beendet im Zeitraum contracts.status; neu = created_at, beendet = cancelled_at im Zeitraum contracts
Ausgestellt netto/Steuer/brutto Rechnungen mit Rechnungsdatum im Zeitraum, ohne Entwürfe, ohne Stornorechnungen (auch später stornierte Originale zählen hier) invoices
Stornos Stornorechnungen (cancels_invoice_id gesetzt) im Zeitraum, negative Beträge invoices
Netto/brutto nach Storno ausgestellt + Stornos –
Als bezahlt markiert Originalrechnungen im Status paid – Rechnungsstatus, kein gebuchter Zahlungseingang invoices
Offen / davon überfällig Status open; überfällig = Fälligkeit vor heute invoices
Nach Steuersatz Summen der Positionen je Steuersatz (inkl. Stornos) invoice_items
Nach Produktkategorie Position → Vertrag → Produkt (hosting, license, addon, service); ohne Vertragsbezug (z. B. Domains, manuell) eigene Zeile invoice_items, contracts, products
Nach Monat netto ausgestellt, Stornos, nach Storno je Rechnungsmonat invoices

Alle Beträge in Cent/EUR, netto/Steuer/brutto getrennt beschriftet. Kein Umsatz, Gewinn, Forecast oder Bilanzwert.

Abnahme (umgesetzt)

apps/api/test/analytics.test.ts: feste Testdaten mit Storno, 19 %/7 %, Zeitraumgrenze (31.01./01.02.), Entwurf (zählt nicht), überfälliger Rechnung; Rechte: support/accounting/admin/superadmin/Kunde → 403, Management → 200, Management ohne sonstige Rechte und ohne Schreibweg, Rolle vergibt nur Superadmin.

Fachlich offen (bewusst nicht erfunden)

  • Zahlungseingänge/Liquidität: erst mit Zahlungserfassung (#56) bzw. Zahlungsanbieter.
  • Wiederkehrender Umsatz (MRR/ARR), Kundenwert, Abwanderung: Definitionen müssen festgelegt werden (z. B. Umgang mit Jahresverträgen, Rabatten, Stornos).
  • Einkauf/Marge (Domains haben EK, Hosting/Lizenzen nicht): erst mit vollständigen Einkaufspreisen.
  • Kennzahlen je Kunde/Produkt im Detail, Export, Diagramme.
  • Simulations-/Testdaten für ein „Analysetestsystem“: nur in einer isolierten Umgebung (z. B. ops/dev/run.sh mit eigener Datenbank), nie in der Produktivdatenbank.