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:
parent
5478f564b8
commit
7ece71407b
1 changed files with 112 additions and 0 deletions
112
docs/datenmodell.md
Normal file
112
docs/datenmodell.md
Normal 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`).
|
||||
Loading…
Add table
Add a link
Reference in a new issue