diff --git a/docs/datenmodell.md b/docs/datenmodell.md new file mode 100644 index 0000000..fc09029 --- /dev/null +++ b/docs/datenmodell.md @@ -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`).