kundencenter/docs/datenmodell.md
Claude (KI) 7ece71407b Datenmodell und Statusautomaten dokumentiert (#8)
ER-Diagramm (Mermaid) aus frisch migriertem Schema (Migrationen 001–041,
Fremdschlüssel aus information_schema), Rechnungs-Eigenbau statt
"Rechnungsspiegel" (Snapshots, Storno, Abrechnungsperioden), Übergangs-
tabellen für Bestellung, Vertrag, Rechnung, Ressource, Ticket, Posteingang
und Aufträge mit Verweis auf die Tests der erlaubten/verbotenen Übergänge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 12:11:25 +02:00

7.1 KiB
Raw Permalink Blame History

Datenmodell und Statusautomaten

Stand: 06.10.2026, Migrationen 001–041. Das Diagramm ist aus einer frisch migrierten Datenbank abgeleitet (information_schema: Tabellen und Fremdschlüssel), nicht aus Annahmen. Einstellungs-Einzeiler (*_settings mit id = 1) sind nur in der Liste unten aufgeführt.

ER-Diagramm (Kern)

erDiagram
  organizations ||--o{ memberships : hat
  users ||--o{ memberships : ist
  organizations ||--|| billing_profiles : Rechnungsprofil
  users ||--o{ sessions : ""
  users ||--o| mfa_totp : ""
  users ||--o{ recovery_codes : ""
  users ||--o{ user_tokens : "Einladung/Reset"

  products ||--o{ product_versions : Version
  product_versions ||--o{ product_term_prices : Laufzeitstaffel
  tax_rates ||--o{ product_versions : ""
  connector_instances ||--o{ products : "Bereitstellung über"

  organizations ||--o{ orders : ""
  orders ||--o{ order_items : ""
  product_versions ||--o{ order_items : ""
  order_items ||--|| contracts : "erzeugt"
  organizations ||--o{ contracts : ""
  product_versions ||--o{ contracts : ""
  contracts }o--o| resources : "bereitgestellt als"
  contracts ||--o{ contract_renewal_tokens : "Behalten/Kündigen-Link"

  connector_instances ||--o{ resources : ""
  organizations ||--o{ resources : ""
  resources ||--o| panel_credentials : ""

  organizations ||--o{ invoices : ""
  invoices ||--o{ invoice_items : ""
  contracts ||--o{ invoice_items : "abgerechnet in"
  invoices |o--o| invoices : "Storno von"
  contracts ||--o{ invoice_billing_periods : "Periode"
  invoices ||--o{ invoice_billing_periods : ""

  organizations ||--o{ tickets : ""
  tickets ||--o{ ticket_messages : ""
  ticket_messages ||--o{ ticket_attachments : ""
  tickets }o--o| resources : "bezieht sich auf"
  tickets }o--o| domain_records : "bezieht sich auf"
  tickets ||--o| ticket_discord_threads : "Discord-Kanal"
  inbox_messages }o--o| tickets : "zugeordnet / Vorschlag"
  inbox_messages }o--o| users : "Absender / Vorschlag"

Nicht im Diagramm (eigenständig oder nur Protokoll): audit_events (Hash-Kette, unveränderlich per Trigger), audit_settings, audit_retention_checkpoints, jobs (Queue, ADR 0003), mail_log, mail_templates, mail_sender_profiles, domain_records/domain_settings/domain_tlds (Domain-Aufstellung, Bezug zu Organisation/Ressource über Spalten), license_state/license_signing_keys (eigene Lizenz), number_sequences/customer_sequences (Nummernkreise), system_alerts/system_heartbeats (Betriebsalarme), schema_migrations/schema_migrations_dirty, Einstellungen: settings, company_settings, smtp_settings, imap_settings, discord_settings, discord_oauth_states, backup_settings, backup_targets.

Rechnungen (Eigenbau, ersetzt den früheren Begriff „Rechnungsspiegel“)

Rechnungen werden im Kundencenter selbst erzeugt (#5, keine externe Rechnungssoftware):

  • invoices: Nummer erst beim Ausstellen (Nummernkreis invoice), Summen in Cent, eingefrorene Absender-/Empfängerdaten (seller_snapshot_json, buyer_snapshot_json) ab dem Ausstellen; Storno als eigene Rechnung mit negativen Beträgen (cancels_invoice_id ↔ cancelled_by_invoice_id).
  • invoice_items: Positionen mit Steuersatz und Rabatt je Position, optional Bezug auf einen Vertrag.
  • invoice_billing_periods: welche Vertragsperiode mit welcher Rechnung abgerechnet ist (Abrechnungslauf, #50).
  • Verträge tragen den Preis-Snapshot (price_snapshot_json) aus der Bestellung; spätere Katalogänderungen wirken nicht rückwirkend.

Statusautomaten

Bestellung (orders.status) – platform/statemachine.ts, nur über transition()

von \ Ereignis approve reject cancel start_provisioning complete fail retry
pending_approval approved rejected cancelled
approved cancelled provisioning
provisioning completed failed
failed cancelled provisioning

Endzustände ohne Ausgang: completed, rejected, cancelled. Nebenwirkungen: Bei der Anlage/Freigabe entstehen die Verträge im Zustand pending (mit Preis-Snapshot); complete aktiviert sie (activate); fail speichert failure_note und markiert unklare Provider-Ergebnisse (failure_ambiguous) – dann erst Abgleich, kein blinder Neuversuch. Test: packages/platform/test/logic.test.ts „Bestellung: erlaubte Übergänge“ und „alle anderen Übergänge sind verboten“ (alle Kombinationen).

Vertrag (contracts.status)

von \ Ereignis activate suspend unsuspend cancel expire fail
pending active cancelled failed
active suspended cancelled expired
suspended active cancelled expired

Kündigung durch Kunden setzt zunächst nur cancel_requested_at/cancel_effective_at; der Vertragslauf im Worker (processContractLifecycle) beendet bzw. verlängert zum Laufzeitende (renewal = auto). Rückabwicklung: kein Weg zurück aus cancelled/expired/failed – ein neuer Vertrag entsteht nur über eine neue Bestellung. Test: logic.test.ts „Vertrag: alle Übergänge vollständig geprüft“, Laufzeit/Kündigung ebenda.

Rechnung (invoices.status)

von Aktion nach Bedingung / Nebenwirkung
draft Positionen speichern draft nur unter Zeilensperre im Status draft (#95)
draft ausstellen open Firmenstammdaten vollständig, ≥ 1 Position; Nummer + Snapshots, Mail an Rechnungsadresse
draft löschen – gibt Abrechnungsperioden frei
open als bezahlt markieren paid
open stornieren cancelled neue Storno-Rechnung (open) mit negativen Beträgen; Perioden bleiben belegt bis zur Freigabe

Verboten (409/403): Positionen ändern außer im Entwurf, ausgestellte Rechnung löschen, doppelt ausstellen/stornieren/bezahlen. Tests: apps/api/test/invoices.test.ts (inkl. Nebenläufigkeit), billing.test.ts.

Ressource (resources.state, vom Anbieter abgeglichen)

active, suspended, expired, error, unknown – kein eigener Automat: der Zustand spiegelt den Anbieter (Connector-Abgleich). Aktionen (sperren, entsperren, verlängern, löschen) laufen als Jobs; unklare Ergebnisse → needs_review und Abgleich statt Annahme.

Ticket (tickets.status)

open, pending_customer, pending_staff, resolved, closed. Automatisch: Kundenantwort (Web, Mail mit Bezug, Discord) → pending_staff; Personalantwort → pending_customer; interne Notiz ändert nichts. Personal (tickets.write) kann den Status frei setzen; closed ist für Antworten gesperrt (409, neues Ticket nötig). Kein fester Automat – bewusst, weil Support-Abläufe flexibel bleiben sollen.

Posteingang (inbox_messages.status)

unmatched → matched (an Ticket angehängt) | created (neues Ticket) | ignored. Nur aus unmatched, atomar (Doppelklick erzeugt kein zweites Ticket, #107).

Auftrag (jobs.status)

scheduled → running → succeeded | retrying (→ running) | failed | needs_review | partial/waiting_external (Connector-spezifisch). Absturz: running ohne Herzschlag → retrying, destruktiv → needs_review (security.test.ts).