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>
This commit is contained in:
Claude (KI) 2026-10-06 12:11:25 +02:00
parent 5478f564b8
commit 7ece71407b

112
docs/datenmodell.md Normal file
View file

@ -0,0 +1,112 @@
# 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)
```mermaid
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`).