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>
7.1 KiB
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 (Nummernkreisinvoice), 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).