commit 7ac1371aff7dd19b61dfcda2d488906dc5c094f0 Author: Olaf Rabing Date: Mon May 18 04:37:23 2026 +0000 Add AI workspace reviews diff --git a/AI Workspace einrichten Erste Schritte.docx b/AI Workspace einrichten Erste Schritte.docx new file mode 100644 index 0000000..fccf30a Binary files /dev/null and b/AI Workspace einrichten Erste Schritte.docx differ diff --git a/README.md b/README.md new file mode 100644 index 0000000..fe577e5 --- /dev/null +++ b/README.md @@ -0,0 +1,29 @@ +# Hosting-Backoffice + +Ein europäisches, kundenzentriertes Hosting-Backoffice für kleine Anbieter, Webagenturen, Freelancer und IT-Dienstleister. + +## Vision + +Ein europäisches Hosting-Backoffice für kleine Anbieter, das Ordnung in Kunden, Hostingpakete, Domains, Rechnungen und Support bringt – professionell, verständlich und nutzbar ab dem ersten Kunden. + +## Arbeits-Slogan + +Professionelles Hosting-Backoffice. Einfach ab dem ersten Kunden. + +## Zielgruppe + +Kleine europäische Hostinganbieter, Webagenturen, Freelancer, IT-Dienstleister und Einzelunternehmer mit ca. 1–500 Kunden. + +## Grundarchitektur + +- Standalone-Core +- Laravel +- REST API +- modulare Integrationen +- optionales WordPress-Plugin +- Mandantenfähigkeit von Anfang an vorbereiten +- kundenzentrierter Ansatz + +## V1-Ziel + +Eine erste produktiv nutzbare Version für 3–5 echte Bestandskunden. diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.10.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.10.zip new file mode 100644 index 0000000..1005b38 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.10.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.11.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.11.zip new file mode 100644 index 0000000..d41e94d Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.11.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.12.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.12.zip new file mode 100644 index 0000000..0414ca3 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.12.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.13.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.13.zip new file mode 100644 index 0000000..7c07950 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.13.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.14.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.14.zip new file mode 100644 index 0000000..91b050a Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.14.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.15.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.15.zip new file mode 100644 index 0000000..a4de63c Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.15.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.16.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.16.zip new file mode 100644 index 0000000..02b2d1c Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.16.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.17.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.17.zip new file mode 100644 index 0000000..612add5 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.17.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.18.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.18.zip new file mode 100644 index 0000000..8f2a384 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.18.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.19.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.19.zip new file mode 100644 index 0000000..09bc43b Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.19.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.2.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.2.zip new file mode 100644 index 0000000..db17bbf Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.2.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.20.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.20.zip new file mode 100644 index 0000000..c6c6397 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.20.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.3.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.3.zip new file mode 100644 index 0000000..0612528 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.3.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.4.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.4.zip new file mode 100644 index 0000000..baa26aa Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.4.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.5.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.5.zip new file mode 100644 index 0000000..bc8c677 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.5.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.6.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.6.zip new file mode 100644 index 0000000..1fa459a Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.6.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.7.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.7.zip new file mode 100644 index 0000000..ff1f692 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.7.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.8.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.8.zip new file mode 100644 index 0000000..7b9844e Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.8.zip differ diff --git a/Z-Archiv/Hosting-Backoffice-Update-v0.9.zip b/Z-Archiv/Hosting-Backoffice-Update-v0.9.zip new file mode 100644 index 0000000..01bd744 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice-Update-v0.9.zip differ diff --git a/Z-Archiv/Hosting-Backoffice_Basisdateien_v0.1.zip b/Z-Archiv/Hosting-Backoffice_Basisdateien_v0.1.zip new file mode 100644 index 0000000..f773ea9 Binary files /dev/null and b/Z-Archiv/Hosting-Backoffice_Basisdateien_v0.1.zip differ diff --git a/architecture/api-strategy-v0.1.md b/architecture/api-strategy-v0.1.md new file mode 100644 index 0000000..892f627 --- /dev/null +++ b/architecture/api-strategy-v0.1.md @@ -0,0 +1,47 @@ +# API Strategy v0.1 + +## Grundprinzip + +Hosting-Backoffice ist API-first aufgebaut. + +Alle Module und spätere Erweiterungen sollen über definierte API- und Service-Schnittstellen kommunizieren. + +## API-Typ + +V1: REST API + +Später möglich: +- GraphQL +- interne Service-Bus-Strukturen +- Webhooks + +## API-Bereiche + +- Kunden +- Verträge +- Domains +- Hostingpakete +- Rechnungen +- Tickets +- Dokumente +- Server +- Integrationen + +## API-Sicherheit + +Alle API-Zugriffe benötigen: +- Authentifizierung +- Rechteprüfung +- Auditierbarkeit +- Rate-Limiting +- Logging + +## Versionierung + +Beispiel: +- /api/v1/ +- /api/v2/ + +## WordPress-Plugin + +Das spätere WordPress-Plugin nutzt ausschließlich die REST API. Keine direkte Datenbankkopplung. diff --git a/architecture/api-strategy-v0.2.md b/architecture/api-strategy-v0.2.md new file mode 100644 index 0000000..8011c49 --- /dev/null +++ b/architecture/api-strategy-v0.2.md @@ -0,0 +1,91 @@ +# API Strategy v0.2 + +## Zweck +Dieses Dokument konkretisiert API-first nach dem Architekturreview. + +## Kurz erklärt +API-first bedeutet: + +```text +Die Schnittstelle wird als Vertrag geplant, +nicht nachträglich aus Controllern abgeleitet. +``` + +## Entscheidung +V1 verwendet REST API mit OpenAPI 3.x als Spezifikation. + +## OpenAPI +OpenAPI ist eine maschinenlesbare Beschreibung der API. + +Sie definiert: + +- Endpoints +- Datenformate +- Auth +- Fehler +- Parameter +- Responses + +## API-Konventionen + +### Versionierung + +```text +/api/v1/ +``` + +### Pagination +Cursor Pagination wird bevorzugt. + +### Fehlerformat +Problem Details nach RFC 7807 wird als Zielmodell verwendet. + +### Idempotenz +Für kritische POST-Vorgänge wird ein Idempotency-Key vorbereitet. + +Idempotenz bedeutet: + +```text +Ein Vorgang kann mehrfach gesendet werden, +ohne mehrfach ausgeführt zu werden. +``` + +### Filtering + +```text +filter[status]=active +filter[customer_id]=123 +``` + +### Sorting + +```text +sort=-created_at +``` + +## Auth +V1 nutzt Laravel Sanctum gemäß ADR 0006. + +## Long Running Jobs +Lange Vorgänge laufen asynchron. + +Beispiele: + +- große Importe +- Syncs +- spätere Migrationen + +Sie erhalten Job-Status-Endpunkte. + +## Webhooks +Webhooks sind nicht V1-Pflicht, werden aber architektonisch vorbereitet. + +Webhook bedeutet: + +```text +Das System informiert andere Systeme automatisch, +wenn ein Ereignis passiert. +``` + +## Nächster Schritt +OpenAPI-Stub für V1 erstellen. diff --git a/architecture/core-architecture-v0.1.md b/architecture/core-architecture-v0.1.md new file mode 100644 index 0000000..5738e9c --- /dev/null +++ b/architecture/core-architecture-v0.1.md @@ -0,0 +1,44 @@ +# Core Architecture v0.1 + +## Grundarchitektur + +Hosting-Backoffice basiert auf einem modularen Standalone-Core mit REST API. + +Die Plattform soll modular erweiterbar, kundenzentriert, API-first, mandantenfähig vorbereitbar, sicher und verständlich sein. + +## Technologischer Ansatz + +- Backend: Laravel +- API: REST API +- Datenbank: MariaDB oder PostgreSQL +- Frontend: Laravel Blade oder später Vue/Nuxt +- Integrationen: modular angebunden, niemals direkt im Core verdrahten + +## Architekturprinzip + +Der Core enthält ausschließlich zentrale Datenobjekte und Kernlogik. + +Externe Systeme werden über Module/Integrationen angebunden. + +## Core-Module + +- Benutzer & Rechte +- Kunden +- Verträge +- Produkte +- Domains +- Hostingpakete +- Server +- Dokumente +- Audit-Logs +- Benachrichtigungen +- API +- Einstellungen + +## Integrationsprinzip + +Der Core kennt keine direkte Anbieterlogik. + +Nicht: Customer → direkt Lexware + +Sondern: Customer → Billing Interface → Lexware Modul diff --git a/architecture/core-architecture-v0.2.md b/architecture/core-architecture-v0.2.md new file mode 100644 index 0000000..16f9f89 --- /dev/null +++ b/architecture/core-architecture-v0.2.md @@ -0,0 +1,72 @@ +# Core Architecture v0.2 + +## Zweck +Dieses Dokument ersetzt die bisherige Core-Definition aus v0.1. + +## Wichtigste Änderung +Der Core wird deutlich verkleinert. + +In v0.1 war der Core zu groß und enthielt zu viele Fachdomänen. + +## Core enthält nur noch + +- Identity +- Authentication +- Tenant Context +- RBAC / Policies +- Audit Base +- Module Registry +- Settings Base +- Event Routing +- API Base +- System Health + +## Core enthält nicht + +- Kundenfachlogik +- Vertragsfachlogik +- Produktfachlogik +- Domainfachlogik +- Hostingfachlogik +- Billingfachlogik +- Ticketfachlogik +- Dokumentenarchivfachlogik +- Integrationslogik + +## Service-Module + +- Customers +- Contracts +- Products +- Domains +- Hosting +- Billing +- Tickets +- Documents +- Notifications + +## Integrationsmodule + +- KeyHelp +- 1blu +- Lexware +- Invoice Ninja +- SMTP/Transactional Mail später +- Payment-Adapter später + +## Grundregel + +Wenn ein Bereich fachliche Geschäftslogik enthält, gehört er nicht in den Core. + +## Kommunikation + +Module kommunizieren über: + +- Service Contracts +- Events +- API-Schichten +- External References + +## Ziel + +Der Core soll stabil bleiben, auch wenn Fachmodule wachsen oder ersetzt werden. diff --git a/architecture/data-model-v0.1.md b/architecture/data-model-v0.1.md new file mode 100644 index 0000000..f9b7ae7 --- /dev/null +++ b/architecture/data-model-v0.1.md @@ -0,0 +1,96 @@ +# Data Model v0.1 + +## Grundprinzip + +Hosting-Backoffice ist kundenzentriert aufgebaut. + +Der Kunde ist das zentrale Objekt. + +## Hauptobjekte + +### Kunde +- Stammdaten +- Ansprechpartner +- Kontaktdaten +- Kundennummer +- Status +- Historie + +### Vertrag +- Vertragsnummer +- Laufzeiten +- Kündigungsstatus +- Abrechnungsmodell +- Produktreferenzen + +### Produkt +- Produktname +- Beschreibung +- Preis +- Abrechnungsintervall +- Status + +### Domain +- Domainname +- TLD +- Registrar +- Registrar-Account +- Laufzeiten +- Status + +### Registrar-Account +- Anbieter +- Accountbeschreibung +- Zugangsdaten/API-Referenzen +- Status + +### Hostingpaket +- Paketname +- Serverzuordnung +- Ressourcen +- Status + +### Server +- Hostname +- Rolle +- Provider +- KeyHelp-Referenz +- Status + +### Rechnung +- Rechnungsnummer +- Rechnungsdatum +- Betrag +- Zahlungsstatus +- externes System + +### Zahlung +- Zahlungsart +- Status +- externe Referenzen +- Gebührenregeln später möglich + +### Ticket +- Status +- Priorität +- Verlauf +- interne Notizen + +### Dokument +- Datei +- Hashes +- Archivinformationen +- Referenzen + +### Audit-Log +- Benutzer +- Aktion +- Zeitstempel +- Objektbezug +- Änderungshistorie + +## Mandantenfähigkeit + +Von Anfang an vorbereiten: +- organisation_id +- tenant_id diff --git a/architecture/data-model-v0.2-direction.md b/architecture/data-model-v0.2-direction.md new file mode 100644 index 0000000..a0fc75f --- /dev/null +++ b/architecture/data-model-v0.2-direction.md @@ -0,0 +1,78 @@ +# Data Model v0.2 — Korrekturrichtung + +## Zweck +Dieses Dokument beschreibt die Richtung für das überarbeitete Datenmodell v0.2. + +## Hauptänderungen gegenüber v0.1 + +- `organisation_id` wird entfernt bzw. nicht standardmäßig verwendet +- `tenant_id` wird zentrale Mandantenreferenz +- anbieter-spezifische Felder werden entfernt +- External References werden eingeführt +- Kunde wird in Customer / Party / Address / ContactPoint aufgeteilt +- Billing wird eigene Domäne +- Core wird fachlich verkleinert + +## Zentrale Tabellenbereiche + +### Core +- tenants +- users +- roles +- permissions +- module_registry +- audit_logs +- settings +- external_references +- secrets_references + +### Customer Module +- customers +- parties +- addresses +- contact_points +- customer_contacts + +### Contract Module +- contracts +- contract_items +- contract_status_history + +### Product Module +- products +- product_prices +- product_tax_metadata + +### Domain Module +- domains +- domain_status_history +- registrar_accounts + +### Hosting Module +- hosting_packages +- servers +- hosting_assignments +- hosting_status_history + +### Billing Module +- invoice_references +- payment_references +- billing_accounts +- payment_methods + +### Ticket Module +- tickets +- ticket_messages +- ticket_notes +- ticket_status_history + +### Document Module +- documents +- document_hashes +- document_links + +## Wichtig +Dieses Dokument ist noch kein vollständiges ER-Modell. + +Nächster Schritt: +- ER-Modell mit Beziehungen und Kardinalitäten erstellen. diff --git a/architecture/deployment-strategy-v0.1.md b/architecture/deployment-strategy-v0.1.md new file mode 100644 index 0000000..d32ee4a --- /dev/null +++ b/architecture/deployment-strategy-v0.1.md @@ -0,0 +1,32 @@ +# Deployment Strategy v0.1 + +## Grundprinzip + +Hosting-Backoffice soll sicher, reproduzierbar und verständlich installiert werden können. + +## V1-Ansatz + +- Laravel-Anwendung +- Webserver mit PHP +- MariaDB oder PostgreSQL +- Composer +- Queue optional +- Cron/Scheduler + +## Später möglich + +- Docker-Deployment +- SaaS-Variante +- Installer +- Update-System +- Systemchecks + +## Sicherheitsprinzip + +Produktivsysteme dürfen nicht direkt durch KI-Agenten verändert werden. + +Änderungen laufen über: +- Entwicklungsumgebung +- Tests +- Review +- kontrolliertes Deployment diff --git a/architecture/gobd-archive-strategy-v0.1.md b/architecture/gobd-archive-strategy-v0.1.md new file mode 100644 index 0000000..7a12444 --- /dev/null +++ b/architecture/gobd-archive-strategy-v0.1.md @@ -0,0 +1,41 @@ +# GoBD & Archive Strategy v0.1 + +## Grundprinzip + +Dokumente und relevante Änderungen sollen nachvollziehbar und revisionsfreundlich gespeichert werden. + +## Ziele + +Das System soll: +- PDFs archivieren +- Änderungen nachvollziehbar machen +- Auditinformationen speichern +- Dokumente referenzieren +- Hash-Prüfungen ermöglichen + +## Dokumenttypen + +- Rechnungen +- Vertragsdokumente +- Anhänge +- Supportdokumente +- Importdateien + +## V1 + +- PDFs speichern +- Hashes speichern +- Audit-Logs schreiben +- Archivmetadaten speichern + +## Später möglich + +- WORM-Speicher +- S3 Object Lock +- externe Archivsysteme +- Langzeitarchivierung +- Signaturprüfungen + +## Wichtig + +Hosting-Backoffice ist zunächst kein vollständiges DMS oder Buchhaltungssystem. diff --git a/architecture/hosting-strategy-v0.1.md b/architecture/hosting-strategy-v0.1.md new file mode 100644 index 0000000..f7bb29d --- /dev/null +++ b/architecture/hosting-strategy-v0.1.md @@ -0,0 +1,51 @@ +# Hosting Strategy v0.1 + +## Grundprinzip + +Hosting-Backoffice ist kundenzentriert aufgebaut. + +Server, Domains und Hostingpakete werden zentral verwaltet. + +## Hostingbereiche + +### Hostingpakete +- Zuordnung zu Kunden +- Zuordnung zu Servern +- Status +- Ressourcen später möglich + +### Domains +- Registrar-Zuordnung +- Laufzeiten +- Status +- Kundenzuordnung + +### Server +- zentrale Serverobjekte +- Rollen später möglich +- KeyHelp-Referenzen + +## V1 + +Unterstützt: +- KeyHelp +- 1blu Business + +## Registrarstrategie + +V1: +- Import +- manuelle Zuordnung +- mehrere Accounts + +Später: +- API-Synchronisation +- mehrere Registrare +- TLD-Regeln +- Registrarrouting + +## Nicht Teil von V1 + +- automatische Provisionierung +- VM-Orchestrierung +- Cloudmanagement diff --git a/architecture/integration-adapter-pattern-v0.1.md b/architecture/integration-adapter-pattern-v0.1.md new file mode 100644 index 0000000..8528c3d --- /dev/null +++ b/architecture/integration-adapter-pattern-v0.1.md @@ -0,0 +1,38 @@ +# Integration Adapter Pattern v0.1 + +## Grundprinzip + +Externe Anbieter werden über Adapter angebunden. + +Der Core kennt keine direkte Anbieterlogik. + +## Beispiel + +Nicht: +- Kunde → direkt Lexware + +Sondern: +- Kunde → Billing Interface → Lexware Adapter + +## Adapterbereiche + +- Billing Adapter +- Registrar Adapter +- Hosting Panel Adapter +- Payment Reference Adapter +- Notification Adapter + +## Vorteile + +- Anbieter austauschbar +- Core bleibt stabil +- Module sind testbar +- spätere Erweiterungen werden einfacher + +## Anforderungen an Adapter + +- definierte Interfaces +- Fehlerbehandlung +- Logging +- Auditierbarkeit bei kritischen Aktionen +- sichere Speicherung von Zugangsdaten diff --git a/architecture/logging-monitoring-strategy-v0.1.md b/architecture/logging-monitoring-strategy-v0.1.md new file mode 100644 index 0000000..bc89582 --- /dev/null +++ b/architecture/logging-monitoring-strategy-v0.1.md @@ -0,0 +1,34 @@ +# Logging & Monitoring Strategy v0.1 + +## Grundprinzip + +Alle wichtigen Aktionen sollen nachvollziehbar sein. + +Das System soll Fehler erkennen, Änderungen protokollieren und Systemzustände überwachen können. + +## Logging + +Geplant: +- Login-Logs +- API-Logs +- Import-Logs +- Fehler-Logs +- Ticketaktionen +- Benutzeraktionen + +## Audit-Logs + +Audit-Logs sind getrennt von technischen Logs. + +Sie dienen Nachvollziehbarkeit, Compliance und Archivierung. + +## Monitoring später + +- Serverstatus +- API-Status +- Integrationsstatus +- Benachrichtigungen + +## Sicherheitsprinzip + +Logs dürfen nicht manipulierbar sein und müssen nachvollziehbar, filterbar und geschützt gespeichert werden. diff --git a/architecture/module-structure-v0.2.md b/architecture/module-structure-v0.2.md new file mode 100644 index 0000000..7afead3 --- /dev/null +++ b/architecture/module-structure-v0.2.md @@ -0,0 +1,65 @@ +# Module Structure v0.2 + +## Zweck +Dieses Dokument ersetzt die Modulstruktur v0.1 als verbindliche Modulübersicht. + +## Core +- Identity +- Authentication +- Tenancy +- RBAC +- Audit Base +- Module Registry +- Settings Base +- Event Routing +- API Base + +## Service-Module + +### Customers +Kunden, Parteien, Adressen, Kontakte. + +### Contracts +Verträge, Laufzeiten, Vertragspositionen. + +### Products +Produkte, Leistungen, Preise, Steuer-Metadaten. + +### Domains +Domains, TLD, Status, Registrar-Zuordnung. + +### Hosting +Hostingpakete, Server, Zuordnungen. + +### Billing +Rechnungsreferenzen, Zahlungsreferenzen, externe Billing-Konten. + +### Tickets +Tickets, Antworten, interne Notizen, Status. + +### Documents +PDFs, Anhänge, Hashes, Dokumentenverknüpfungen. + +### Notifications +Benachrichtigungsrouting und spätere Kanäle. + +## Integrationsmodule + +### KeyHelp Adapter +Verbindung zu KeyHelp. + +### 1blu Adapter +Import und spätere Synchronisation. + +### Lexware Adapter +Billing-Referenzen und spätere Synchronisation. + +### Invoice Ninja Adapter +Alternative Billing-Anbindung. + +## Nicht V1 +- AI Assistant +- WordPress Plugin +- Customer Portal +- Plesk/cPanel +- Cloud Provisioning diff --git a/architecture/multi-tenancy-strategy-v0.1.md b/architecture/multi-tenancy-strategy-v0.1.md new file mode 100644 index 0000000..3b1eb5c --- /dev/null +++ b/architecture/multi-tenancy-strategy-v0.1.md @@ -0,0 +1,30 @@ +# Multi-Tenancy Strategy v0.1 + +## Grundprinzip + +Mandantenfähigkeit wird von Anfang an architektonisch vorbereitet. + +V1 bleibt zunächst einfach nutzbar, spätere Multi-Tenant- und Resellerstrukturen sollen jedoch möglich bleiben. + +## Ziele + +Das System soll später ermöglichen: +- mehrere Organisationen +- Reseller +- getrennte Kundenbereiche +- Datenisolation +- Rechteisolation + +## Architekturprinzip + +Alle zentralen Objekte sollen vorbereitet sein für: +- organisation_id +- tenant_id + +## V1 + +V1 arbeitet zunächst primär als Single-Tenant-System. Die Datenstruktur bleibt vorbereitet. + +## Sicherheitsprinzip + +Mandanten dürfen niemals auf fremde Daten zugreifen können. diff --git a/architecture/notification-strategy-v0.1.md b/architecture/notification-strategy-v0.1.md new file mode 100644 index 0000000..09c5439 --- /dev/null +++ b/architecture/notification-strategy-v0.1.md @@ -0,0 +1,29 @@ +# Notification Strategy v0.1 + +## Grundprinzip + +Benachrichtigungen sollen Kunden und Administratoren über relevante Ereignisse informieren. + +## V1-Benachrichtigungen + +- Ticket erstellt +- Ticket beantwortet +- Rechnungsstatus geändert +- Domainlaufzeit-Hinweis später +- Import abgeschlossen +- kritische Systemereignisse + +## Kanäle + +V1: +- E-Mail +- interne Systemmeldungen + +Später: +- Webhooks +- Kundenportal-Benachrichtigungen +- optionale Messenger-/Push-Systeme + +## Architektur + +Benachrichtigungen sollen über ein zentrales Notification-System laufen, nicht direkt aus einzelnen Modulen heraus hart verdrahtet werden. diff --git a/architecture/payment-policy-v0.1.md b/architecture/payment-policy-v0.1.md new file mode 100644 index 0000000..1b475e5 --- /dev/null +++ b/architecture/payment-policy-v0.1.md @@ -0,0 +1,28 @@ +# Payment Policy v0.1 + +## Grundprinzip + +Hosting-Backoffice ist kein Payment-Service-Provider und kein Banking-System. + +Das System verwaltet Zahlungsarten, Status, Hinweise und externe Referenzen. + +## Zahlungsarten V1 + +- Rechnung +- Überweisung +- Lastschrift +- PayPal +- Wero + +## Gebührenregeln + +Später sollen Zahlungsarten mit Regeln versehen werden können: +- bevorzugte Zahlungsart +- Hinweistext +- mögliche Zusatzgebühr +- rechtlicher Hinweis +- Aktivierung je Kunde oder Produkt + +## Rechtlicher Hinweis + +Gebühren für Zahlungsarten müssen rechtlich geprüft werden. Die Software soll Konfiguration ermöglichen, aber keine pauschalen rechtlichen Annahmen hart einbauen. diff --git a/architecture/security-and-rights-v0.1.md b/architecture/security-and-rights-v0.1.md new file mode 100644 index 0000000..c4d236b --- /dev/null +++ b/architecture/security-and-rights-v0.1.md @@ -0,0 +1,49 @@ +# Security & Rights Model v0.1 + +## Grundprinzip + +Hosting-Backoffice ist ein kundenzentriertes System mit sensiblen Daten. + +Sicherheit, Nachvollziehbarkeit und Rechtekontrolle haben hohe Priorität. + +## Benutzerrollen V1 + +### Superadmin +Vollzugriff auf Systemeinstellungen, Module, Benutzer, Server, Integrationen und Auditdaten. + +### Administrator +Zugriff auf Kunden, Verträge, Domains, Tickets, Rechnungsreferenzen und Hostingpakete. + +### Support-Mitarbeiter +Zugriff auf Tickets, Kundeninformationen und Hostingstatus. Kein Zugriff auf kritische Einstellungen. + +### Kunde +Zugriff ausschließlich auf eigene Verträge, Domains, Rechnungen, Tickets und Dokumente. + +## API-Sicherheit + +- Authentifizierung +- Rechteprüfung +- Auditierung +- Tokenbasierte API +- später OAuth/Sanctum möglich + +## Audit-Logs + +Alle kritischen Aktionen sollen protokolliert werden. + +Beispiele: +- Loginversuche +- Änderungen +- Löschungen +- Ticketaktionen +- Domainänderungen +- Benutzerrechte +- Importvorgänge + +## Mandantenfähigkeit + +- tenant_id / organisation_id +- Datenisolation +- Rechteisolation +- spätere Resellerfähigkeit diff --git a/architecture/security-and-rights-v0.2.md b/architecture/security-and-rights-v0.2.md new file mode 100644 index 0000000..d50044d --- /dev/null +++ b/architecture/security-and-rights-v0.2.md @@ -0,0 +1,47 @@ +# Security & Rights Model v0.2 + +## Zweck +Dieses Dokument ergänzt das Sicherheitsmodell um konkrete Entscheidungen aus den ADRs. + +## Zentrale Sicherheitsentscheidungen + +- tenant_id als Mandantenkontext +- PostgreSQL als Datenbank +- Laravel Sanctum als Auth-Basis +- Secrets nicht in Fachtabellen speichern +- Audit-Logs append-only +- API-Zugriffe auditierbar +- Plugin-Scopes später minimal halten + +## Rollen V1 + +### Superadmin +Systemweiter Zugriff, aber alle mandantenübergreifenden Aktionen werden auditierbar. + +### Tenant Admin +Verwaltet den eigenen Mandanten. + +### Staff / Support +Bearbeitet Kunden, Tickets und operative Daten innerhalb eines Mandanten. + +### Kunde +Nicht V1, erst Customer Portal V2. + +## Tenant-Isolation +Alle mandantenbezogenen Daten benötigen: + +- tenant_id +- Policy-Prüfung +- Query-Scope +- Tests gegen Tenant-Leaks + +## Secrets +Secrets werden nur über einen Secret-Service gelesen/geschrieben. + +## Audit +Kritische Aktionen werden in Audit-Logs erfasst. + +## Offene Punkte +- genaue MFA-Pflicht +- Impersonation-Regeln +- RLS-Umsetzung im Detail diff --git a/decisions/0001-standalone-core.md b/decisions/0001-standalone-core.md new file mode 100644 index 0000000..9ec0bb6 --- /dev/null +++ b/decisions/0001-standalone-core.md @@ -0,0 +1,24 @@ +# Entscheidung 0001: Standalone-Core statt WordPress-Core + +## Entscheidung + +Das Hosting-Backoffice wird als eigenständiges Laravel-System entwickelt. + +WordPress wird nicht als Kernsystem verwendet, sondern später optional über ein Plugin angebunden. + +## Begründung + +- höhere Sicherheit +- bessere Kontrolle über Rechte, Daten und APIs +- weniger Abhängigkeit von Fremdplugins +- bessere Skalierbarkeit +- sauberere Modularchitektur +- bessere Trennung zwischen Backoffice und Frontend + +## Zielarchitektur + +Standalone-Core + REST API + optionale Integrationen + optionales WordPress-Plugin. + +## Status + +Akzeptiert. diff --git a/decisions/0002-customer-centric-platform.md b/decisions/0002-customer-centric-platform.md new file mode 100644 index 0000000..566de7a --- /dev/null +++ b/decisions/0002-customer-centric-platform.md @@ -0,0 +1,28 @@ +# Entscheidung 0002: Kundenzentriertes Hosting-Backoffice + +## Entscheidung + +Das System wird kundenzentriert aufgebaut. + +Nicht Server, Domains oder Rechnungen stehen im Zentrum, sondern der Kunde mit allen zugehörigen Objekten. + +## Zentrale Sicht + +Kunde: +- Verträge +- Domains +- Hostingpakete +- Serverbezug +- Rechnungen +- Zahlungen +- Tickets +- Dokumente +- Historie + +## Begründung + +Ein kleines Hostinggeschäft benötigt vor allem Übersicht und Beziehungskontext. Support, Abrechnung und technische Informationen müssen aus einer Kundenakte heraus verständlich sein. + +## Status + +Akzeptiert. diff --git a/decisions/0003-no-own-payment-system.md b/decisions/0003-no-own-payment-system.md new file mode 100644 index 0000000..efeb199 --- /dev/null +++ b/decisions/0003-no-own-payment-system.md @@ -0,0 +1,27 @@ +# Entscheidung 0003: Kein eigenes Payment-/Banking-System + +## Entscheidung + +Hosting-Backoffice wird keine eigene Zahlungs- oder Banking-Plattform. + +Das System verwaltet Zahlungsarten, Zahlungsstatus, Hinweise, externe Referenzen und spätere Gebührenregeln. Die eigentliche Zahlungsabwicklung erfolgt über externe Anbieter oder Rechnungssysteme. + +## Begründung + +- weniger rechtliche Risiken +- weniger Sicherheitsrisiken +- weniger Compliance-Aufwand +- keine unnötige PCI-/Banking-Komplexität +- bessere Austauschbarkeit externer Anbieter + +## Beispiele + +- Lexware Office +- Invoice Ninja CE +- PayPal +- Wero +- SEPA-/Bankprozesse außerhalb des Cores + +## Status + +Akzeptiert. diff --git a/decisions/0004-tenancy-model.md b/decisions/0004-tenancy-model.md new file mode 100644 index 0000000..6d372f2 --- /dev/null +++ b/decisions/0004-tenancy-model.md @@ -0,0 +1,162 @@ +# ADR 0004 — Tenancy-Modell + +## Status +Accepted + +## Kurz erklärt +Tenancy bedeutet Mandantenfähigkeit. + +Ein Mandant ist z. B. ein Anbieter, eine Agentur oder später ein Reseller, der seine eigenen Kunden, Verträge, Domains und Rechnungen verwaltet. + +Das Tenancy-Modell legt fest, wie Daten verschiedener Mandanten technisch voneinander getrennt werden. + +## Kontext +Hosting-Backoffice soll zunächst einfach nutzbar sein, später aber mandantenfähig und ggf. resellerfähig erweitert werden können. + +Die bisherige Planung enthielt die Begriffe `tenant_id` und `organisation_id`, ohne deren Verhältnis eindeutig zu definieren. + +Das wurde im Architekturreview als kritisches Risiko bewertet, da eine nachträgliche Mandantenfähigkeit sehr teuer und fehleranfällig wäre. + +## Entscheidung +Hosting-Backoffice verwendet von Beginn an ein mandantenfähiges Datenmodell mit: + +- `tenant_id` als zentrale Mandantenreferenz +- Shared Database Modell +- PostgreSQL als bevorzugte Datenbank +- Tenant Scope auf Anwendungsebene +- Row Level Security als spätere zusätzliche Sicherheitsschicht + +`organisation_id` wird vorerst nicht als separates Standardfeld verwendet. + +Falls später eine Organisationshierarchie benötigt wird, wird diese über das Tenant-Modell abgebildet. + +## Gewähltes Modell + +```text +Platform +└── Tenant + └── Kunde + └── Verträge + └── Domains + └── Hostingpakete + └── Tickets + └── Dokumente +``` + +Später möglich: + +```text +Platform +└── Tenant + └── Reseller-Tenant + └── Kunden +``` + +Dafür kann später ein Feld wie `parent_tenant_id` in der Tenant-Struktur ergänzt oder vorbereitet werden. + +## Begründung +Ein Shared-Database-Modell mit `tenant_id` ist für den Start sinnvoll, weil: + +- V1 klein bleiben soll +- alle Daten zentral verwaltbar bleiben +- Migrationen einfacher sind +- Betrieb und Backups weniger komplex sind +- spätere Mandantenfähigkeit vorbereitet wird +- Resellerstrukturen später möglich bleiben + +PostgreSQL wird bevorzugt, weil es Row Level Security unterstützt. + +Row Level Security bedeutet: + +```text +Die Datenbank selbst kann verhindern, +dass Mandant A Datensätze von Mandant B sieht. +``` + +Das ist eine zusätzliche Sicherheitsschicht neben der Anwendung. + +## Konsequenzen + +### Positiv +- Mandantenfähigkeit wird nicht später „angeklebt“ +- bessere Grundlage für spätere SaaS-/Resellerfähigkeit +- klare Datenisolation +- bessere Sicherheitsarchitektur +- weniger Refactoring-Risiko + +### Negativ +- jede mandantenbezogene Tabelle braucht `tenant_id` +- alle Abfragen müssen tenant-aware sein +- Entwickler müssen von Anfang an sauber mit Tenant-Kontext arbeiten +- Tests müssen Mandantenisolation prüfen + +## Technische Leitlinien +Alle mandantenbezogenen Tabellen erhalten: + +```text +tenant_id +``` + +Beispiele: + +```text +customers.tenant_id +contracts.tenant_id +domains.tenant_id +hosting_packages.tenant_id +tickets.tenant_id +documents.tenant_id +``` + +Nicht mandantenbezogene Tabellen können global sein, z. B.: + +```text +system_settings +module_registry +global_permissions +``` + +## Anwendungsebene +Laravel soll sicherstellen, dass mandantenbezogene Daten nur im aktuellen Tenant-Kontext geladen werden. + +Dafür vorgesehen: + +- Tenant Context +- Eloquent Global Scopes +- Policies +- Tests gegen Tenant-Leaks + +Tenant-Leak bedeutet: + +```text +Ein Benutzer oder Prozess sieht versehentlich Daten eines anderen Mandanten. +``` + +## Datenbankebene +PostgreSQL Row Level Security soll als spätere zweite Schutzschicht vorbereitet werden. + +V1 kann zunächst mit sauberem Tenant Scope in Laravel starten. + +RLS sollte jedoch nicht durch Datenmodellentscheidungen blockiert werden. + +## Offene Punkte +Noch zu klären: + +- genaue Tenant-Tabelle +- ob `parent_tenant_id` sofort angelegt wird +- ob V1 technisch bereits echtes Multi-Tenant-Login erlaubt +- wie Plattform-Admins mandantenübergreifend arbeiten dürfen +- wie Tenant-Offboarding später funktioniert + +## Nicht entschieden +Diese ADR entscheidet noch nicht: + +- ob Hosting-Backoffice später SaaS oder nur self-hosted wird +- ob einzelne Mandanten später eigene Datenbanken erhalten können +- ob Resellerstrukturen bereits in V1 aktiv sichtbar sind + +## Verwandte ADRs +- ADR 0005 — Datenbankwahl +- ADR 0006 — Auth-Strategie +- ADR 0009 — Core-Grenzen +- ADR 0011 — GoBD-Verantwortlichkeit diff --git a/decisions/0005-database-choice.md b/decisions/0005-database-choice.md new file mode 100644 index 0000000..f8b6e0d --- /dev/null +++ b/decisions/0005-database-choice.md @@ -0,0 +1,80 @@ +# ADR 0005 — Datenbankwahl + +## Status +Accepted + +## Kurz erklärt +Die Datenbank ist der zentrale Speicher für Kunden, Verträge, Domains, Tickets, Dokumente und technische Referenzen. + +Die Wahl der Datenbank beeinflusst später besonders: + +- Mandantenfähigkeit +- Sicherheit +- Performance +- Auditierbarkeit +- Skalierbarkeit +- Entwicklungsaufwand + +## Kontext +In der ersten Planung waren MariaDB und PostgreSQL offen. + +Das Architekturreview hat kritisiert, dass eine offene Datenbankwahl bei Multi-Tenancy und API-first zu einem kleinsten gemeinsamen Nenner führen würde. + +## Entscheidung +Hosting-Backoffice verwendet PostgreSQL als primäre Datenbank. + +## Begründung +PostgreSQL bietet wichtige Funktionen für das Zielbild: + +- Row Level Security +- starke Datenintegrität +- JSONB-Unterstützung +- gute Indexierungsoptionen +- transaktionale Migrationen +- gute Grundlage für Mandantenfähigkeit +- gute Grundlage für spätere SaaS-/Reseller-Strukturen + +## Row Level Security +Row Level Security bedeutet: + +```text +Die Datenbank kann Regeln erzwingen, +welche Datensätze ein Benutzer oder Prozess sehen darf. +``` + +Das ist besonders relevant, wenn mehrere Mandanten in einer gemeinsamen Datenbank verwaltet werden. + +## Nicht gewählt + +### MariaDB / MySQL +Vorteile: + +- sehr weit verbreitet +- vielen Hostern bekannt +- einfacher Einstieg + +Nachteile: + +- schwächer für Row-Level-Isolation +- schwächer als Sicherheitsbasis für Mandantenfähigkeit +- langfristig weniger geeignet für das geplante SaaS-/Reseller-Modell + +## Konsequenzen + +### Positiv +- bessere Sicherheitsarchitektur +- bessere Grundlage für Multi-Tenancy +- bessere technische Zukunftsfähigkeit + +### Negativ +- etwas höhere Einstiegshürde +- nicht jeder kleine Shared-Hosting-Anbieter bietet PostgreSQL gleichwertig an +- Self-hosted-Installationen benötigen klare Systemvoraussetzungen + +## Leitlinie +Hosting-Backoffice wird nicht primär für beliebiges Billig-Shared-Hosting optimiert, sondern für eine seriöse, betreibbare Hosting-/Backoffice-Umgebung. + +## Verwandte ADRs +- ADR 0004 — Tenancy-Modell +- ADR 0010 — Secrets-Management +- ADR 0014 — Audit-Log-Strategie diff --git a/decisions/0006-auth-strategy.md b/decisions/0006-auth-strategy.md new file mode 100644 index 0000000..34c9084 --- /dev/null +++ b/decisions/0006-auth-strategy.md @@ -0,0 +1,96 @@ +# ADR 0006 — Auth-Strategie + +## Status +Accepted + +## Kurz erklärt +Auth bedeutet Authentifizierung und Autorisierung. + +Authentifizierung beantwortet: + +```text +Wer bist du? +``` + +Autorisierung beantwortet: + +```text +Was darfst du? +``` + +## Kontext +Das System benötigt mehrere Zugriffstypen: + +- Admin-Login +- Mitarbeiter-Login +- Kundenlogin später +- API-Zugriffe +- Integrationen +- später WordPress-Plugin + +Das Architekturreview hat kritisiert, dass „Tokenbasiert, später OAuth/Sanctum“ zu unscharf ist. + +## Entscheidung +V1 verwendet Laravel Sanctum als Auth-Basis. + +Sanctum wird genutzt für: + +- Admin-/Backoffice-Login +- interne API +- Personal Access Tokens für technische Clients +- spätere einfache API-Zugriffe + +OAuth2/Passport wird nicht in V1 eingeführt. + +## Warum Sanctum? +Sanctum ist für V1 passend, weil: + +- es Laravel-nah ist +- wenig Overhead erzeugt +- API-Tokens unterstützt +- SPA-/Frontend-Sessions unterstützt +- für ein kleines V1-Team einfacher beherrschbar ist + +## OAuth2 später +OAuth2 kann später relevant werden für: + +- Drittanbieter-Apps +- öffentliches Plugin-Ökosystem +- externe Entwickler +- komplexere WordPress-Plugin-Szenarien + +## Rechteprüfung +Auth allein reicht nicht. + +Jeder Zugriff benötigt zusätzlich: + +- Tenant-Kontext +- Rollenprüfung +- Policy-Prüfung +- Auditierbarkeit bei kritischen Aktionen + +## MFA +MFA bedeutet Multi-Faktor-Authentifizierung. + +Für V1 gilt: + +- MFA für Superadmins empfohlen +- MFA für normale Kunden optional später +- WebAuthn kann später geprüft werden + +## Konsequenzen + +### Positiv +- einfacher Einstieg +- Laravel-nah +- gut für V1 +- weniger Komplexität + +### Negativ +- für öffentliche Drittanbieter-Ökosysteme später eventuell nicht ausreichend +- OAuth2 muss ggf. später zusätzlich eingeführt werden + +## Verwandte ADRs +- ADR 0004 — Tenancy-Modell +- ADR 0012 — Frontend-Strategie +- ADR 0018 — WordPress-Plugin-Security diff --git a/decisions/0007-module-system.md b/decisions/0007-module-system.md new file mode 100644 index 0000000..f7bc860 --- /dev/null +++ b/decisions/0007-module-system.md @@ -0,0 +1,102 @@ +# ADR 0007 — Modul-System + +## Status +Accepted + +## Kurz erklärt +Das Modul-System legt fest, wie Funktionen voneinander getrennt werden. + +Ziel ist: + +```text +modular denken, +aber V1 nicht technisch überkomplizieren. +``` + +## Kontext +Das Projekt soll kein klassischer Monolith werden. + +Gleichzeitig wäre ein echtes Microservice-System für V1 zu komplex. + +## Entscheidung +V1 verwendet ein modulares In-App-Modell innerhalb einer Laravel-Anwendung. + +Module sind logisch getrennt, laufen aber im selben Deployment. + +## Warum kein Microservice-System? +Microservices bedeuten: + +- mehrere Deployments +- mehrere Services +- Service-Kommunikation +- verteiltes Logging +- verteilte Fehlerbilder +- mehr DevOps-Aufwand + +Für V1 wäre das zu schwer. + +## Modularten + +### Core +Minimaler Plattformkern. + +### Service-Module +Fachliche Module wie: + +- Kunden +- Verträge +- Domains +- Hosting +- Tickets +- Dokumente +- Billing + +### Integrationsmodule +Adapter zu externen Systemen wie: + +- KeyHelp +- 1blu +- Lexware +- Invoice Ninja + +## Technische Leitlinien +Module kommunizieren über: + +- Service-Contracts +- Events +- definierte Interfaces + +Nicht erlaubt: + +```text +Modul A verändert ungeprüft interne Tabellen von Modul B. +``` + +## Modul-Lifecycle +Module sollen später Zustände haben: + +- installiert +- aktiviert +- deaktiviert +- aktualisiert +- archiviert + +Deinstallation mit Datenlöschung ist nicht Standard. + +## Konsequenzen + +### Positiv +- V1 bleibt betreibbar +- Architektur bleibt modular +- keine Microservice-Komplexität +- spätere Auslagerung einzelner Module bleibt möglich + +### Negativ +- strikte Disziplin nötig +- Modulgrenzen müssen geprüft werden +- ohne klare Contracts droht trotzdem ein Monolith + +## Verwandte ADRs +- ADR 0009 — Core-Grenzen +- ADR 0008 — External-Reference-Pattern +- ADR 0016 — Modul-Lifecycle diff --git a/decisions/0008-external-reference-pattern.md b/decisions/0008-external-reference-pattern.md new file mode 100644 index 0000000..6f9ead9 --- /dev/null +++ b/decisions/0008-external-reference-pattern.md @@ -0,0 +1,97 @@ +# ADR 0008 — External-Reference-Pattern + +## Status +Accepted + +## Kurz erklärt +External Reference bedeutet: + +```text +Ein internes Objekt merkt sich, +wie es in einem externen System heißt. +``` + +Beispiel: + +- Kunde im Backoffice +- derselbe Kunde in Lexware +- dieselbe Domain bei 1blu +- derselbe Hostingaccount in KeyHelp + +## Kontext +Das Architekturreview hat kritisiert, dass konkrete Anbieterfelder wie `keyhelp_id` oder `lexware_id` im Core das Adapter-Pattern zerstören würden. + +## Entscheidung +Hosting-Backoffice verwendet ein generisches External-Reference-Pattern. + +Der Core erhält keine Anbieterfelder wie: + +```text +keyhelp_id +lexware_id +oneblu_id +``` + +Stattdessen gibt es eine generische Referenzstruktur. + +## Beispielstruktur + +```text +external_references +- id +- tenant_id +- owner_type +- owner_id +- provider +- provider_account_id +- external_id +- external_type +- metadata +- last_synced_at +- created_at +- updated_at +``` + +## Beispiel + +```text +owner_type: Domain +owner_id: 123 +provider: 1blu +external_id: ABC-987 +``` + +Oder: + +```text +owner_type: Server +owner_id: 55 +provider: KeyHelp +external_id: server-user-4711 +``` + +## Begründung +Dieses Pattern sorgt für: + +- Providerneutralität +- weniger Core-Abhängigkeiten +- einfachere neue Integrationen +- saubere Migrationen +- bessere Austauschbarkeit von Modulen + +## Konsequenzen + +### Positiv +- keine harte Anbieterlogik im Core +- bessere Erweiterbarkeit +- sauberer Wechsel von Anbietern möglich + +### Negativ +- etwas komplexeres Datenmodell +- Entwickler müssen über Adapter denken +- direkte Fremdschlüssel zu externen Systemen sind nicht erlaubt + +## Verwandte ADRs +- ADR 0007 — Modul-System +- ADR 0009 — Core-Grenzen +- ADR 0017 — Adapter-Fehlerresilienz diff --git a/decisions/0009-core-boundaries.md b/decisions/0009-core-boundaries.md new file mode 100644 index 0000000..d6f07df --- /dev/null +++ b/decisions/0009-core-boundaries.md @@ -0,0 +1,106 @@ +# ADR 0009 — Core-Grenzen + +## Status +Accepted + +## Kurz erklärt +Core-Grenzen legen fest, was wirklich in den Plattformkern gehört. + +Je größer der Core wird, desto höher ist das Risiko, dass das System trotz Modulidee zu einem Monolithen wird. + +## Kontext +Das Architekturreview hat kritisiert, dass der bisherige Core zu groß definiert war. + +Bisher waren u. a. Kunden, Domains, Server, Produkte, Dokumente und Benachrichtigungen im Core vorgesehen. + +Das widerspricht dem Ziel eines modularen Systems. + +## Entscheidung +Der Core wird bewusst klein gehalten. + +Der Core enthält nur technische und organisatorische Plattformfunktionen, die alle Module benötigen. + +## Core enthält + +- Identity +- Authentication +- Tenant Context +- RBAC / Policies +- Audit-Grundstruktur +- Module Registry +- Settings-Grundstruktur +- Event Routing +- API-Basis +- System Health + +## Core enthält NICHT + +- Kundenfachlogik +- Domainfachlogik +- Billingfachlogik +- Hostingfachlogik +- Ticketsystemfachlogik +- Dokumentenarchivfachlogik +- Anbieterlogik + +Diese Bereiche werden als Service-Module oder Integrationsmodule behandelt. + +## Neue Struktur + +```text +Core +├── Identity +├── Tenancy +├── RBAC +├── Audit Base +├── Module Registry +├── Settings Base +├── Event Routing +└── API Base + +Service Modules +├── Customers +├── Contracts +├── Products +├── Domains +├── Hosting +├── Billing +├── Tickets +├── Documents +└── Notifications + +Integration Modules +├── KeyHelp +├── 1blu +├── Lexware +└── Invoice Ninja +``` + +## Begründung +Ein kleiner Core reduziert: + +- Kopplung +- Refactoring-Risiken +- Monolith-Gefahr +- Abhängigkeiten zwischen Fachbereichen + +## Konsequenzen + +### Positiv +- sauberere Modulgrenzen +- leichter testbar +- langfristig besser erweiterbar +- neue Integrationen einfacher möglich + +### Negativ +- mehr Architekturdisziplin nötig +- Module brauchen definierte Contracts +- anfänglich mehr Planungsaufwand + +## Regel +Wenn ein Bereich fachliche Geschäftslogik enthält, gehört er nicht in den Core. + +## Verwandte ADRs +- ADR 0007 — Modul-System +- ADR 0008 — External-Reference-Pattern +- ADR 0016 — Modul-Lifecycle diff --git a/decisions/0010-secrets-management.md b/decisions/0010-secrets-management.md new file mode 100644 index 0000000..62a7454 --- /dev/null +++ b/decisions/0010-secrets-management.md @@ -0,0 +1,99 @@ +# ADR 0010 — Secrets-Management + +## Status +Accepted + +## Kurz erklärt +Secrets sind geheime technische Zugangsdaten, z. B.: + +- API-Keys +- Registrar-Zugänge +- Tokens +- Passwörter +- Webhook-Secrets + +Secrets dürfen nicht wie normale Stammdaten gespeichert werden. + +## Kontext +Hosting-Backoffice wird später Zugangsdaten zu externen Systemen verwalten: + +- KeyHelp +- 1blu +- Lexware +- Invoice Ninja +- SMTP +- Zahlungsanbieter + +Das Architekturreview hat fehlendes Secrets-Management als kritisches Risiko bewertet. + +## Entscheidung +Das Datenmodell speichert keine Secrets direkt in fachlichen Tabellen. + +Fachliche Tabellen speichern nur Referenzen auf Secrets. + +## V1-Strategie +Für V1 wird mindestens verwendet: + +- verschlüsselte Speicherung mit Laravel Encryption +- getrennte Secret-Tabelle +- Zugriff nur über Secret-Service +- keine Ausgabe von Secrets im UI +- Audit-Log bei Secret-Erstellung/Änderung +- Rotation vorbereiten + +## Spätere Strategie +Für SaaS- oder größere Multi-Tenant-Nutzung wird ein externer Vault vorbereitet, z. B.: + +- HashiCorp Vault +- Bitwarden Secrets Manager +- Cloud KMS / Secrets Manager + +## Beispiel + +Nicht erlaubt: + +```text +registrar_accounts.api_password +``` + +Erlaubt: + +```text +registrar_accounts.secret_reference_id +``` + +## Begründung +Bei einem Einbruch darf nicht sofort der direkte Zugriff auf alle externen Systeme möglich sein. + +Secrets brauchen: + +- Verschlüsselung +- Zugriffskontrolle +- Rotation +- Auditierung +- Mandantenisolation + +## Konsequenzen + +### Positiv +- höheres Sicherheitsniveau +- bessere Mandantenisolation +- spätere Vault-Anbindung möglich + +### Negativ +- mehr technische Komplexität +- Secret-Service muss früh gebaut werden +- Backups müssen besonders betrachtet werden + +## Mindestregeln + +- Secrets nie im Klartext loggen +- Secrets nie im UI vollständig anzeigen +- Secrets nie in normalen Exporten ausgeben +- Secret-Zugriff auditieren +- API-Keys rotierbar halten + +## Verwandte ADRs +- ADR 0004 — Tenancy-Modell +- ADR 0006 — Auth-Strategie +- ADR 0017 — Adapter-Fehlerresilienz diff --git a/decisions/0011-gobd-responsibility.md b/decisions/0011-gobd-responsibility.md new file mode 100644 index 0000000..5338978 --- /dev/null +++ b/decisions/0011-gobd-responsibility.md @@ -0,0 +1,76 @@ +# ADR 0011 — GoBD-Verantwortlichkeit + +## Status +Accepted + +## Kurz erklärt +GoBD beschreibt Anforderungen an ordnungsgemäße Buchführung und Aufbewahrung steuerlich relevanter Daten in Deutschland. + +Wichtige Frage: + +```text +Ist Hosting-Backoffice das führende Rechnungssystem +oder nur ein Verwaltungs-/Spiegelsystem? +``` + +## Kontext +Das System soll Rechnungen anzeigen, archivieren und mit Kunden/Verträgen verknüpfen. + +Gleichzeitig soll die eigentliche Rechnungsstellung über externe Systeme wie Lexware oder Invoice Ninja erfolgen. + +Das Architekturreview hat zurecht bemängelt, dass die GoBD-Rolle nicht eindeutig war. + +## Entscheidung +Hosting-Backoffice ist in V1 nicht das führende GoBD-Rechnungssystem. + +Das führende Rechnungssystem ist: + +- Lexware Office +- oder Invoice Ninja CE, sofern der Betreiber dies bewusst so nutzt + +Hosting-Backoffice ist in V1: + +- Referenzsystem +- Spiegel +- Dokumentenablage +- Prozess- und Audit-System + +## Konsequenz +Hosting-Backoffice erzeugt in V1 keine steuerlich führenden Originalrechnungen. + +Es speichert: + +- Rechnungsreferenzen +- PDF-Kopien +- Hashes +- Zahlungsstatus-Referenzen +- Audit-Ereignisse + +## Begründung +Damit werden reduziert: + +- Buchhaltungsrisiken +- GoBD-Komplexität +- Haftungsfragen +- technische Anforderungen an unveränderbare Originalbelege + +## Archivierung +PDF-Kopien können gespeichert werden, aber die Originalverantwortung liegt beim externen Billing-System. + +## Später möglich +Ein späteres eigenes GoBD-fähiges Billing-Modul wäre möglich, aber nicht Teil von V1. + +Dafür wären nötig: + +- lückenlose Nummernkreise +- Beleg-Festschreibung +- unveränderbare Speicherung +- Exportfunktionen +- Verfahrensdokumentation +- Steuerlogik +- Retention-Strategie + +## Verwandte ADRs +- ADR 0014 — Audit-Log-Strategie +- ADR 0015 — Tax- und VAT-Strategie +- ADR 0021 — DSGVO-Löschung und Retention diff --git a/decisions/0012-frontend-strategy.md b/decisions/0012-frontend-strategy.md new file mode 100644 index 0000000..0c14a8a --- /dev/null +++ b/decisions/0012-frontend-strategy.md @@ -0,0 +1,69 @@ +# ADR 0012 — Frontend-Strategie + +## Status +Accepted + +## Kurz erklärt +Die Frontend-Strategie legt fest, wie Benutzer die Anwendung bedienen. + +Wichtig ist die Frage: + +```text +Klassische Laravel-Seiten +oder modernes API-basiertes Frontend? +``` + +## Kontext +Das Architekturreview hat kritisiert, dass „Blade oder später Vue/Nuxt“ eine offene Grundsatzentscheidung ist. + +Für API-first darf das Frontend nicht direkt an Datenbanklogik hängen. + +## Entscheidung +V1 verwendet ein Laravel-basiertes Admin-Frontend, aber strikt über interne Service-/API-Schichten. + +Es wird kein vollständig getrenntes Nuxt/Vue-SPA in V1 gebaut. + +Das Frontend darf nicht direkt fachliche Datenbanklogik umgehen. + +## Warum? +Ein vollständiges SPA erhöht V1-Komplexität: + +- separater Build-Prozess +- separate Auth-Flows +- mehr Frontend-Architektur +- mehr Testing-Aufwand + +Für V1 ist ein Laravel-nahes Frontend effizienter. + +## API-first bleibt bestehen +API-first bedeutet hier: + +- Geschäftslogik liegt in Services/Contracts +- REST API wird parallel sauber definiert +- spätere externe Clients bleiben möglich +- WordPress-Plugin nutzt später ausschließlich API + +## Später möglich +In V2/V3 kann ein SPA-Frontend entstehen, wenn: + +- API stabil ist +- Auth-Scopes klar sind +- Kundenportal ausgebaut wird +- Plugin-/App-Ökosystem entsteht + +## Konsequenzen + +### Positiv +- schnellerer V1-Start +- weniger Komplexität +- gute Laravel-Integration + +### Negativ +- API-first muss diszipliniert umgesetzt werden +- Gefahr eines klassischen Laravel-Monolithen bleibt +- klare Architekturregeln nötig + +## Verwandte ADRs +- ADR 0006 — Auth-Strategie +- ADR 0018 — WordPress-Plugin-Security +- ADR 0020 — Customer-Portal-Scope diff --git a/decisions/0013-customer-domain-model.md b/decisions/0013-customer-domain-model.md new file mode 100644 index 0000000..cfe775e --- /dev/null +++ b/decisions/0013-customer-domain-model.md @@ -0,0 +1,108 @@ +# ADR 0013 — Kunden-/Adress-/Kontaktmodell + +## Status +Accepted + +## Kurz erklärt +Ein Kunde ist nicht einfach nur ein Datensatz mit Name, Adresse und E-Mail. + +Es gibt: + +- Privatpersonen +- Firmen +- Ansprechpartner +- Rechnungsadressen +- technische Kontakte +- abweichende Postadressen + +## Kontext +Das Architekturreview hat kritisiert, dass das Objekt „Kunde“ zu monolithisch gedacht war. + +Ein zu einfaches Kundenmodell erschwert später: + +- DSGVO-Auskunft +- DSGVO-Löschung +- B2B/B2C-Unterscheidung +- mehrere Ansprechpartner +- getrennte Rechnungsadressen +- spätere Mandantenfähigkeit + +## Entscheidung +Das fachliche Kundenmodell wird aufgeteilt in: + +- Customer +- Party +- Address +- ContactPoint +- CustomerContact + +## Begriffe + +### Customer +Die Kundenbeziehung im System. + +### Party +Eine Person oder Organisation. + +### Address +Eine Adresse mit Verwendungszweck, z. B.: + +- Rechnungsadresse +- Postadresse +- Firmensitz + +### ContactPoint +Kontaktmöglichkeit, z. B.: + +- E-Mail +- Telefon +- Mobil +- Website + +### CustomerContact +Verknüpfung zwischen Kunde und Ansprechpartner. + +## Beispiel + +```text +Customer: Müller Webservice +Party: Müller Webservice GmbH +Address: Rechnungsadresse +ContactPoint: buchhaltung@... +ContactPoint: technik@... +CustomerContact: Max Müller als technischer Ansprechpartner +``` + +## B2B/B2C +Das Modell muss unterscheiden können: + +- B2B +- B2C +- öffentliche Einrichtung +- Verein/Organisation + +## Begründung +Das ist notwendig für: + +- korrekte Rechnungsdaten +- DSGVO +- Supportprozesse +- Vertragsverwaltung +- spätere Erweiterbarkeit + +## Konsequenzen + +### Positiv +- saubereres Datenmodell +- bessere DSGVO-Fähigkeit +- bessere B2B/B2C-Unterstützung +- bessere Kundenrealität + +### Negativ +- mehr Tabellen +- mehr UI-Komplexität +- Importlogik muss sauber mappen + +## Verwandte ADRs +- ADR 0021 — DSGVO-Löschung und Retention +- ADR 0015 — Tax- und VAT-Strategie diff --git a/decisions/0014-audit-log-strategy.md b/decisions/0014-audit-log-strategy.md new file mode 100644 index 0000000..3cdcf69 --- /dev/null +++ b/decisions/0014-audit-log-strategy.md @@ -0,0 +1,92 @@ +# ADR 0014 — Audit-Log-Strategie + +## Status +Accepted + +## Kurz erklärt +Audit-Logs dokumentieren wichtige Änderungen und Aktionen. + +Sie beantworten: + +```text +Wer hat wann was geändert? +``` + +## Kontext +Das Architekturreview hat bemängelt, dass „nicht manipulierbare Logs“ gefordert wurden, aber kein Mechanismus definiert war. + +## Entscheidung +V1 verwendet ein append-only Audit-Log. + +Append-only bedeutet: + +```text +Einträge werden nur hinzugefügt, +aber nicht geändert oder gelöscht. +``` + +## V1-Mindestmechanismus +Audit-Logs werden gespeichert mit: + +- tenant_id +- actor_id +- actor_type +- action +- object_type +- object_id +- old_values +- new_values +- created_at +- request_id +- ip_address +- user_agent + +## Integrität +V1 bereitet eine Hash-Chain vor. + +Hash-Chain bedeutet: + +```text +Jeder Logeintrag enthält einen Prüfwert +und verweist rechnerisch auf den vorherigen Eintrag. +``` + +Dadurch werden nachträgliche Manipulationen besser erkennbar. + +## Trennung +Es gibt unterschiedliche Logarten: + +- App-Logs +- Security-Logs +- Audit-Logs + +Audit-Logs sind keine normalen Debug-Logs. + +## Kritische Aktionen +Immer auditieren: + +- Login/Logout +- fehlgeschlagene Logins +- Rechteänderungen +- Kundendatenänderungen +- Vertragsänderungen +- Zahlungsstatusänderungen +- Importvorgänge +- Secret-Änderungen +- Modulaktivierungen +- API-Token-Erstellung + +## Nicht-Ziel +V1 garantiert noch keine vollständige externe WORM-Archivierung. + +## Später möglich +- Export in externes Audit-Sink +- WORM-Speicher +- signierte Logs +- tägliche Hash-Summen +- revisionssichere Langzeitablage + +## Verwandte ADRs +- ADR 0011 — GoBD-Verantwortlichkeit +- ADR 0010 — Secrets-Management +- ADR 0021 — DSGVO-Löschung und Retention diff --git a/decisions/0015-tax-and-vat-strategy.md b/decisions/0015-tax-and-vat-strategy.md new file mode 100644 index 0000000..932c215 --- /dev/null +++ b/decisions/0015-tax-and-vat-strategy.md @@ -0,0 +1,60 @@ +# ADR 0015 — Tax- und VAT-Strategie + +## Status +Accepted + +## Kurz erklärt +Tax/VAT bedeutet Steuer- und Mehrwertsteuerlogik. + +Auch wenn Hosting-Backoffice V1 keine eigene Buchhaltung sein soll, muss das System steuerlich relevante Informationen verstehen und sauber an externe Rechnungssysteme übergeben oder anzeigen können. + +## Kontext +Das Architekturreview hat bemängelt, dass MwSt, B2B/B2C, OSS und Reverse Charge nicht erwähnt wurden. + +Für V1 muss mindestens der deutsche Standardfall sauber abgebildet werden. + +## Entscheidung +V1 enthält ein minimales Steuer-Metadatenmodell, erzeugt aber keine führenden Steuerbelege. + +Führende Steuerberechnung bleibt in: + +- Lexware +- Invoice Ninja +- späterem externen Billing-System + +## V1-Mindestumfang + +- Kundentyp: B2B / B2C +- Land des Kunden +- USt-IdNr. optional +- Standard-Steuersatz je Produktreferenz +- Steuerhinweis je Vertrag/Rechnungsreferenz +- Brutto-/Netto-Anzeige nur als Referenz aus Billing-System + +## Nicht Teil von V1 + +- vollständige OSS-Automatisierung +- vollständige Reverse-Charge-Prüfung +- eigene Steuerberechnung als führendes System +- komplexe internationale Steuerlogik + +## Warum trotzdem Tax-Metadaten? +Weil das System sonst nicht zuverlässig erkennen kann: + +- welche Kunden B2B/B2C sind +- welche Rechnungslogik extern nötig ist +- welche Daten für Lexware/Invoice Ninja relevant sind +- welche Kunden steuerlich anders behandelt werden müssen + +## Später möglich + +- OSS-Unterstützung +- EU-B2B Reverse Charge +- Steuerprofile pro Mandant +- Steuerregeln pro Produkt +- Prüfung von USt-IdNr. +- tiefe Billing-Synchronisation + +## Verwandte ADRs +- ADR 0011 — GoBD-Verantwortlichkeit +- ADR 0013 — Kunden-/Adress-/Kontaktmodell diff --git a/decisions/0016-module-lifecycle.md b/decisions/0016-module-lifecycle.md new file mode 100644 index 0000000..2691845 --- /dev/null +++ b/decisions/0016-module-lifecycle.md @@ -0,0 +1,66 @@ +# ADR 0016 — Modul-Lifecycle + +## Status +Accepted + +## Kurz erklärt +Der Modul-Lifecycle beschreibt, was mit einem Modul passiert, wenn es installiert, aktiviert, deaktiviert oder entfernt wird. + +## Kontext +Das Architekturreview hat kritisiert, dass Module zwar aktivierbar/deaktivierbar sein sollen, aber nicht definiert war, was mit bestehenden Daten passiert. + +## Entscheidung +Module haben definierte Zustände: + +- available +- installed +- enabled +- disabled +- archived + +Deinstallation mit Datenlöschung ist kein Standardfall. + +## Zustände + +### available +Modul ist im System vorhanden, aber nicht installiert. + +### installed +Modul ist installiert, aber nicht aktiv. + +### enabled +Modul ist aktiv. + +### disabled +Modul ist deaktiviert, Daten bleiben erhalten. + +### archived +Modul wird nicht mehr genutzt, Daten bleiben aus Nachvollziehbarkeitsgründen erhalten. + +## Datenregel +Daten werden beim Deaktivieren nicht gelöscht. + +Grund: + +- Audit +- GoBD +- Nachvollziehbarkeit +- Referenzintegrität + +## Modul-Abhängigkeiten +Module müssen Abhängigkeiten deklarieren. + +Beispiel: + +```text +Invoice Ninja Adapter benötigt Billing-Modul. +``` + +## Migrationen +Jedes Modul verwaltet eigene Migrationen. + +Core-Migrationen dürfen keine Anbieterlogik enthalten. + +## Verwandte ADRs +- ADR 0007 — Modul-System +- ADR 0009 — Core-Grenzen diff --git a/decisions/0017-adapter-error-resilience.md b/decisions/0017-adapter-error-resilience.md new file mode 100644 index 0000000..3d32a75 --- /dev/null +++ b/decisions/0017-adapter-error-resilience.md @@ -0,0 +1,69 @@ +# ADR 0017 — Adapter-Fehlerresilienz + +## Status +Accepted + +## Kurz erklärt +Adapter verbinden Hosting-Backoffice mit externen Systemen. + +Fehlerresilienz bedeutet: + +```text +Das System darf nicht kaputt gehen, +nur weil ein externer Anbieter gerade nicht erreichbar ist. +``` + +## Kontext +Integrationen zu KeyHelp, 1blu, Lexware und Invoice Ninja sind geschäftskritisch. + +Das Architekturreview hat fehlende Retry-, Backoff- und Reconciliation-Strategien bemängelt. + +## Entscheidung +Alle Integrationsmodule müssen ein gemeinsames Fehlerverhalten unterstützen. + +## Pflichtmechanismen + +- Retry +- Backoff +- Dead Letter Queue +- Reconciliation +- sichtbarer Job-Status +- Audit-Log bei kritischen Fehlern + +## Begriffe + +### Retry +Ein fehlgeschlagener Vorgang wird erneut versucht. + +### Backoff +Wiederholungen erfolgen mit zunehmender Wartezeit. + +### Dead Letter Queue +Fehlgeschlagene Jobs werden gesammelt, damit ein Admin sie prüfen kann. + +### Reconciliation +Abgleich zwischen internem System und externem Anbieter, um Abweichungen zu erkennen. + +## Beispiel +Wenn Lexware nicht erreichbar ist: + +- Job schlägt nicht still fehl +- System versucht später erneut +- Admin sieht den Fehler +- Daten bleiben nachvollziehbar + +## Konsequenzen + +### Positiv +- stabilere Integrationen +- weniger stille Fehler +- bessere Admin-Kontrolle + +### Negativ +- mehr Implementierungsaufwand +- Job-System erforderlich +- Monitoring wird wichtiger + +## Verwandte ADRs +- ADR 0008 — External-Reference-Pattern +- ADR 0010 — Secrets-Management diff --git a/decisions/0018-wordpress-plugin-security.md b/decisions/0018-wordpress-plugin-security.md new file mode 100644 index 0000000..53df2f2 --- /dev/null +++ b/decisions/0018-wordpress-plugin-security.md @@ -0,0 +1,61 @@ +# ADR 0018 — WordPress-Plugin-Sicherheit + +## Status +Proposed + +## Kurz erklärt +Das WordPress-Plugin ist später ein API-Client. + +Es läuft in einer WordPress-Umgebung, die möglicherweise durch andere Plugins, Themes oder schlechte Wartung gefährdet ist. + +## Kontext +WordPress soll nicht Core sein, aber später als Frontend-/Widget-Schicht dienen. + +Das Architekturreview hat gewarnt, dass das Plugin eine zweite Sicherheitsdomäne erzeugt. + +## Entscheidung +Das WordPress-Plugin wird nicht Teil von V1. + +Für spätere Versionen gilt: + +- Plugin nutzt ausschließlich REST API +- Plugin bekommt minimale API-Scopes +- keine direkten Datenbankzugriffe +- keine lokalen Kopien sensibler Daten, außer technisch zwingend nötig +- Token-Rotation muss möglich sein +- Plugin-Zugriffe werden auditierbar + +## API-Scopes +Das Plugin darf nur das, was für seine Widgets nötig ist. + +Beispiele: + +- Kundenbereich anzeigen +- Ticket erstellen +- Rechnungsreferenzen anzeigen +- Vertragsdaten lesen + +Nicht erlaubt: + +- globale Adminfunktionen +- Anbieter-Credentials lesen +- fremde Mandantendaten lesen + +## Bei kompromittierter WordPress-Seite +Ein kompromittiertes Plugin-Token darf nicht das gesamte Backoffice gefährden. + +Deshalb: + +- Token widerrufbar +- Scope begrenzt +- Mandant begrenzt +- Audit-Logs +- Rate-Limits + +## Status +Diese ADR bleibt zunächst Proposed, weil das WordPress-Plugin erst nach V1 konkret geplant wird. + +## Verwandte ADRs +- ADR 0006 — Auth-Strategie +- ADR 0012 — Frontend-Strategie +- ADR 0020 — Customer-Portal-Scope diff --git a/decisions/0019-v1-scope-finalization.md b/decisions/0019-v1-scope-finalization.md new file mode 100644 index 0000000..e922380 --- /dev/null +++ b/decisions/0019-v1-scope-finalization.md @@ -0,0 +1,77 @@ +# ADR 0019 — V1-Scope-Finalisierung + +## Status +Accepted + +## Kurz erklärt +Der V1-Scope legt fest, was in die erste produktiv nutzbare Version gehört und was bewusst nicht. + +Das verhindert Feature-Explosion. + +## Kontext +Das Architekturreview hat Widersprüche festgestellt: + +- 1–500 Kunden vs. 1–50 Kunden +- KI in V1 vs. V2 +- Customer Portal in V1 vs. unklar +- SEPA als Zahlungsart ohne Modell + +## Entscheidung +V1 wird auf eine interne produktive Grundversion für kleine Anbieter mit 1–50 Kunden begrenzt. + +## V1 enthält + +- Admin-/Backoffice-Oberfläche +- Kundenverwaltung +- Kontakt-/Adressmodell +- Verträge +- Produkte/Leistungen +- Domains +- Registrar-Import 1blu +- Server-/Hosting-Zuordnung +- Rechnungsreferenzen +- Billing-Referenzen zu Lexware/Invoice Ninja +- Tickets light intern +- Dokumentenablage +- Audit-Logs +- Tax-/VAT-Metadaten minimal +- Nummernkreise +- einfache Statuslogik + +## V1 enthält NICHT + +- KI-Assistent +- öffentliches WordPress-Plugin +- vollständiges Customer Portal +- SEPA-Lastschrift mit Mandatsverwaltung +- eigenes Payment-System +- eigene Rechnungsstellung als führendes System +- automatische Servermigration +- automatische VM-/Cloud-Provisionierung +- Plesk/cPanel +- Marketplace + +## Customer Portal +Ein vollständiges Kundenportal wird auf V2 verschoben. + +In V1 kann optional eine interne Kundenansicht vorbereitet werden, aber kein öffentlicher Self-Service. + +## KI +KI wird auf V2 verschoben. + +Grund: + +- Datenschutz +- Subprozessoren +- Drittlandtransfer +- unnötige V1-Komplexität + +## Zahlungsarten +In V1 werden Zahlungsarten nur als Referenz/Status geführt. + +Keine echte Zahlungsabwicklung im Backoffice. + +## Verwandte ADRs +- ADR 0011 — GoBD-Verantwortlichkeit +- ADR 0015 — Tax- und VAT-Strategie +- ADR 0020 — Customer-Portal-Scope diff --git a/decisions/0020-customer-portal-scope.md b/decisions/0020-customer-portal-scope.md new file mode 100644 index 0000000..66fb439 --- /dev/null +++ b/decisions/0020-customer-portal-scope.md @@ -0,0 +1,58 @@ +# ADR 0020 — Customer-Portal-Scope + +## Status +Accepted + +## Kurz erklärt +Das Kundenportal ist der Bereich, in dem Endkunden später selbst Daten, Rechnungen, Verträge und Tickets sehen können. + +## Kontext +Das Architekturreview hat kritisiert, dass das Customer Portal gleichzeitig als V1-Modul genannt, aber nicht konsistent im MVP enthalten war. + +## Entscheidung +Ein vollständiges Customer Portal ist nicht Teil von V1. + +## V1 +V1 enthält nur eine interne Kundenansicht für Admins/Mitarbeiter. + +Diese zeigt: + +- Kundendaten +- Verträge +- Domains +- Hostingpakete +- Rechnungsreferenzen +- Tickets +- Dokumente + +## V2 +Das öffentliche Customer Portal wird in V2 geplant. + +Dann müssen zusätzlich geklärt werden: + +- Kundenlogin +- Self-Service +- Barrierefreiheit +- AGB-/Datenschutz-Hinweise +- Session-Sicherheit +- Passwort-Reset +- MFA optional +- WordPress-Integration + +## Warum nicht V1? +Ein öffentliches Portal erhöht V1-Komplexität stark: + +- Sicherheitsrisiko +- Supportaufwand +- rechtliche Anforderungen +- UI-/UX-Aufwand +- Barrierefreiheit +- Auth-Komplexität + +## Konsequenz +V1 wird stabiler und schneller erreichbar. + +## Verwandte ADRs +- ADR 0012 — Frontend-Strategie +- ADR 0018 — WordPress-Plugin-Sicherheit +- ADR 0019 — V1-Scope-Finalisierung diff --git a/decisions/0021-dsgvo-deletion-retention.md b/decisions/0021-dsgvo-deletion-retention.md new file mode 100644 index 0000000..3990a39 --- /dev/null +++ b/decisions/0021-dsgvo-deletion-retention.md @@ -0,0 +1,53 @@ +# ADR 0021 — DSGVO-Löschung und Retention + +## Status +Proposed + +## Kurz erklärt +DSGVO-Löschung bedeutet, dass personenbezogene Daten unter bestimmten Voraussetzungen gelöscht werden müssen. + +Retention bedeutet Aufbewahrungspflicht, z. B. für Rechnungsunterlagen. + +Diese Anforderungen können kollidieren. + +## Kontext +Das Architekturreview hat bemängelt, dass DSGVO-Löschung und GoBD-Aufbewahrung nicht modelliert wurden. + +## Entscheidung +V1 muss ein Lösch-/Pseudonymisierungskonzept vorbereiten. + +## Grundprinzip +Personenbezogene Stammdaten sollen von retentionspflichtigen Belegdaten getrennt werden. + +## Modell +Bei Löschanforderung: + +- nicht aufbewahrungspflichtige Daten werden gelöscht +- aufbewahrungspflichtige Daten bleiben erhalten +- personenbezogene Daten werden soweit möglich pseudonymisiert +- Audit-Log dokumentiert den Vorgang + +## Beispiel +Statt Kundenname: + +```text +Gelöschter Kunde 8f3a... +``` + +## Nicht einfach löschen +Rechnungsrelevante Daten dürfen ggf. nicht vollständig gelöscht werden, wenn gesetzliche Aufbewahrungspflichten bestehen. + +## V1-Mindestanforderung + +- Kennzeichnung gelöschter/pseudonymisierter Kunden +- Export der Kundendaten vorbereiten +- Trennung von Stammdaten und Belegdaten +- Audit-Log für Löschung/Pseudonymisierung + +## Offener Punkt +Rechtliche Prüfung erforderlich. + +## Verwandte ADRs +- ADR 0011 — GoBD-Verantwortlichkeit +- ADR 0013 — Kunden-/Adress-/Kontaktmodell +- ADR 0014 — Audit-Log-Strategie diff --git a/decisions/0022-document-hierarchy.md b/decisions/0022-document-hierarchy.md new file mode 100644 index 0000000..dfe214b --- /dev/null +++ b/decisions/0022-document-hierarchy.md @@ -0,0 +1,55 @@ +# ADR 0022 — Dokumentenhierarchie und Single Source of Truth + +## Status +Accepted + +## Kurz erklärt +Single Source of Truth bedeutet: + +```text +Es gibt eine verbindliche Quelle, +wenn sich Dokumente widersprechen. +``` + +## Kontext +Das Architekturreview hat kritisiert, dass mehrere Dokumente unterschiedliche Aussagen enthalten. + +Beispiele: + +- V1-Kundenzahl +- KI in V1 oder V2 +- Customer Portal in V1 oder V2 +- Module im Core oder Service-Modul + +## Entscheidung +Es gilt folgende Dokumentenhierarchie: + +1. ADRs +2. Architektur-Dokumente +3. Modulstruktur +4. Roadmap +5. Modul-Detaildokumente +6. Brainstorming-/Ideendokumente + +## Konsequenz +Wenn sich Dokumente widersprechen, gilt die höhere Ebene. + +Beispiel: + +Wenn ADR 0019 sagt „KI ist V2“, aber ein altes Modul-Dokument KI als V1 beschreibt, gilt ADR 0019. + +## Pflege-Regel +Nach jeder größeren ADR-Serie müssen betroffene Dokumente aktualisiert werden. + +## Ziel +Architekturdrift verhindern. + +Architekturdrift bedeutet: + +```text +Planung und tatsächliche Umsetzung entfernen sich schleichend voneinander. +``` + +## Verwandte ADRs +- ADR 0019 — V1-Scope-Finalisierung +- ADR 0009 — Core-Grenzen diff --git a/decisions/0023-numbering-sequences.md b/decisions/0023-numbering-sequences.md new file mode 100644 index 0000000..f4d8fba --- /dev/null +++ b/decisions/0023-numbering-sequences.md @@ -0,0 +1,62 @@ +# ADR 0023 — Nummernkreise + +## Status +Accepted + +## Kurz erklärt +Nummernkreise erzeugen eindeutige Nummern für: + +- Kunden +- Verträge +- Rechnungsreferenzen +- Tickets + +Bei Rechnungen sind Nummern besonders sensibel, weil sie steuerlich relevant sein können. + +## Kontext +Das Architekturreview hat fehlende Nummernkreislogik als V1-Risiko bewertet. + +## Entscheidung +V1 erhält eine zentrale Nummernkreisverwaltung pro Tenant. + +## Beispielstruktur + +```text +number_sequences +- tenant_id +- sequence_key +- prefix +- current_number +- padding +- reset_strategy +- locked_at +``` + +## Beispiele + +```text +K-00001 +V-00001 +T-2026-00001 +``` + +## Rechnungen +Da Hosting-Backoffice V1 nicht führendes Rechnungssystem ist, erzeugt es keine verbindlichen Rechnungsnummern. + +Es speichert externe Rechnungsnummern aus Lexware/Invoice Ninja. + +## Interne Referenzen +Für interne Vorgänge dürfen eigene Referenzen erzeugt werden. + +## Technische Regel +Nummernvergabe muss atomar erfolgen. + +Atomar bedeutet: + +```text +Zwei gleichzeitige Vorgänge dürfen nicht dieselbe Nummer erhalten. +``` + +## Verwandte ADRs +- ADR 0011 — GoBD-Verantwortlichkeit +- ADR 0019 — V1-Scope-Finalisierung diff --git a/development/api-conventions-v0.1.md b/development/api-conventions-v0.1.md new file mode 100644 index 0000000..a64ef7f --- /dev/null +++ b/development/api-conventions-v0.1.md @@ -0,0 +1,34 @@ +# API Conventions v0.1 + +## Grundprinzip + +Die REST API soll konsistent und verständlich aufgebaut sein. + +## Versionierung + +- /api/v1/ + +## Ressourcenbeispiele + +- /customers +- /contracts +- /domains +- /hosting-packages +- /servers +- /invoices +- /tickets +- /documents + +## Antworten + +API-Antworten sollen konsistent sein: +- data +- meta +- errors + +## Sicherheit + +- Authentifizierung erforderlich +- Rechteprüfung je Ressource +- Rate-Limiting +- API-Logs diff --git a/development/coding-standards-v0.1.md b/development/coding-standards-v0.1.md new file mode 100644 index 0000000..f828c8d --- /dev/null +++ b/development/coding-standards-v0.1.md @@ -0,0 +1,28 @@ +# Coding Standards v0.1 + +## Grundprinzip + +Code soll verständlich, testbar und wartbar sein. + +## Laravel-Konventionen + +- klare Services +- Controller schlank halten +- Businesslogik nicht in Views +- Migrations nachvollziehbar benennen +- Policies für Rechteprüfungen verwenden +- Events/Jobs für asynchrone Prozesse prüfen + +## Sicherheit + +- keine Secrets im Code +- Eingaben validieren +- Rechte prüfen +- Audit-Logs bei kritischen Aktionen + +## Tests + +- kritische Workflows testen +- Importprozesse testen +- Rechteprüfungen testen +- API-Endpunkte testen diff --git a/development/development-principles-v0.1.md b/development/development-principles-v0.1.md new file mode 100644 index 0000000..b7abb4b --- /dev/null +++ b/development/development-principles-v0.1.md @@ -0,0 +1,22 @@ +# Development Principles v0.1 + +## Grundprinzip + +Hosting-Backoffice soll modular, verständlich, wartbar und nachvollziehbar entwickelt werden. + +## Architekturprinzipien + +- kein Monolith +- API-first +- Sicherheit zuerst +- kundenzentriert +- modulare Erweiterbarkeit +- Logging und Auditierung + +## Erweiterbarkeit + +Neue Module sollen aktivierbar, deaktivierbar und austauschbar sein. + +## Ziel + +Hosting-Backoffice soll langfristig professionell, stabil, verständlich und modular bleiben. diff --git a/development/module-development-guidelines-v0.1.md b/development/module-development-guidelines-v0.1.md new file mode 100644 index 0000000..2d55819 --- /dev/null +++ b/development/module-development-guidelines-v0.1.md @@ -0,0 +1,29 @@ +# Module Development Guidelines v0.1 + +## Grundprinzip + +Module erweitern das System, ohne den Core hart zu koppeln. + +## Anforderungen + +Jedes Modul soll: +- klaren Zweck haben +- aktivierbar/deaktivierbar sein +- definierte Interfaces nutzen +- eigene Konfiguration haben +- Fehler sauber protokollieren + +## Nicht erlaubt + +- direkte Core-Manipulation ohne Service-Schicht +- unprotokollierte kritische Änderungen +- direkte Anbieterlogik im Core + +## Dokumentation + +Jedes Modul benötigt: +- Zweck +- Datenobjekte +- API-Endpunkte falls vorhanden +- Rechteanforderungen +- Risiken diff --git a/modules/ai-assistant-module-v0.1.md b/modules/ai-assistant-module-v0.1.md new file mode 100644 index 0000000..114aca2 --- /dev/null +++ b/modules/ai-assistant-module-v0.1.md @@ -0,0 +1,29 @@ +# AI Assistant Module v0.1 + +## Grundprinzip + +KI-Funktionen unterstützen Benutzer und Prozesse. + +Die KI ersetzt keine Kernlogik und trifft keine finalen Entscheidungen. + +## V1-Prinzip + +Die KI darf: +- Vorschläge machen +- Daten erkennen +- Zusammenfassungen erstellen + +Die endgültige Entscheidung trifft ein Benutzer. + +## Geplante Funktionen + +- Ticketzusammenfassungen +- Antwortvorschläge +- Rechnungserkennung +- Kundenerkennung +- Vertragsvorschläge +- Importunterstützung + +## Sicherheitsprinzip + +KI erhält nur notwendige Daten, keine direkten Systemrechte und keine direkten Schreibrechte im Core. diff --git a/modules/billing-module-v0.1.md b/modules/billing-module-v0.1.md new file mode 100644 index 0000000..f1c4eca --- /dev/null +++ b/modules/billing-module-v0.1.md @@ -0,0 +1,39 @@ +# Billing Module v0.1 + +## Grundprinzip + +Hosting-Backoffice ist kein eigenes Buchhaltungs- oder Banking-System. + +Billing wird über externe Systeme integriert. + +## Unterstützte Systeme V1 + +- Lexware Office +- Invoice Ninja CE + +## Zahlungsarten + +- Rechnung +- Überweisung +- Lastschrift +- PayPal +- Wero + +## Zahlungslogik + +Das System verarbeitet zunächst keine echten Zahlungen selbst. + +Es verwaltet: +- Status +- Referenzen +- Hinweise +- spätere Gebührenregeln + +## Rechnungen + +Das System speichert: +- Rechnungsnummern +- Zahlungsstatus +- Beträge +- Referenzen +- Archivverweise diff --git a/modules/customer-portal-module-v0.1.md b/modules/customer-portal-module-v0.1.md new file mode 100644 index 0000000..66de227 --- /dev/null +++ b/modules/customer-portal-module-v0.1.md @@ -0,0 +1,33 @@ +# Customer Portal Module v0.1 + +## Grundprinzip + +Das Kundenportal ist die zentrale Kundenansicht. + +Der Kunde soll professionell betreut, informiert und sicher eingebunden werden. + +## V1-Funktionen + +### Kundenbereich +- Stammdaten +- Verträge +- Domains +- Hostingpakete + +### Rechnungen +- Rechnungsübersicht +- Zahlungsstatus +- Dokumente + +### Support +- Tickets +- Antworten +- Ticketstatus + +### Dokumente +- PDFs +- Anhänge + +## Sicherheitsprinzip + +Kunden sehen ausschließlich eigene Daten. diff --git a/modules/document-archive-module-v0.1.md b/modules/document-archive-module-v0.1.md new file mode 100644 index 0000000..394cd83 --- /dev/null +++ b/modules/document-archive-module-v0.1.md @@ -0,0 +1,27 @@ +# Document Archive Module v0.1 + +## Grundprinzip + +Das Dokumentenarchiv verwaltet Dateien, Metadaten, Hashes und Objektbezüge. + +## V1-Funktionen + +- PDF-Ablage +- Dokumentenmetadaten +- Hash-Erzeugung +- Objektverknüpfung +- Audit-Log bei Upload und Änderung + +## Dokumentenarten + +- Rechnungen +- Verträge +- Supportanhänge +- Importdateien +- Kundenunterlagen + +## Nicht Ziel von V1 + +- vollständiges DMS +- eigene Buchhaltung +- rechtlich garantierte GoBD-Zertifizierung diff --git a/modules/import-assistant-module-v0.1.md b/modules/import-assistant-module-v0.1.md new file mode 100644 index 0000000..be32f3d --- /dev/null +++ b/modules/import-assistant-module-v0.1.md @@ -0,0 +1,29 @@ +# Import Assistant Module v0.1 + +## Grundprinzip + +Importe sollen kleinen Anbietern den Einstieg erleichtern. + +Bestehende Daten sollen möglichst einfach übernommen werden können. + +## V1 + +### Registrar-Import +- 1blu Exporte +- mehrere Accounts +- Domains erkennen + +### Kundenzuordnung +- manuelle Zuordnung +- Vorschläge später möglich + +## KI-Unterstützung später + +- Rechnungserkennung +- Kundenerkennung +- Vertragsvorschläge +- automatische Vorschläge + +## Sicherheitsprinzip + +Importe verändern niemals ungeprüft Core-Daten. Sie werden geprüft, protokolliert und bestätigt. diff --git a/modules/keyhelp-module-v0.1.md b/modules/keyhelp-module-v0.1.md new file mode 100644 index 0000000..6bbb029 --- /dev/null +++ b/modules/keyhelp-module-v0.1.md @@ -0,0 +1,26 @@ +# KeyHelp Module v0.1 + +## Grundprinzip + +KeyHelp wird als modular angebundenes Hostingpanel integriert. + +Die Plattform bleibt providerneutral. + +## V1-Funktionen + +- Serverobjekte +- KeyHelp-Referenzen +- Hostingpaket-Zuordnung +- Serverstatus später möglich + +## Später geplant + +- Hostingdaten synchronisieren +- Ressourceninformationen +- Benutzerinformationen +- Servertemplates +- Konfigurationsprofile +- API-gestützte Abläufe +- Paketverschiebungen +- Mailmigrationen +- Downtimeplanung diff --git a/modules/module-structure-v0.1.md b/modules/module-structure-v0.1.md new file mode 100644 index 0000000..ccb5dcd --- /dev/null +++ b/modules/module-structure-v0.1.md @@ -0,0 +1,47 @@ +# Module Structure v0.1 + +## Grundprinzip + +Hosting-Backoffice basiert auf: +- Core +- Service-Modulen +- Integrationsmodulen + +Der Core enthält ausschließlich zentrale Plattformlogik. + +## Core-Bereiche + +- Benutzer +- Rollen/Rechte +- Kunden +- Verträge +- Produkte +- Domains +- Hostingpakete +- Server +- Dokumente +- Audit-Logs +- Benachrichtigungen +- API +- Einstellungen + +## Service-Module + +- Ticketsystem +- KI-Assistent +- Import-Assistent +- Dokumentenarchiv +- Migrationen später + +## Integrationsmodule + +- Lexware Office +- Invoice Ninja CE +- KeyHelp +- 1blu Business +- PayPal +- Wero + +## WordPress-Plugin + +Das WordPress-Plugin ist kein Corebestandteil. Es dient später als Frontend-Integration über die REST API. diff --git a/modules/registrar-module-v0.1.md b/modules/registrar-module-v0.1.md new file mode 100644 index 0000000..f8cb9ec --- /dev/null +++ b/modules/registrar-module-v0.1.md @@ -0,0 +1,39 @@ +# Registrar Module v0.1 + +## Grundprinzip + +Domains und Registrarinformationen werden zentral verwaltet. + +Registrare werden modular angebunden. + +## V1 + +Unterstützt: +- 1blu Business + +## Funktionen + +### Registrar-Accounts +- mehrere Accounts +- Accountbeschreibung +- Anbieterreferenz + +### Domainverwaltung +- Domainname +- TLD +- Status +- Laufzeiten +- Kundenzuordnung + +### Importfunktionen +- Exportdateien einlesen +- Domains erkennen +- Kundenzuordnung +- Audit-Protokollierung + +## Später geplant + +- API-Synchronisation +- weitere Registrare +- TLD-Regeln +- Routinglogik diff --git a/modules/server-migration-module-future.md b/modules/server-migration-module-future.md new file mode 100644 index 0000000..b805f80 --- /dev/null +++ b/modules/server-migration-module-future.md @@ -0,0 +1,21 @@ +# Server Migration Module Future + +## Grundprinzip + +Servermigrationen sind eine spätere Erweiterung und nicht Teil von V1. + +## Geplante Funktionen + +- Hostingpaket von Server A nach Server B verschieben +- Webdaten übertragen +- Datenbanken übertragen +- Maildaten übertragen +- DNS vorbereiten +- Downtime planen +- Kunden informieren +- Rollback ermöglichen +- Migration protokollieren + +## Architekturhinweis + +V1 muss bereits wissen, auf welchem Server ein Hostingpaket liegt, damit spätere Migrationen möglich werden. diff --git a/modules/server-template-module-future.md b/modules/server-template-module-future.md new file mode 100644 index 0000000..df48b01 --- /dev/null +++ b/modules/server-template-module-future.md @@ -0,0 +1,24 @@ +# Server Template Module Future + +## Grundprinzip + +Server-Templates sind eine spätere Automatisierungsfunktion. + +## Ziel + +Neue Server sollen nach definierten Profilen eingerichtet werden können. + +## Mögliche Inhalte + +- KeyHelp-Installation +- Basiskonfiguration +- PHP-Versionen +- Mailserver-Konfiguration +- DNS-Konfiguration +- Sicherheitsregeln +- Backup-Konfiguration +- Monitoring + +## V1-Vorbereitung + +V1 sollte Serverrollen und Servermetadaten so erfassen, dass spätere Templates möglich bleiben. diff --git a/modules/ticket-system-module-v0.1.md b/modules/ticket-system-module-v0.1.md new file mode 100644 index 0000000..7f5ee54 --- /dev/null +++ b/modules/ticket-system-module-v0.1.md @@ -0,0 +1,33 @@ +# Ticket System Module v0.1 + +## Grundprinzip + +Das Ticketsystem ist kundenzentriert aufgebaut. + +Support soll direkt mit Kunden, Domains, Hostingpaketen und Verträgen verbunden sein. + +## V1-Funktionen + +- Tickets erstellen +- Tickets beantworten +- Tickets schließen +- Priorität setzen +- Status setzen +- interne Notizen + +## Verknüpfungen + +Ein Ticket kann verbunden sein mit: +- Kunde +- Domain +- Hostingpaket +- Vertrag +- Rechnung später möglich + +## KI-Unterstützung später + +- Ticketzusammenfassungen +- Antwortvorschläge +- automatische Kategorisierung +- Priorisierung +- Wissensdatenbankintegration diff --git a/modules/wordpress-plugin-strategy-v0.1.md b/modules/wordpress-plugin-strategy-v0.1.md new file mode 100644 index 0000000..9aa41f3 --- /dev/null +++ b/modules/wordpress-plugin-strategy-v0.1.md @@ -0,0 +1,32 @@ +# WordPress Plugin Strategy v0.1 + +## Grundprinzip + +Das WordPress-Plugin ist eine optionale Frontend-Erweiterung. + +Der Plattformkern bleibt unabhängig. + +## Wichtig + +WordPress ist nicht der Core. + +Alle Funktionen laufen über die REST API. Keine direkte Datenbankkopplung. + +## Geplante Funktionen + +- Login-Widget +- Kundenbereich +- Verträge +- Domains +- Rechnungen +- Tickets +- Produktdarstellung +- Supportintegration + +## Langfristige Ziele + +- Elementor-Widgets +- Gutenberg-Blöcke +- Bestellprozesse +- Kunden-Dashboards +- API-basierte Echtzeitdaten diff --git a/notizen.txt b/notizen.txt new file mode 100644 index 0000000..1d43671 --- /dev/null +++ b/notizen.txt @@ -0,0 +1,10 @@ +AI Workspace einrichten: + +1. Basisserver absichern +2. Arbeitsuser anlegen +3. Git installieren +4. Docker installieren +5. Projektordner anlegen +6. Gitea installieren +7. Projekt als privates Git-Repo ablegen +8. Danach optional: VS Code Server / Open WebUI \ No newline at end of file diff --git a/notizen.txt.bak b/notizen.txt.bak new file mode 100644 index 0000000..e69de29 diff --git a/processes/customer-onboarding-process-v0.1.md b/processes/customer-onboarding-process-v0.1.md new file mode 100644 index 0000000..fd95da0 --- /dev/null +++ b/processes/customer-onboarding-process-v0.1.md @@ -0,0 +1,21 @@ +# Customer Onboarding Process v0.1 + +## Ziel + +Ein neuer Kunde soll einfach, nachvollziehbar und professionell angelegt werden können. + +## Ablauf V1 + +1. Kunde anlegen +2. Ansprechpartner erfassen +3. Vertrag anlegen +4. Produkt/Hostingpaket zuweisen +5. Domain zuweisen oder importieren +6. Serverbezug erfassen +7. Rechnungsreferenz anlegen oder später synchronisieren +8. Dokumente ablegen +9. Audit-Log schreiben + +## Erfolgsziel + +Ein Anbieter kann einen Kunden vollständig erfassen, ohne auf Excel oder verstreute Notizen angewiesen zu sein. diff --git a/processes/invoice-import-ai-process-future.md b/processes/invoice-import-ai-process-future.md new file mode 100644 index 0000000..66b56a8 --- /dev/null +++ b/processes/invoice-import-ai-process-future.md @@ -0,0 +1,25 @@ +# Invoice Import AI Process Future + +## Ziel + +Alte Kundenrechnungen sollen KI-gestützt analysiert werden, um Bestandsdaten einfacher zu übernehmen. + +## Mögliche Erkennung + +- Kundennamen +- Anschriften +- alte Kundennummern +- Rechnungsnummern +- Leistungspositionen +- Domains +- Hostingpakete +- Leistungszeiträume +- Beträge + +## Prinzip + +Die KI macht Vorschläge. Der Admin bestätigt. + +## Sicherheitsprinzip + +Keine automatische Übernahme ohne menschliche Prüfung. diff --git a/processes/payment-status-process-v0.1.md b/processes/payment-status-process-v0.1.md new file mode 100644 index 0000000..ebf42a9 --- /dev/null +++ b/processes/payment-status-process-v0.1.md @@ -0,0 +1,25 @@ +# Payment Status Process v0.1 + +## Ziel + +Zahlungsstatus sollen nachvollziehbar und einfach verwaltet werden. + +## Statusbeispiele + +- offen +- bezahlt +- teilweise bezahlt +- überfällig +- storniert +- extern verwaltet + +## Ablauf V1 + +1. Rechnung oder Referenz wird importiert/angelegt +2. Zahlungsart wird angezeigt +3. Status wird manuell oder per Integration aktualisiert +4. Änderung wird protokolliert + +## Wichtig + +Hosting-Backoffice verarbeitet keine Zahlung selbst. diff --git a/processes/registrar-import-process-v0.1.md b/processes/registrar-import-process-v0.1.md new file mode 100644 index 0000000..2d4dd22 --- /dev/null +++ b/processes/registrar-import-process-v0.1.md @@ -0,0 +1,21 @@ +# Registrar Import Process v0.1 + +## Ziel + +Bestehende Domains sollen aus 1blu-Exporten übernommen und Kunden zugeordnet werden können. + +## Ablauf V1 + +1. Registrar-Account anlegen +2. Exportdatei hochladen +3. Import prüfen +4. Domains erkennen +5. Dubletten erkennen +6. Kunden manuell zuweisen +7. Import bestätigen +8. Audit-Log schreiben +9. Importdatei archivieren + +## Sicherheitsprinzip + +Der Import verändert keine finalen Kundenzuordnungen ohne Bestätigung. diff --git a/processes/ticket-workflow-v0.1.md b/processes/ticket-workflow-v0.1.md new file mode 100644 index 0000000..676ba60 --- /dev/null +++ b/processes/ticket-workflow-v0.1.md @@ -0,0 +1,22 @@ +# Ticket Workflow v0.1 + +## Ziel + +Supportanfragen sollen professionell, kundenzentriert und nachvollziehbar bearbeitet werden. + +## Ablauf + +1. Kunde erstellt Ticket oder Admin legt Ticket an +2. Ticket wird Kunde zugeordnet +3. Optional: Domain/Hostingpaket/Vertrag verknüpfen +4. Priorität setzen +5. Antwort verfassen +6. interne Notizen nutzen +7. Status aktualisieren +8. Abschluss dokumentieren + +## Später + +- KI-Zusammenfassung +- Antwortvorschläge +- automatische Kategorisierung diff --git a/prompts/architecture-review-prompt.md b/prompts/architecture-review-prompt.md new file mode 100644 index 0000000..9151542 --- /dev/null +++ b/prompts/architecture-review-prompt.md @@ -0,0 +1,192 @@ +# Architecture Review Prompt + +## Wichtiger Hinweis + +Die Projektinformationen werden schrittweise in mehreren Nachrichten übergeben. + +Bitte: + +* zunächst nur analysieren +* noch kein finales Gesamtfazit ziehen +* Inkonsistenzen und Risiken bereits notieren +* offene Fragen sammeln +* erst nach der letzten Nachricht ein vollständiges Review erstellen + +Ein finales Architekturreview erfolgt erst nach der letzten Nachricht mit dem Hinweis: + +"Bitte jetzt Gesamtreview erstellen." + +--- + +## Deine Rolle + +Du agierst als kritischer Senior Software Architect und Platform Engineer. + +Deine Aufgabe ist NICHT, das Projekt zu bestätigen oder zu loben. + +Deine Aufgabe ist es: + +* Architekturfehler zu erkennen +* spätere Skalierungsprobleme zu identifizieren +* gefährliche Entscheidungen aufzudecken +* unnötige Komplexität zu erkennen +* fehlende Kernkonzepte zu finden +* Sicherheitsrisiken zu analysieren +* problematische Modulgrenzen aufzudecken +* zukünftige Monolith-Risiken zu erkennen +* spätere Refactoring-Kosten sichtbar zu machen + +--- + +## Bitte vermeide + +* oberflächliche Zustimmung +* generisches SaaS-Lob +* allgemeine Laravel-Standardantworten +* unkritische Bestätigung der Planung +* zu frühe Lösungsvorschläge ohne Risikoanalyse + +--- + +## Fokus der Analyse + +Der Fokus liegt auf: + +* echten Architekturproblemen +* Skalierungsrisiken +* Sicherheitsrisiken +* problematischen Modulgrenzen +* zukünftigen Refactoring-Risiken +* versteckter Komplexität +* unklaren Verantwortlichkeiten zwischen Core und Modulen +* Risiken bei Mandantenfähigkeit +* Risiken bei API-first-Architektur +* Risiken durch spätere WordPress-Anbindung + +--- + +## Projektkontext + +Das Projekt ist ein neues europäisches Hosting-Backoffice-System für kleine professionelle Anbieter. + +Wichtige Prinzipien: + +* Laravel Standalone-Core +* REST API +* modularer Aufbau +* kundenzentriert +* kein Enterprise-Monolith +* kein eigenes Payment-/Banking-System +* WordPress nur als optionales Frontend-Plugin +* API-first +* Mandantenfähigkeit von Anfang an vorbereiten +* europäischer Fokus mit DSGVO-/GoBD-Orientierung +* Integrationen über Module, nicht direkt im Core + +--- + +## Wichtige Prüffragen + +Bitte analysiere die bereitgestellten Dateien kritisch anhand dieser Fragen: + +1. Welche Architekturentscheidungen sind gefährlich? +2. Welche Teile werden später schwer skalierbar? +3. Welche Module sind falsch getrennt? +4. Wo droht ein zukünftiger Monolith? +5. Welche Datenobjekte fehlen? +6. Welche Sicherheitsprobleme erkennst du? +7. Welche Probleme siehst du bei Mandantenfähigkeit? +8. Welche API-Strategien sind problematisch? +9. Welche V1-Funktionen sind zu groß gedacht? +10. Welche Funktionen fehlen für eine produktive V1? +11. Welche Integrationen sind architektonisch riskant? +12. Welche Entscheidungen sollten JETZT getroffen werden, bevor Entwicklung beginnt? +13. Welche Teile wirken unnötig kompliziert? +14. Welche Teile wirken noch nicht klar genug definiert? +15. Welche Bereiche würden später hohe Refactoring-Kosten verursachen? +16. Welche Datenobjekte oder Beziehungen fehlen im Datenmodell? +17. Welche Modulgrenzen sind unscharf? +18. Welche Sicherheitsannahmen sind gefährlich? +19. Welche V1-Ziele sollten reduziert werden? +20. Welche V1-Ziele dürfen nicht weiter nach hinten geschoben werden? + +--- + +## Arbeitsweise während der Dateiübergabe + +Solange noch nicht ausdrücklich "Bitte jetzt Gesamtreview erstellen." geschrieben wurde: + +* nur Zwischenanalyse erstellen +* erkannte Risiken notieren +* offene Fragen sammeln +* keine finale Gesamtbewertung abgeben +* keine endgültige Priorisierung vornehmen + +--- + +## Finales Ausgabeformat + +Wenn die Nachricht "Bitte jetzt Gesamtreview erstellen." kommt, strukturiere die finale Ausgabe bitte exakt in diese drei Markdown-Dateien: + +--- + +# reviews/claude-review-round1.md + +Inhalt: + +* Gesamtanalyse +* Architekturkritik +* Core-/Modulbewertung +* Datenmodellbewertung +* API-Bewertung +* Mandantenfähigkeitsbewertung +* V1-Scope-Bewertung +* Roadmap-Bewertung +* Empfehlungen für die nächste Arbeitsphase + +--- + +# reviews/claude-open-questions.md + +Inhalt: + +* offene Architekturfragen +* unklare Entscheidungen +* fehlende Definitionen +* notwendige Produktentscheidungen +* Fragen, die vor Entwicklungsbeginn geklärt werden müssen + +--- + +# reviews/claude-critical-risks.md + +Inhalt: + +* kritische Architekturprobleme +* Monolith-Risiken +* Sicherheitsprobleme +* problematische Skalierungsentscheidungen +* spätere Refactoring-Gefahren +* Compliance-/Mandantenfähigkeitsrisiken + +Bitte kennzeichne jedes Risiko zusätzlich mit: + +* Schweregrad: LOW / MEDIUM / HIGH / CRITICAL +* Zeitpunkt: NOW / V1 / V2 / V3 / LATER +* Empfehlung: was konkret entschieden oder geprüft werden sollte + +--- + +## Wichtig + +Sei kritisch. + +Stelle Annahmen infrage. + +Suche aktiv nach Problemen. + +Denke wie ein erfahrener SaaS-/Platform-Architekt. + +Denke langfristig. + +Das Ziel ist Architekturqualität, nicht Bestätigung. diff --git a/prompts/architecture-review-prompt.md.bak b/prompts/architecture-review-prompt.md.bak new file mode 100644 index 0000000..275f0cc --- /dev/null +++ b/prompts/architecture-review-prompt.md.bak @@ -0,0 +1,96 @@ +# Wichtiger Hinweis + +Die Projektinformationen werden schrittweise in mehreren Nachrichten übergeben. + +Bitte: + +* zunächst nur analysieren +* noch kein finales Gesamtfazit ziehen +* Inkonsistenzen und Risiken bereits notieren +* offene Fragen sammeln + +Ein finales Architekturreview erfolgt erst nach der letzten Nachricht mit dem Hinweis: + +"Bitte jetzt Gesamtreview erstellen." + +Bitte vermeide: + +* oberflächliche Zustimmung +* generisches SaaS-Lob +* allgemeine Laravel-Standardantworten + +Der Fokus liegt auf: + +* echten Architekturproblemen +* Skalierungsrisiken +* Sicherheitsrisiken +* problematischen Modulgrenzen +* zukünftigen Refactoring-Risiken +* versteckter Komplexität + + +# Architecture Review Prompt + +Du agierst als kritischer Senior Software Architect und Platform Engineer. + +Deine Aufgabe ist NICHT, das Projekt zu bestätigen oder zu loben. + +Deine Aufgabe ist es: + +* Architekturfehler zu erkennen +* spätere Skalierungsprobleme zu identifizieren +* gefährliche Entscheidungen aufzudecken +* unnötige Komplexität zu erkennen +* fehlende Kernkonzepte zu finden +* Sicherheitsrisiken zu analysieren +* problematische Modulgrenzen aufzudecken +* zukünftige Monolith-Risiken zu erkennen + +Das Projekt ist ein neues europäisches Hosting-Backoffice-System für kleine professionelle Anbieter. + +Wichtige Prinzipien: + +* Laravel Standalone-Core +* REST API +* modularer Aufbau +* kundenzentriert +* kein Enterprise-Monolith +* kein eigenes Payment-/Banking-System +* WordPress nur als optionales Frontend-Plugin +* API-first +* Mandantenfähigkeit vorbereiten +* europäischer Fokus (DSGVO/GoBD) + +Bitte analysiere die bereitgestellten Dateien kritisch. + +Wichtige Fragen: + +1. Welche Architekturentscheidungen sind gefährlich? +2. Welche Teile werden später schwer skalierbar? +3. Welche Module sind falsch getrennt? +4. Wo droht ein zukünftiger Monolith? +5. Welche Datenobjekte fehlen? +6. Welche Sicherheitsprobleme erkennst du? +7. Welche Probleme siehst du bei Mandantenfähigkeit? +8. Welche API-Strategien sind problematisch? +9. Welche V1-Funktionen sind zu groß gedacht? +10. Welche Funktionen fehlen für eine produktive V1? +11. Welche Integrationen sind architektonisch riskant? +12. Welche Entscheidungen sollten JETZT getroffen werden, bevor Entwicklung beginnt? +13. Welche Teile wirken unnötig kompliziert? +14. Welche Teile wirken noch nicht klar genug definiert? +15. Welche Bereiche würden später hohe Refactoring-Kosten verursachen? + +Wichtig: + +* Sei kritisch. +* Stelle Annahmen infrage. +* Suche aktiv nach Problemen. +* Denke wie ein erfahrener SaaS-/Platform-Architekt. +* Denke langfristig. +* Vermeide oberflächliches Lob. + +Das Ziel ist Architekturqualität, nicht Bestätigung. + + + diff --git a/prompts/product-review-prompt.md b/prompts/product-review-prompt.md new file mode 100644 index 0000000..039b770 --- /dev/null +++ b/prompts/product-review-prompt.md @@ -0,0 +1,18 @@ +# Prompt: Produktreview + +Bitte prüfe die Produktidee für Hosting-Backoffice kritisch. + +Vision: +Ein europäisches Hosting-Backoffice für kleine Anbieter, das Ordnung in Kunden, Hostingpakete, Domains, Rechnungen und Support bringt – professionell, verständlich und nutzbar ab dem ersten Kunden. + +Zielgruppe: +Kleine Hostinganbieter, Webagenturen, Freelancer und IT-Dienstleister mit 1–500 Kunden. + +Bitte bewerte: +- Positionierung +- Zielgruppe +- USP +- V1-Scope +- Risiken +- fehlende Funktionen +- mögliche Überforderung diff --git a/prompts/security-review-prompt.md b/prompts/security-review-prompt.md new file mode 100644 index 0000000..91f7044 --- /dev/null +++ b/prompts/security-review-prompt.md @@ -0,0 +1,14 @@ +# Prompt: Security Review + +Bitte prüfe das Konzept für Hosting-Backoffice aus Sicherheits- und Datenschutzsicht. + +Fokus: +- Rechtekonzept +- API-Sicherheit +- Mandantenfähigkeit +- Audit-Logs +- externe Integrationen +- Dokumentenarchiv +- KI-Funktionen + +Bitte liefere konkrete Risiken und empfohlene Gegenmaßnahmen. diff --git a/reviews/chatgpt-consolidation-20260518-042851.md b/reviews/chatgpt-consolidation-20260518-042851.md new file mode 100644 index 0000000..5015b21 --- /dev/null +++ b/reviews/chatgpt-consolidation-20260518-042851.md @@ -0,0 +1,472 @@ +## 1. Zusammenfassung + +Claude benennt valide Architektur-Risiken. Für das Projekt werden daraus keine neuen Produktziele abgeleitet, sondern konkrete Korrekturen an Datenmodell, Security-Dokumentation, ADRs und Betriebsregeln. + +Kernentscheidungen: + +- `tenant_id` wird der einzige technische Mandanten-Isolationsschlüssel. +- `organisation_id` wird nicht mehr für Tenant-Isolation verwendet. +- Multi-Tenancy wird nicht „halb vorbereitet“, sondern technisch sauber in V1 angelegt. +- Secrets werden nicht im Domainmodell gespeichert, sondern nur referenziert. +- Audit-Hash-Chain wird nicht als manipulationssichere Security-Maßnahme verkauft. +- DLQ, Dokumente, Rollen und Reconciliation erhalten konkrete Regeln. +- Bounded Contexts werden als Modul-/Schema-Grenzen dokumentiert, keine Microservice-Aufspaltung. + +--- + +## 2. Übernommene Punkte + +### Tenant-Isolation + +Übernehmen. + +Änderung: + +- `tenant_id` ist Pflichtfeld auf allen mandantenbezogenen Tabellen. +- `organisation_id` wird aus der technischen Isolation entfernt. +- Falls Organisation benötigt wird, dann nur fachlich, z. B. als `customer_organisation_id`. +- PostgreSQL Row-Level-Security wird vorgesehen. +- Tenant-Kontext wird pro Request/Job explizit gesetzt. +- Queries ohne Tenant-Kontext müssen fehlschlagen. + +Konkrete Modellregel: + +```text +tenant_id UUID NOT NULL REFERENCES tenants(id) +``` + +Für mandantenbezogene Relationen: + +```text +FOREIGN KEY (tenant_id, customer_id) +REFERENCES customers(tenant_id, id) +``` + +--- + +### Secrets-Management + +Übernehmen. + +Änderung: + +- Keine API-Keys, Passwörter oder Tokens in Fachentitäten. +- Domainmodelle speichern nur `secret_ref`. +- Secret-Service wird als technischer Baustein dokumentiert. +- Encryption-at-rest wird verpflichtend für Secret-Storage. +- Zugriff auf Secrets nur über Service-Layer, nicht über direkte DB-Reads. + +Beispiel: + +```text +registrar_accounts.secret_ref +``` + +statt: + +```text +registrar_accounts.api_key +registrar_accounts.password +``` + +--- + +### Audit-Log + +Teilweise übernehmen. + +Änderung: + +- Hash-Chain wird nicht als Schutz gegen DB-Admin-Manipulation beschrieben. +- Audit-Log bleibt append-only auf Anwendungsebene. +- Integritätsprüfung wird klar abgegrenzt. +- Optional: periodischer Export/Checkpoint in externes System. + +ADR 0014 muss entsprechend korrigiert werden. + +--- + +### Dead Letter Queue + +Übernehmen. + +Änderung: + +- DLQ erhält Retention-Regeln. +- PII in Fehlerpayloads wird vermieden oder redaktiert. +- Maximale Aufbewahrung wird festgelegt. +- Reprocessing und Löschung werden beschrieben. + +Vorschlag: + +```text +DLQ default retention: 30 Tage +DLQ max retention: 90 Tage +PII payloads: nicht speichern oder redaktieren +``` + +--- + +### Bounded Contexts + +Übernehmen, aber pragmatisch. + +Änderung: + +- Keine sofortige Service-Aufteilung. +- Einführung klarer Modulgrenzen im Monolithen. +- Datenmodell wird nach fachlichen Bereichen gegliedert. + +Kontexte: + +- Identity & Access +- CRM +- Billing +- Provisioning +- Registry +- Support +- Documents +- Audit + +--- + +### Reconciliation + +Teilweise übernehmen. + +Änderung: + +- Kein vollständiges Event-Sourcing für V1. +- Stattdessen Operation-/Job-Historie und Status-Snapshots. +- Reconciliation basiert auf: + - gewünschtem Zustand + - aktuellem externem Zustand + - letzter Operation + - Fehlerhistorie + +Benötigte Tabellen/Modelle: + +```text +provisioning_operations +external_resource_snapshots +job_runs +job_attempts +``` + +--- + +### Rollen und Scopes + +Übernehmen. + +Änderung: + +- Rollen werden nicht nur benannt, sondern mit konkreten Berechtigungen dokumentiert. +- Zugriff auf Secrets, Rechnungen, Serverdaten und Kundendaten wird explizit geregelt. + +Beispielrollen: + +- Owner +- Admin +- Billing +- Support +- Provisioning Operator +- Read-only Auditor + +--- + +### Dokument-Storage + +Übernehmen. + +Änderung: + +- Dokumente speichern keine Datei direkt im Datenmodell. +- Dokumente referenzieren Object Storage. +- Tenant-Isolation über Bucket/Prefix plus DB-Zugriffskontrolle. +- Löschung, Archivierung und Legal Hold werden dokumentiert. + +Beispiel: + +```text +documents.object_key +documents.storage_provider +documents.checksum_sha256 +documents.retention_until +documents.legal_hold +documents.deleted_at +``` + +--- + +## 3. Abgelehnte oder verschobene Punkte + +### Vollständiges Event-Sourcing + +Verschoben. + +Begründung: + +- Für V1 nicht erforderlich. +- Reconciliation kann über Operation-Historie, Job-Historie und Snapshots umgesetzt werden. + +--- + +### Microservice-Aufteilung nach Bounded Contexts + +Abgelehnt für V1. + +Begründung: + +- Zu hoher Betriebs- und Integrationsaufwand. +- Modulgrenzen im Monolithen reichen aktuell aus. + +--- + +### Audit-Hash-Chain als Manipulationsschutz + +Abgelehnt. + +Änderung: + +- Hash-Chain darf maximal als Integritätsindikator beschrieben werden. +- Kein Sicherheitsversprechen gegen privilegierte DB-Manipulation. + +--- + +### Parallele Nutzung von `organisation_id` und `tenant_id` + +Abgelehnt. + +Änderung: + +- Nur `tenant_id` ist technischer Scope. +- Organisation ist, falls benötigt, ein CRM-/Kundenkonzept. + +--- + +### Single-Tenant V1 ohne Tenant-Schutz + +Abgelehnt. + +Änderung: + +- V1 darf fachlich nur einen aktiven Tenant haben. +- Technisch wird Tenant-Isolation trotzdem sauber eingebaut. + +--- + +## 4. Neue/geänderte Dateien + +### Geändert + +#### `docs/data-model-v0.2.md` + +Änderungen: + +- `organisation_id` aus technischer Mandanten-Isolation entfernen. +- `tenant_id` als verbindlichen Scope definieren. +- Tenant-FK-Regeln ergänzen. +- Tabellen nach Bounded Contexts gruppieren. +- Secret-Felder durch `secret_ref` ersetzen. +- Dokumentmodell um Storage-Metadaten erweitern. +- Operation-/Job-Historie ergänzen. + +--- + +#### `docs/security.md` + +Änderungen: + +- Tenant-Isolation konkretisieren. +- Secrets-Management konkretisieren. +- RBAC/Scopes verlinken. +- RLS und Tenant-Kontext als Pflichtmechanismus aufnehmen. + +--- + +#### `docs/adr/0014-audit-log.md` + +Änderungen: + +- Hash-Chain nicht mehr als manipulationssicher beschreiben. +- Algorithmus konkretisieren, falls beibehalten. +- Optionalen externen Checkpoint/Export dokumentieren. +- Grenzen des Mechanismus explizit nennen. + +--- + +#### `docs/adr/0017-jobs-reconciliation-dlq.md` + +Änderungen: + +- DLQ-Retention ergänzen. +- PII-Regeln ergänzen. +- Reprocessing-Regeln ergänzen. +- Reconciliation-Datenbasis ergänzen. + +--- + +### Neu + +#### `docs/architecture/tenant-isolation.md` + +Inhalt: + +- `tenant_id` als einziger technischer Mandantenschlüssel +- Request-/Job-Tenant-Kontext +- Fail-closed-Verhalten +- RLS-Grundregeln +- Cross-Tenant-Zugriffe verboten +- Composite FK-Regeln + +--- + +#### `docs/architecture/bounded-contexts.md` + +Inhalt: + +- Modulgrenzen +- erlaubte Abhängigkeiten +- Besitz von Tabellen/Entitäten +- keine direkten Fremdzugriffe zwischen Kontexten ohne definierte Schnittstelle + +--- + +#### `docs/security/secrets-management.md` + +Inhalt: + +- Secret-Service-Konzept +- `secret_ref` +- keine Klartext-Secrets in DB +- Rotation +- Zugriffskontrolle +- Auditierung von Secret-Zugriffen + +--- + +#### `docs/security/rbac-matrix.md` + +Inhalt: + +| Bereich | Owner | Admin | Billing | Support | Provisioning | Auditor | +|---|---:|---:|---:|---:|---:|---:| +| Kunden lesen | ja | ja | ja | ja | ja | ja | +| Kunden ändern | ja | ja | nein | eingeschränkt | nein | nein | +| Rechnungen lesen | ja | ja | ja | nein | nein | ja | +| Rechnungen ändern | ja | ja | ja | nein | nein | nein | +| Serverdaten lesen | ja | ja | nein | eingeschränkt | ja | ja | +| Server ändern | ja | ja | nein | nein | ja | nein | +| Secrets lesen | nein | nein | nein | nein | nein | nein | +| Secret nutzen | ja | ja | nein | nein | system | nein | + +--- + +#### `docs/storage/document-storage.md` + +Inhalt: + +- Object-Storage-Strategie +- Tenant-Isolation per Prefix/Bucket +- Checksums +- Archivierung +- Löschanfragen +- Legal Hold +- Zugriffskontrolle + +--- + +#### `docs/operations/dlq-retention.md` + +Inhalt: + +- DLQ-Retention +- PII-Regeln +- Reprocessing +- manuelle Freigabe +- endgültige Löschung +- Monitoring + +--- + +#### `docs/operations/reconciliation.md` + +Inhalt: + +- gewünschter Zustand +- externer Ist-Zustand +- Operation-Historie +- Snapshot-Modell +- Konfliktbehandlung +- Retry-Strategie + +--- + +#### `db/policies/tenant_rls.sql` + +Inhalt: + +- PostgreSQL RLS-Grundstruktur +- Policy pro mandantenbezogener Tabelle +- Nutzung von `current_setting('app.tenant_id')` +- Fail-closed bei fehlendem Tenant-Kontext + +Beispiel: + +```sql +ALTER TABLE customers ENABLE ROW LEVEL SECURITY; + +CREATE POLICY tenant_isolation_customers +ON customers +USING ( + tenant_id = current_setting('app.tenant_id')::uuid +); +``` + +--- + +#### `db/migrations/xxxx_add_tenant_scope.sql` + +Inhalt: + +- `tenants`-Tabelle +- `tenant_id` auf mandantenbezogenen Tabellen +- NOT NULL Constraints +- Composite Foreign Keys +- Indizes auf `(tenant_id, id)` + +--- + +## 5. Konkrete nächste Schritte + +1. `docs/data-model-v0.2.md` anpassen: + - `tenant_id` festlegen + - `organisation_id` aus Isolation entfernen + - Secret-Felder durch `secret_ref` ersetzen + +2. `docs/architecture/tenant-isolation.md` neu erstellen. + +3. `db/migrations/xxxx_add_tenant_scope.sql` vorbereiten: + - `tenants` + - `tenant_id` + - Constraints + - Indizes + +4. `db/policies/tenant_rls.sql` erstellen. + +5. `docs/security/secrets-management.md` erstellen. + +6. `docs/security/rbac-matrix.md` erstellen. + +7. ADR 0014 überarbeiten: + - keine falsche Sicherheitsbehauptung zur Hash-Chain + +8. ADR 0017 überarbeiten: + - DLQ-Retention + - PII-Regeln + - Reconciliation-Datenbasis + +9. `docs/storage/document-storage.md` erstellen. + +10. `docs/architecture/bounded-contexts.md` erstellen und Datenmodell danach gruppieren. \ No newline at end of file diff --git a/reviews/claude-critical-risks.md b/reviews/claude-critical-risks.md new file mode 100644 index 0000000..504b921 --- /dev/null +++ b/reviews/claude-critical-risks.md @@ -0,0 +1,312 @@ +# Kritische Risiken und Refactoring-Gefahren + +**Stand:** 15. Mai 2026 +**Reviewer:** Claude +**Bezug:** Hosting-Backoffice v0.1 (vollständiger Basisbestand) + +Jedes Risiko ist mit Schweregrad, Zeitpunkt und konkreter Empfehlung markiert. + +**Legende:** +- Schweregrad: `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` +- Zeitpunkt: `NOW` (vor Codebeginn) / `V1` / `V2` / `V3` / `LATER` + +--- + +## R-01 — Mandantenfähigkeit ist Absichtserklärung, kein Design + +- **Schweregrad:** `CRITICAL` +- **Zeitpunkt:** `NOW` +- **Problem:** Die Multi-Tenancy-Strategie listet Ziele, keinen Mechanismus. V1 läuft als Single-Tenant mit zwei ungeklärten ID-Spalten (`tenant_id`, `organisation_id`). Wenn V1 ohne Tenant-Scope-Enforcement deployt wird, ist V2/V3-Reseller-Fähigkeit ein Komplett-Refactor jeder Query, Policy, Job-Payload, Cache-Key und Webhook-Definition. +- **Empfehlung:** Tenancy-Modell jetzt entscheiden und in ADR festschreiben. Vorschlag: Shared Database, `tenant_id`-Scope, Postgres Row-Level Security als zweite Verteidigungsschicht. Eloquent Global Scope von Tag 1 auf allen mandantenscoped Modellen. Statische Analyse oder Runtime-Assertion in CI gegen ungescopte Queries. `organisation_id` vs. `tenant_id` mit ER-Modell klären oder eine der beiden Spalten streichen. + +--- + +## R-02 — Anbieterlogik im Core-Datenmodell bricht das eigene Adapter-Pattern + +- **Schweregrad:** `CRITICAL` +- **Zeitpunkt:** `NOW` +- **Problem:** `Server.KeyHelp-Referenz` und `Rechnung.externes System` stehen im Core-Datenmodell. Das widerspricht direkt dem Integration-Adapter-Pattern, das „Core kennt keine direkte Anbieterlogik" als Grundprinzip formuliert. Sobald V1 mit dieser Schema-Form deployt wird, ist das Adapter-Pattern in der Praxis tot, und jedes neue Hostingpanel braucht Core-Schema-Änderungen. +- **Empfehlung:** Vor dem ersten Migration-File ein generisches External-Reference-Pattern einführen, z. B. Tabelle `external_references(id, owner_type, owner_id, adapter_id, external_id, metadata, last_synced_at)`. Im Core nur diese Tabelle, keine anbieter-spezifischen Felder. + +--- + +## R-03 — Daten im Core, Logik in Modulen (Billing-Anti-Pattern) + +- **Schweregrad:** `CRITICAL` +- **Zeitpunkt:** `NOW` +- **Problem:** `Rechnung` und `Zahlung` sind im Core-Datenmodell. Billing-Logik ist als Integrationsmodul gedacht (Lexware, Invoice Ninja). Konsequenz: Module schreiben in Core-Tabellen, kennen das Core-Schema, jede Schema-Änderung im Core bricht potenziell mehrere Module. Genau die Konstruktion, in der „modularer Aufbau" zum erweiterten Monolithen wird. +- **Empfehlung:** Billing als eigene Bounded-Context-Domäne (Service-Modul) etablieren. Core kennt höchstens `InvoiceReference` mit Adapter-ID und externer ID, nicht aber `Rechnung.Betrag`. Eigenes Datenmodell pro Modul, Kommunikation per definierten Service-Contract. + +--- + +## R-04 — Modulstruktur und Modul-Dokumente widersprechen sich + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `NOW` +- **Problem:** `module-structure-v0.1.md` listet weder Billing noch Customer Portal, obwohl beide eigene Modul-Beschreibungen haben. KeyHelp und Registrar sind als Modul-Doks vorhanden – einer ist Integrationsmodul, der andere möglicherweise eine Mischform. Solange diese drei verschiedenen „Wahrheiten" parallel existieren, gibt es kein gemeinsames Architekturverständnis. +- **Empfehlung:** Modulstruktur als alleinige Wahrheit etablieren. Jedes Modul-Dokument muss in der Modul-Struktur gelistet sein, oder es existiert nicht. Inkonsistenzen vor Codebeginn beheben. + +--- + +## R-05 — Secrets-Management vollständig undefiniert + +- **Schweregrad:** `CRITICAL` +- **Zeitpunkt:** `NOW` +- **Problem:** `Registrar-Account.Zugangsdaten/API-Referenzen` impliziert Credentials im Datenmodell. Im gesamten Bestand findet sich kein Wort zu Vault, Verschlüsselung, Key Rotation, KMS, HSM oder Mandanten-Isolation der Schlüssel. Bei kompromittierter DB hätte ein Angreifer Zugriff auf Registrar-Accounts aller Mandanten – das wäre ein Vorfall mit Branchenrelevanz. +- **Empfehlung:** Externes Secret-Management (HashiCorp Vault, AWS Secrets Manager, Bitwarden Secrets Manager) oder mindestens Envelope-Encryption mit pro-Mandant abgeleiteten Schlüsseln und externem KMS. Datenmodell darf keine Credentials enthalten, nur Referenzen in den Vault. Vor V1-Codebeginn entscheiden. + +--- + +## R-06 — Core ist zu groß, Monolith-Pfad voraussehbar + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `NOW` +- **Problem:** Core enthält 13 Bereiche, davon mindestens 6 mit eigener Geschäftslogik (Domains, Hostingpakete, Server, Dokumente, Notifications, Produkte). Diese Konstellation produziert einen Bounded Context für die gesamte Anwendung und macht den Modul-Ansatz architektonisch wirkungslos. +- **Empfehlung:** Core auf Identity, RBAC, Audit, Settings, Module-Registry, Event-Routing, Tenant-Scope reduzieren. Domains, Hostingpakete, Server, Dokumente, Notifications-Channels in eigene Service-Module auslagern. Adapter-Pattern und Modul-Contract als verbindliche Grenze. + +--- + +## R-07 — GoBD-Verantwortlichkeit nicht entschieden + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `V1` +- **Problem:** `Rechnung.externes System` impliziert, dass Lexware/Invoice Ninja der Beleg-Originalspeicher ist. Die GoBD-Archive-Strategie sagt aber gleichzeitig „PDFs archivieren, Hashes speichern, Audit-Logs schreiben" – das klingt nach lokalem Originalspeicher. Wenn Hosting-Backoffice der Originalspeicher ist, gelten harte GoBD-Anforderungen (unveränderbare Belege, lückenlose Nummernkreise pro Mandant, 10-Jahres-Retention, Z3-Export). Aktuell ist das nicht entschieden. +- **Empfehlung:** Klärungs-ADR. Empfehlung: Lexware/Invoice Ninja als Original, Hosting-Backoffice als Referenz-/Spiegel-System mit Archivkopie und Hash. Audit-Logs intern, aber keine GoBD-Originalrolle. + +--- + +## R-08 — DSGVO-Löschung vs. GoBD-Retention nicht modelliert + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `V1` +- **Problem:** Endkunde verlangt Löschung nach DSGVO Art. 17, gleichzeitig müssen Rechnungsbelege 10 Jahre aufbewahrt werden. Diese Spannung muss technisch abgebildet sein. Im aktuellen Datenmodell gibt es weder Soft-Delete-Modell noch Pseudonymisierungs-Strategie noch Tombstone-Mechanismus. +- **Empfehlung:** Tombstone- und Pseudonymisierungs-Modell entwerfen. Pflicht: Trennung von Personen-Stammdaten (löschbar/pseudonymisierbar) und Beleg-Inhalt (retentionspflichtig). Konkrete Felder definieren, was bei „Löschung" mit der Person passiert (z. B. `Anonymized` als Name). + +--- + +## R-09 — API-Auth-Strategie unentschieden + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `NOW` +- **Problem:** „Tokenbasiert, später OAuth/Sanctum möglich" mischt Konzeptebenen. Das WordPress-Plugin und das Customer Portal können nicht entwickelt werden, bevor entschieden ist, welcher Auth-Mechanismus für welchen Client-Typ gilt. +- **Empfehlung:** ADR. Vorschlag für V1: Sanctum Personal Access Tokens (M2M, einfache Clients) plus Sanctum SPA-Mode (eigenes Frontend, falls vorhanden). V2: Passport/OAuth2 für WordPress-Plugin und Drittanbieter-Apps. + +--- + +## R-10 — Datenbankwahl offen + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `NOW` +- **Problem:** „MariaDB oder PostgreSQL" als Nicht-Entscheidung. Postgres bietet Row-Level Security (relevant für Tenancy als Defense-in-Depth), JSONB mit Indizes, transaktionales DDL, partielle Indizes. MariaDB nicht in gleichem Umfang. „Später entscheiden" ist faktisch eine Festlegung auf den kleinsten gemeinsamen Nenner. +- **Empfehlung:** ADR. Vorschlag: PostgreSQL 15+, mit expliziter Begründung an Tenancy-, Audit-, JSON- und Performance-Anforderungen. + +--- + +## R-11 — KI-Modul in V1 birgt DSGVO-Sprengstoff + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `NOW` (Scope-Entscheidung) / `V2` (technisch) +- **Problem:** KI-Funktionen verarbeiten potenziell personenbezogene Support-Ticket-Inhalte über US-Provider, was Auftragsverarbeitungsvertrag, SCC, Drittlandtransfer-Risikobewertung, Subprozessor-Transparenz und Endkunden-Information erfordert. Für V1 (3–5 Pilotkunden, „Ordnung schaffen") ist das Aufwand ohne Geschäftswert. +- **Empfehlung:** KI-Modul aus V1 entfernen, in V2 wieder aufnehmen. Bis dahin: Subprozessor-Strategie, DPA-Vorlage, Datenklassifikation und Mensch-im-Loop-Konzept ausarbeiten. + +--- + +## R-12 — SEPA-Lastschrift ohne SEPA-Modell + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V1` +- **Problem:** Payment Policy listet Lastschrift als V1-Zahlungsart. SEPA-Lastschrift erfordert Mandate (UMR, Mandatsdatum, Mandatstext), Pre-Notification (mind. 1 Tag), IBAN-Speicherung (personenbezogen + sicherheitsrelevant), Mandatsänderungs-Historie. Davon ist nichts modelliert. +- **Empfehlung:** Entweder Lastschrift aus V1 entfernen, oder SEPA-Mandat-Modell vollständig spezifizieren (eigene Tabellen, Statusmaschine, Verschlüsselung der IBAN, Audit-Log). + +--- + +## R-13 — V1-Scope intern widersprüchlich + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `NOW` +- **Problem:** Mehrere Dokumente erzählen unterschiedliche V1-Geschichten: KI in V1 vs. V2, Customer Portal in V1 vs. nicht in MVP, Kundenzahl 1–500 vs. 1–50. Das macht den V1-Scope unentscheidbar und damit das Erfolgsversprechen unprüfbar. +- **Empfehlung:** V1-Scope-Liste als einzelne Quelle der Wahrheit etablieren. Empfehlung: KI raus, Customer Portal raus oder mit reduziertem Umfang, Kundenzahl auf 1–50 festgelegt. Alle Dokumente daran ausrichten. + +--- + +## R-14 — Audit-Log-Unveränderbarkeit als Wunsch, kein Mechanismus + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V1` +- **Problem:** „Logs dürfen nicht manipulierbar sein" steht als Anforderung, aber kein Mechanismus ist beschrieben. Eine normale DB-Tabelle ist manipulierbar. +- **Empfehlung:** Mindestens Append-only-Tabelle ohne UPDATE/DELETE-Berechtigung des App-Users, Hash-Chain der Einträge, regelmäßiger Export in WORM-Storage oder externes Audit-Sink. ADR. + +--- + +## R-15 — Tenant-Offboarding und Datenexport nicht definiert + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `V2` +- **Problem:** Wenn ein Mandant das System verlässt, muss er DSGVO-konform seine Daten erhalten (Datenportabilität) und der Plattformbetreiber muss löschen. Kein Konzept im Bestand. +- **Empfehlung:** Tenant-Lifecycle-Domäne entwerfen. Export-Format: maschinenlesbar (JSON Lines, oder pro-Tenant DB-Dump bei DB-per-Tenant-Modell). Aufbewahrungspflichten der GoBD beachten. + +--- + +## R-16 — Steuer-/MwSt-Logik komplett fehlend + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `V1` +- **Problem:** Im gesamten Bestand kein Wort zu MwSt-Sätzen, OSS (One-Stop-Shop für EU-B2C), Reverse Charge B2B EU, oder MwSt-Befreiungen. Eine Rechnungs-Software ohne Steuermodell ist nicht produktiv einsetzbar. +- **Empfehlung:** Minimal-Modell für V1: deutscher Standardfall (19%/7%/0%), B2B/B2C-Flag pro Kunde, Erweiterbarkeit für OSS in V2. ADR + Daten-Modell-Update. + +--- + +## R-17 — Reseller-Hierarchie V3 ohne V1-Vorbereitung + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `NOW` +- **Problem:** V3 verspricht „Resellerstrukturen" und „tiefere Mandantenfähigkeit". Das setzt mindestens dreistufige Hierarchie (Plattform → Reseller → Endkunde) voraus. V1 plant zweistufig oder einstufig (siehe R-01). Ohne saubere Hierarchie-Definition heute wird V3 ein Modellbruch. +- **Empfehlung:** Hierarchie als Datenmodell-Entscheidung heute festlegen (selbst wenn V1 nur eine Ebene aktiv nutzt). ADR. Tabelle `tenants` mit `parent_tenant_id` als Vorbereitung. + +--- + +## R-18 — Fehlerresilienz für Integrationen nicht entworfen + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V1` +- **Problem:** Adapter-Anforderungen sagen „Fehlerbehandlung" – aber Retry-Strategie, Backoff, Circuit Breaker, Dead-Letter-Queue, Reconciliation bei inkonsistentem Zustand sind nicht beschrieben. Bei Domain-Renewal kann ein nicht behandelter Adapter-Fehler einen geschäftskritischen Datenverlust bedeuten. +- **Empfehlung:** Standardpattern für alle Adapter: Retry mit exponentiellem Backoff, Circuit Breaker, Dead Letter, Reconciliation-Job nightly. Job-Status sichtbar im UI. + +--- + +## R-19 — API-Versionierungsstrategie unvollständig + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V1` +- **Problem:** Nur Pfad-Versionierung (`/api/v1/`) ohne Deprecation/Sunset/Compatibility-Strategie. Bei API-first-Anspruch zu wenig. +- **Empfehlung:** ADR mit klaren Regeln: Breaking Changes nur über neue Major-Version, Minor-Changes additiv, Deprecation-Header (`Deprecation`, `Sunset`), Mindest-Support-Zeitraum für ältere Versionen. + +--- + +## R-20 — Nummernkreise pro Mandant ohne Mechanismus + +- **Schweregrad:** `HIGH` +- **Zeitpunkt:** `V1` +- **Problem:** Rechnungsnummern müssen lückenlos sein und pro Mandant separat. Kunden-, Vertrags-, Rechnungsnummern: pro Mandant? Global? Konfigurierbar? Aktuell nicht modelliert. +- **Empfehlung:** Dedicate Sequence-Tabelle pro Mandant und pro Nummernkreis. Atomic-Increment mit DB-Lock. Konfigurierbares Format (Präfix, Padding, Reset-Verhalten). Pflicht für GoBD-Konformität. + +--- + +## R-21 — Personen-/Adressmodell als undifferenziertes Bündel + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `NOW` +- **Problem:** `Kunde` enthält „Stammdaten + Ansprechpartner + Kontaktdaten" als monolithisches Objekt. Klassisches Anti-Pattern. Erschwert DSGVO-Auskunft/Löschung, B2B-Modell, Mehrfach-Ansprechpartner, getrennte Rechnungs-/Postanschriften. +- **Empfehlung:** Trennung in `Party` (Person oder Organisation) + `Address` (mit Verwendungszweck: Rechnung/Post/Rechtssitz) + `ContactPoint` (Mail/Tel/etc. mit Verwendungszweck). N:M zwischen Customer und Party für Ansprechpartner. + +--- + +## R-22 — WordPress-Plugin als zweite Sicherheitsdomäne + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V2` +- **Problem:** Plugin ist API-Client mit eigener Session-Domäne, eigenem Update-Lifecycle, eigener Plugin-Ökosystem-Risikofläche. Wenn die WP-Site kompromittiert ist, sind die API-Tokens des Plugins gefährdet. Aktuell ist nicht definiert, welche Scopes das Plugin erhält und wie kompromittierte Tokens rotiert werden. +- **Empfehlung:** Plugin nur mit minimal-Scope-Token. Token-Revocation aus Admin-UI. Lifetime begrenzen. Audit-Log bei jeder Plugin-API-Nutzung. Strategie für Sandbox-Tests bei kompromittiertem WP-Setup. + +--- + +## R-23 — Frontend-Strategie offen widerspricht API-first-Anspruch + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `NOW` +- **Problem:** „Blade oder später Vue/Nuxt" lässt eine fundamentale Architekturentscheidung offen. Klassischer Laravel-Monolith mit angeflanschter API ist eine andere Architekturklasse als ein API-first-System mit echtem SPA-Client. +- **Empfehlung:** ADR. Entweder Blade-als-API-Konsument (Blade-Views rufen interne API auf, kein direkter DB-Zugriff aus Views) oder Vue-/Nuxt-SPA. Nicht „später". + +--- + +## R-24 — BFSG / Barrierefreiheit für Customer Portal + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V1` (falls Portal in V1) / `V2` +- **Problem:** Seit 28. Juni 2025 sind in der EU kommerzielle digitale Dienste an Verbraucher barrierefrei zu gestalten (BFSG, Umsetzung der EU-Richtlinie 2019/882). Customer Portal fällt darunter. +- **Empfehlung:** UI-Komponenten und Frontend-Stack barrierefrei gestalten (WCAG 2.1 AA als Ziel). Wenn Portal aus V1 raus ist (R-13), entschärft sich das auf V2. + +--- + +## R-25 — Modul-Lifecycle (Deinstallation, Datenreferenzen) ungeklärt + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V1` +- **Problem:** Module sollen aktivierbar/deaktivierbar sein. Was passiert mit referenzierten Daten in anderen Modulen, wenn ein Modul deinstalliert wird? Was passiert bei Re-Installation? Diese Semantik ist nirgendwo beschrieben. +- **Empfehlung:** Modul-Lifecycle definieren: aktivieren / deaktivieren (Daten bleiben) / deinstallieren (Daten archivieren, optional löschen). Dependencies zwischen Modulen explizit deklarieren. Migrations-Strategie bei Re-Installation. + +--- + +## R-26 — Logging-/Audit-Sink-Architektur unspezifiziert + +- **Schweregrad:** `MEDIUM` +- **Zeitpunkt:** `V1` +- **Problem:** Logging-Strategie sagt was geloggt werden soll, aber nicht wohin oder wie. App-Logs vs. Audit-Logs sind getrennt, aber Speicherort, Retention, Mandantenscope, Integritätsschutz fehlen. +- **Empfehlung:** Drei getrennte Senken: App-Logs (lokal, kurzfristig, optional externer Aggregator wie Loki/Sentry), Audit-Logs (DB-Append-only, langfristig, pro Mandant), Security-Logs (Login, Auth-Fehler, Admin-Aktionen, separat). + +--- + +## R-27 — „Vorbereitende" Felder ohne Verwendung in V1 + +- **Schweregrad:** `LOW` +- **Zeitpunkt:** `NOW` +- **Problem:** Mehrfach „… später möglich" als Feld-Anmerkung (Server.Rollen später, Hostingpaket.Ressourcen später, Gebührenregeln später). Erfahrung: solche Felder werden entweder nie genutzt oder mit Bedeutung versehen, die nicht zur ursprünglichen Form passt. +- **Empfehlung:** „Später"-Felder aus dem v0.1-Datenmodell entfernen. Wenn ein Feld V1 nicht braucht, wird es V1 nicht migriert. Bei Bedarf später eigene Migration. + +--- + +## R-28 — Mehrere parallele Single Sources of Truth + +- **Schweregrad:** `LOW` (organisatorisch) / `HIGH` (in Konsequenz) +- **Zeitpunkt:** `NOW` +- **Problem:** Strategie-Dokumente, Modul-Dokumente, Roadmap und MVP-Liste enthalten sich widersprechende Aussagen (siehe R-04, R-13). Ohne klare Hierarchie zwischen den Dokumenten wird im Code-Schritt jede Person eine andere Variante implementieren. +- **Empfehlung:** Dokumenthierarchie festlegen: ADRs > Strategie-Dokumente > Modul-Beschreibungen > Roadmap. Konflikte werden in dieser Reihenfolge aufgelöst. Bei Konflikt: ADR ergänzen oder Strategie-Doc aktualisieren, untere Ebenen nachziehen. + +--- + +## Zusammenfassende Priorisierung + +**CRITICAL / NOW** (vor Codebeginn unverzichtbar): +- R-01 Mandantenfähigkeits-Mechanismus +- R-02 Anbieterlogik aus Core entfernen +- R-03 Billing aus Core entfernen +- R-05 Secrets-Management + +**HIGH / NOW** (vor Codebeginn entscheiden): +- R-04 Modulstruktur als einzige Wahrheit +- R-06 Core verkleinern +- R-09 API-Auth-Strategie +- R-10 Datenbank-Engine +- R-11 KI-Scope-Entscheidung +- R-13 V1-Scope vereinheitlichen +- R-17 Reseller-Hierarchie-Vorbereitung +- R-21 Personen-/Adressmodell +- R-23 Frontend-Strategie +- R-28 Dokumenten-Hierarchie + +**HIGH / V1** (muss in V1 enthalten sein): +- R-07 GoBD-Verantwortlichkeit +- R-08 DSGVO-Löschung-Modell +- R-16 Steuer-/MwSt-Logik +- R-20 Nummernkreise + +**MEDIUM / V1**: +- R-12 SEPA-Modell oder raus +- R-14 Audit-Unveränderbarkeit +- R-18 Adapter-Fehlerresilienz +- R-19 API-Versionierung +- R-24 Barrierefreiheit (falls Portal in V1) +- R-25 Modul-Lifecycle +- R-26 Logging-Architektur + +**MEDIUM/HIGH / V2-V3**: +- R-15 Tenant-Offboarding +- R-22 WP-Plugin-Sicherheitsmodell +- R-24 Barrierefreiheit (Portal in V2) + +**LOW / NOW**: +- R-27 Spekulative Felder entfernen + +--- + +Die Gesamtbotschaft: Die Anzahl der CRITICAL/NOW-Punkte (4) ist überschaubar und alle in 2–4 Wochen entscheidungsreif. Die HIGH/NOW-Punkte (10) sind ADR-Material. Wenn diese 14 Punkte vor Codebeginn entschieden sind, hat das Projekt eine sehr gute Ausgangslage. Werden sie nicht entschieden, ist V1 voraussichtlich produktiv nutzbar, aber V2/V3 wird teurer als V1 selbst. diff --git a/reviews/claude-open-questions.md b/reviews/claude-open-questions.md new file mode 100644 index 0000000..dbece85 --- /dev/null +++ b/reviews/claude-open-questions.md @@ -0,0 +1,168 @@ +# Offene Fragen vor Entwicklungsbeginn + +**Stand:** 15. Mai 2026 +**Reviewer:** Claude +**Bezug:** Hosting-Backoffice v0.1 (vollständiger Basisbestand) + +Diese Fragen müssen vor Beginn der V1-Implementierung beantwortet sein. Sie sind nach Themenbereich gruppiert. Innerhalb jedes Bereichs sind sie nach Dringlichkeit geordnet. + +--- + +## 1. Mandantenfähigkeit + +1. Welches Tenancy-Modell gilt für V1: Shared Database mit `tenant_id`-Scope, Schema-pro-Tenant, oder Database-pro-Tenant? +2. Was bedeutet `organisation_id` zusätzlich zu `tenant_id`? Sind beide Synonyme (eines streichen) oder Hierarchieebenen (dann mit ER-Modell zeigen)? +3. Wie wird Tenant-Isolation technisch erzwungen? Eloquent Global Scope, Policy-Layer, Row-Level Security in Postgres, Connection-Switching, oder Kombination? +4. Wie viele Subjektebenen hat das Berechtigungsmodell? Plattformbetreiber → Mandant → Endkunde, oder mit Reseller-Zwischenebene? +5. Wie sieht der Tenant-Lifecycle aus: Provisioning, Suspend, Termination, Datenexport, Offboarding? +6. Wie wird Cross-Tenant-Datenzugriff für Plattform-Admins technisch geregelt (Impersonation, Read-only-Bypass, Audit-Pflicht)? +7. Wie wird beim Wechsel von V1 (Single-Tenant) zu V2/V3 (Multi-Tenant) der erste Mandant migriert? +8. Gibt es Cross-Tenant-Ressourcen (gemeinsame Templates, Knowledge Base, Module Registry), und wie sind sie modelliert? + +--- + +## 2. Datenmodell + +1. Wie sieht das vollständige ER-Modell mit Beziehungen und Kardinalitäten aus? +2. Welche Statusmaschinen existieren für Vertrag, Domain, Hostingpaket, Ticket, Rechnung, und welche Übergänge sind erlaubt? +3. Wie werden Nummernkreise pro Mandant verwaltet (lückenlos, GoBD-konform, separat für Kunde/Vertrag/Rechnung)? +4. Wird `Kunde` in Party/Address/ContactPoint aufgespalten, oder als monolithisches Objekt gehalten? +5. Wie wird B2B vs. B2C unterschieden im Datenmodell? +6. Wie wird das Spannungsfeld Soft-Delete / GoBD-Retention / DSGVO-Löschung technisch aufgelöst? Tombstone-Modell mit Pseudonymisierung? +7. Wie werden externe Referenzen modelliert (generisches Pattern statt anbieter-spezifischer Felder im Core)? +8. Wie ist das Audit-Log-Schema, und wie wird Unveränderbarkeit garantiert (Hash-Chain, Append-only-DB, externes Sink)? +9. Werden Verträge versioniert (Vertragsversion, Änderungshistorie)? +10. Wie werden Subscriptions/Laufzeiten modelliert (Vertrag.Laufzeit reicht nicht für Up-/Downgrade und Pro-rata)? +11. Wie wird die Many-to-many-Beziehung Vertrag↔Produkt, Vertrag↔Domain, Vertrag↔Hostingpaket modelliert? +12. Wie ist das Asset-/Dokument-Modell (Hashes, Content-Addressing, Versionen, Storage-Backend-Abstraktion)? + +--- + +## 3. API + +1. Welcher Auth-Stack: Sanctum Personal Access Tokens, Sanctum SPA-Mode, Passport/OAuth2, oder Kombination je Client-Typ? +2. Gibt es OpenAPI 3.x als verbindliche Spec, und ist die Implementierung spec-first? +3. Welches Error-Modell wird verwendet (Problem Details RFC 7807 empfohlen)? +4. Welche Pagination-Strategie: Offset, Cursor, Page? +5. Welche Idempotenz-Strategie für nicht-idempotente Operationen (Domain-Registrierung, Rechnungsanlage)? +6. Wie sieht das Filtering-/Sorting-Schema aus? +7. Wie wird API-Versionierung über `/api/v1/` hinaus gehandhabt (Deprecation, Sunset, Compatibility)? +8. Gibt es Webhooks/Outbound Events? Welches Format, welche Signaturen, welche Delivery-Garantien? +9. Wie werden Rate-Limits pro Mandant skaliert (nicht nur pro IP/Token)? +10. Welche Endpoints sind read-only, welche schreibend, und wie ist das in der Auth-Scope-Logik abgebildet? +11. Wie werden Long-Running-Operations modelliert (Domain-Imports, große Synchronisationen) – synchron, asynchron mit Job-Status-Endpoint, oder via Webhook-Callback? + +--- + +## 4. Core- und Modulgrenzen + +1. Was gehört verbindlich in den Core, was in Service-Module, was in Integrationsmodule? (Aktuelle Liste in `module-structure-v0.1.md` ist unvollständig.) +2. Wo lebt Billing architektonisch? Im Core (Daten heute dort), als Service-Modul, als Adapter-Verbund? +3. Wo lebt das Customer Portal? Service-Modul oder eigenes UI-Modul? +4. Wie ist ein Modul technisch verpackt – Composer-Package, in-app Namespace, Nwidart-Modul, anderes? +5. Wie kommunizieren Module untereinander: Events, Service-Contracts, beides? +6. Wie wird die Modul↔Core-API versioniert? Wie deklariert ein Modul seine Core-API-Mindestversion? +7. Was passiert bei Modul-Deinstallation mit existierenden Datenreferenzen? +8. Wie sind Modul-Migrationen mit Core-Migrationen verzahnt? +9. Wer ist „Owner" jeder Entität (Aggregate Root)? Insbesondere: Wer besitzt `Rechnung` – Billing-Modul oder Core? +10. Wie wird ein generisches External-Reference-Pattern eingeführt, ohne die heutigen anbieter-spezifischen Felder zu zementieren? + +--- + +## 5. Sicherheit und Compliance + +1. Wie werden Registrar-/Provider-API-Credentials gespeichert? Externer Vault, eigenes Verschlüsselungsschema, KMS, HSM? +2. Wer ist GoBD-Verantwortlicher für Rechnungen – Hosting-Backoffice oder das externe Billing-System (Lexware/Invoice Ninja)? +3. Falls Hosting-Backoffice GoBD-Verantwortlicher ist: Welcher Mechanismus garantiert Unveränderbarkeit nach Festschreibung? +4. Wie wird DSGVO-Auskunft pro Endkunde umgesetzt (vollständiger Datenexport in maschinenlesbarer Form)? +5. Wie wird DSGVO-Löschung pro Endkunde umgesetzt, ohne GoBD-Retention zu verletzen (Pseudonymisierung)? +6. Wer ist Auftragsverarbeiter zwischen Plattformbetreiber und Mandant (DPA)? Wie ist die Beziehung Mandant↔Endkunde geregelt? +7. Welche Subprozessoren werden eingesetzt (insbesondere KI-Provider, Mail-Versand, Hosting-Region, Backup-Region)? +8. Wo werden Audit-Logs gespeichert, und wie wird ihre Integrität garantiert? +9. Welche Authentication-Faktoren werden unterstützt (Password, 2FA, WebAuthn)? Pflicht für Admins? +10. Welche Session-Strategie (Lifetime, Idle-Timeout, Refresh, Revocation)? +11. Wie wird Datenresidenz garantiert („europäisch" auf welcher Ebene: Hosting, DB, Backup, Subprozessoren)? +12. Wer haftet bei kompromittierten Registrar-Credentials? Welche technischen Maßnahmen reduzieren das Risiko? +13. Welche AGB-/Widerrufs-Mechanismen werden bei Customer Portal benötigt? +14. Ist BFSG/Barrierefreiheit für das Customer Portal relevant (EU-Verordnung seit 28.06.2025)? + +--- + +## 6. Integrationen + +1. Wie ist der formale Adapter-Contract definiert (Interface-Methoden, Fehler-Schema, Auth, Idempotenz)? +2. Wie werden Adapter-Fehler behandelt (Retry, Backoff, Circuit Breaker, Dead Letter)? +3. Wie wird inkonsistenter Zustand zwischen Core und externem System aufgelöst (Reconciliation, manueller Eingriff)? +4. Wie werden Adapter-Konfigurationen pro Mandant verwaltet (Mandant A nutzt Lexware, Mandant B Invoice Ninja)? +5. Was ist die Bedeutung von „Zahlungsart PayPal/Wero": reine Statusanzeige oder echte Integration? +6. Wie wird SEPA-Lastschrift modelliert (Mandate, UMR, Pre-Notification, IBAN-Verschlüsselung)? +7. Welche Steuer-/MwSt-Logik liegt im System, welche im Billing-Adapter? +8. Was passiert bei Modul-Updates eines Adapters mit nicht-rückwärtskompatiblen Änderungen? +9. Wie wird Mail-Versand (SMTP/Transactional) als eigene Integration gehandhabt? Welcher Anbieter? SPF/DKIM/DMARC-Strategie? + +--- + +## 7. WordPress-Plugin + +1. Welche Auth-Brücke zwischen WordPress und Hosting-Backoffice? OAuth2 Client Credentials? App-Token pro Mandant? Endkunden-Delegation? +2. Speichert das Plugin Daten lokal in WordPress (Sync-Risiko) oder ist es reiner API-Konsument? +3. Wie wird WP-User-Identität auf Backoffice-User-Identität gemappt? +4. Wie ist das Plugin-Update-Lifecycle (eigener Auto-Updater, WordPress.org-Repository, privates Repo)? +5. Welche API-Scopes erhält das Plugin? Was passiert bei kompromittierter WP-Site? +6. Wer ist Mandant aus Sicht der API, wenn ein WP-User klickt – der WP-Site-Betreiber oder der endgültige Endkunde? +7. Welche Caching-/Stale-Data-Strategie hat das Plugin gegenüber der API? + +--- + +## 8. KI-Assistent + +1. Bleibt KI in V1 oder rückt es in V2 (Empfehlung: V2)? +2. Welcher KI-Provider? OpenAI, Anthropic, Mistral, lokal? +3. Wenn US-basierter Provider: DPA, SCC, Drittlandtransfer-Risikobewertung? +4. Welche Daten gehen an die KI – Inhalte oder nur Metadaten? Auf welcher Datenklassifikation basiert das? +5. Wie wird Endkunden-Zustimmung eingeholt, falls Support-Tickets KI-verarbeitet werden? +6. Wie werden Halluzinationen kontrolliert (Mensch-im-Loop, Confidence-Schwellen, Quellen-Citation)? +7. Wer haftet bei falschen KI-Vorschlägen (insbesondere bei Rechnungs-/Vertragsdaten)? +8. Wie wird KI-Output protokolliert und auditiert? + +--- + +## 9. V1-Scope + +1. Endgültige V1-Kundenzahl: 1–50 oder 1–500? (Empfehlung: 1–50, Roadmap-Wert) +2. Kundenportal in V1 oder V2? (Empfehlung: V2) +3. KI-Assistent in V1 oder V2? (Empfehlung: V2) +4. SEPA-Lastschrift in V1 oder V2? (Empfehlung: V2 oder vollständiges Modell jetzt) +5. PayPal/Wero in V1: reine Anzeige oder Integration? +6. Welche Mahnwesen-Funktionalität ist V1-Minimum (Status „überfällig" + manuelle Mail)? +7. Welche Tax-/MwSt-Funktionalität ist V1-Minimum? +8. Welche DSGVO-Funktionen sind V1-Pflicht (Auskunft, Löschung, Datenportabilität)? +9. Welche Backup-/Restore-Funktion ist V1-Pflicht? + +--- + +## 10. Deployment und Operations + +1. Self-hosted-only oder SaaS-Variante geplant? Welcher Mix? +2. Welche PHP-Version? Welche Laravel-Version? +3. Welcher Queue-Driver in V1 (Database, Redis)? +4. Welche Backup-Strategie pro Mandant? +5. Welche Disaster-Recovery-Strategie? +6. Welche Logging-/Monitoring-Tools (Sentry, Loki, Grafana, Telemetry-Provider)? +7. Welcher CI/CD-Stack? +8. Welche Update-/Migration-Strategie auf Kundensystemen (bei Self-hosted)? +9. Welche Update-Strategie für Module unabhängig vom Core? + +--- + +## 11. Lizenz und Geschäftsmodell + +1. Welche Open-Source-Lizenz, oder Closed-Source? +2. Welche kommerzielle Lizenz für Mandanten? +3. Werden Module einzeln verkauft, oder als Bundle? +4. Wer darf Module von Drittanbietern entwickeln und verteilen? +5. Wie wird das Versprechen „europäisch" geschäftlich umgesetzt (Hosting-Region, Subprozessoren, Vertragsrecht)? + +--- + +Diese Liste ist nicht vollständig, aber priorisiert. Die Punkte unter 1, 2, 4 und 5 sind harte Blocker für Codebeginn. Die übrigen können in v0.2 oder begleitend zur ersten Implementierungsphase entschieden werden. diff --git a/reviews/claude-review-20260518-042429.md b/reviews/claude-review-20260518-042429.md new file mode 100644 index 0000000..3a5321a --- /dev/null +++ b/reviews/claude-review-20260518-042429.md @@ -0,0 +1,94 @@ +## Kritische Architekturprobleme + +### 1. Fataler Tenant-Isolation-Fehler + +Das Datenmodell nennt sowohl `organisation_id` als auch `tenant_id`, aber ohne klare Abgrenzung. Dies ist ein **kritischer Designfehler**: + +``` +# Problem in data-model-v0.1.md: +"Von Anfang an vorbereiten: +- organisation_id +- tenant_id" +``` + +**Warum kritisch:** +- Unklare Hierarchie zwischen Organisation und Tenant +- Potenzielle Tenant-Leaks durch falsche Filterung +- Kein explizites Constraint-Modell definiert + +**Lösung erforderlich:** Eine klare Entscheidung - entweder Organisation ODER Tenant, nicht beides halbherzig. + +### 2. Secrets-Management ohne Implementierung + +Das Security-Dokument behauptet: +``` +"Secrets werden nur über einen Secret-Service gelesen/geschrieben" +``` + +Aber: +- Kein Secret-Service definiert +- Registrar-Account hat "Zugangsdaten/API-Referenzen" direkt im Modell +- Keine Encryption-at-Rest-Strategie + +**Risiko:** Passwörter landen im Klartext in der Datenbank. + +### 3. Audit-Log Hash-Chain ist Pseudo-Security + +ADR 0014 schlägt eine Hash-Chain vor, aber: +- Kein Schutz gegen DB-Admin-Manipulation +- Hash-Algorithm nicht spezifiziert +- "V1 bereitet vor" = wird nicht implementiert + +**Problem:** Security-Theater ohne echten Schutz. Ein DB-Admin kann die gesamte Chain neu berechnen. + +### 4. Dead Letter Queue ohne Retention-Strategie + +ADR 0017 fordert Dead Letter Queues, aber: +- Keine maximale Retention definiert +- Potenzielle Speicher-Explosion +- DSGVO-Konflikt bei personenbezogenen Daten in fehlgeschlagenen Jobs + +### 5. Fehlende Core-Domain-Boundaries + +Das Datenmodell mischt alles: +- Billing (Rechnung, Zahlung) +- Provisioning (Server, Hostingpaket) +- CRM (Kunde, Ticket) +- Registry (Domain, Registrar) + +**Problem:** Keine Bounded Contexts = massive Kopplung, unmöglich zu skalieren. + +### 6. Reconciliation ohne Event-Sourcing + +ADR 0017 fordert Reconciliation, aber das Datenmodell hat keine Event-Historie. Wie soll man reconcilen ohne zu wissen, was passiert ist? + +### 7. Security-Rollen ohne Scope-Definition + +"Staff/Support" hat Zugriff auf "operative Daten" - was heißt das konkret? +- Kann Support Passwörter sehen? +- Kann Support Rechnungen ändern? +- Kann Support Server-Zugänge einsehen? + +### 8. Single Point of Failure: tenant_id + +Alles hängt an einem einzigen Feld. Ein fehlerhafter Query-Scope = Datenleck über alle Mandanten. + +**Fehlende Sicherheitsschicht:** +- Kein Row-Level-Security auf DB-Ebene +- Keine Tenant-Context-Validierung +- Kein Fail-Safe-Mechanismus + +### 9. Dokument-Objekt ohne Storage-Strategy + +"Dokument" hat "Hashes" und "Archivinformationen", aber: +- Wo werden Dateien gespeichert? +- Wie wird Tenant-Isolation im Filesystem sichergestellt? +- Was passiert bei Löschanfragen? + +### 10. Keine Migrationsstrategie für Multi-Tenancy + +"V1 arbeitet als Single-Tenant" aber "Struktur vorbereitet" - das ist ein Widerspruch. Entweder man designed multi-tenant von Anfang an oder man plant eine Migration. Beides fehlt. + +## Fazit + +Die Architektur versucht, zu viele Probleme gleichzeitig zu lösen, ohne eines davon richtig zu durchdenken. Kritischster Punkt: Die Tenant-Isolation ist nur oberflächlich geplant und wird mit hoher Wahrscheinlichkeit zu Datenleaks führen. \ No newline at end of file diff --git a/reviews/claude-review-placeholder.md b/reviews/claude-review-placeholder.md new file mode 100644 index 0000000..018fa98 --- /dev/null +++ b/reviews/claude-review-placeholder.md @@ -0,0 +1,9 @@ +# Claude Review Placeholder + +Hier können spätere Claude-Reviews abgelegt werden. + +Empfohlene Nutzung: +- Architektur kritisch prüfen lassen +- Sicherheitsrisiken identifizieren +- V1-Scope hinterfragen +- Datenmodell kommentieren lassen diff --git a/reviews/claude-review-response-map-v0.3.md b/reviews/claude-review-response-map-v0.3.md new file mode 100644 index 0000000..057d4ef --- /dev/null +++ b/reviews/claude-review-response-map-v0.3.md @@ -0,0 +1,123 @@ +# Claude Review Response Map v0.3 + +## Zweck +Dieses Dokument zeigt, welche Claude-Risiken durch dieses Update adressiert wurden. + +## Bereits adressiert + +### R-01 Mandantenfähigkeit +Adressiert durch: +- ADR 0004 Tenancy-Modell +- ADR 0005 Datenbankwahl +- security-and-rights-v0.2.md + +### R-02 Anbieterlogik im Core +Adressiert durch: +- ADR 0008 External-Reference-Pattern +- data-model-v0.2-direction.md + +### R-03 Billing im Core +Adressiert durch: +- ADR 0009 Core-Grenzen +- module-structure-v0.2.md +- data-model-v0.2-direction.md + +### R-04 Modulstruktur widersprüchlich +Adressiert durch: +- ADR 0022 Dokumentenhierarchie +- module-structure-v0.2.md + +### R-05 Secrets-Management +Adressiert durch: +- ADR 0010 Secrets-Management + +### R-06 Core zu groß +Adressiert durch: +- ADR 0009 Core-Grenzen +- core-architecture-v0.2.md + +### R-07 GoBD-Verantwortlichkeit +Adressiert durch: +- ADR 0011 GoBD-Verantwortlichkeit + +### R-08 DSGVO-Löschung vs. Retention +Adressiert durch: +- ADR 0021 DSGVO-Löschung und Retention + +### R-09 API-Auth +Adressiert durch: +- ADR 0006 Auth-Strategie + +### R-10 Datenbankwahl +Adressiert durch: +- ADR 0005 Datenbankwahl + +### R-11 KI in V1 +Adressiert durch: +- ADR 0019 V1-Scope-Finalisierung + +### R-12 SEPA ohne Modell +Adressiert durch: +- ADR 0019 V1-Scope-Finalisierung + +### R-13 V1-Scope widersprüchlich +Adressiert durch: +- ADR 0019 V1-Scope-Finalisierung +- roadmap/v1-scope-v0.2.md + +### R-14 Audit-Unveränderbarkeit +Adressiert durch: +- ADR 0014 Audit-Log-Strategie + +### R-16 Steuer-/MwSt-Logik +Adressiert durch: +- ADR 0015 Tax- und VAT-Strategie + +### R-18 Adapter-Fehlerresilienz +Adressiert durch: +- ADR 0017 Adapter-Fehlerresilienz + +### R-20 Nummernkreise +Adressiert durch: +- ADR 0023 Nummernkreise + +### R-21 Personen-/Adressmodell +Adressiert durch: +- ADR 0013 Kunden-/Adress-/Kontaktmodell + +### R-23 Frontend-Strategie +Adressiert durch: +- ADR 0012 Frontend-Strategie + +### R-25 Modul-Lifecycle +Adressiert durch: +- ADR 0016 Modul-Lifecycle + +### R-28 Dokumentenhierarchie +Adressiert durch: +- ADR 0022 Dokumentenhierarchie + +## Noch nicht vollständig adressiert + +### R-15 Tenant-Offboarding +Teilweise durch ADR 0021 vorbereitet. +Braucht später eigenes Dokument. + +### R-19 API-Versionierungsstrategie +Teilweise durch api-strategy-v0.2 adressiert. +Braucht später API-Conventions-Datei. + +### R-22 WordPress-Plugin-Sicherheitsmodell +Teilweise durch ADR 0018 adressiert. +Später konkreter. + +### R-24 Barrierefreiheit +Noch offen. +Relevant für Customer Portal V2. + +### R-26 Logging-/Audit-Sink-Architektur +Teilweise durch ADR 0014 adressiert. +Braucht später Logging-Strategy v0.2. + +### R-27 Spekulative Felder +Wird durch data-model-v0.2-Überarbeitung behandelt. diff --git a/reviews/claude-review-round1.md b/reviews/claude-review-round1.md new file mode 100644 index 0000000..8d4c806 --- /dev/null +++ b/reviews/claude-review-round1.md @@ -0,0 +1,289 @@ +# Architecture Review – Runde 1 + +**Reviewer:** Claude (kritischer Senior Architect / Platform Engineer) +**Reviewed:** Hosting-Backoffice v0.1 – vollständiger Basisbestand (49 Dateien) +**Datum:** 15. Mai 2026 +**Stand:** v0.1 Konzeptphase, vor Entwicklungsbeginn + +--- + +## Gesamtanalyse + +Hosting-Backoffice befindet sich in einer ungewöhnlich gut dokumentierten v0.1-Konzeptphase. ADR-Kultur, explizite Non-Goals, ein erkanntes Adapter-Pattern und eine konsistente Vision sind mehr Strukturhygiene, als die meisten Projekte in dieser Phase vorweisen. + +Genau diese Stärken erschweren aber die ehrliche Bewertung. Die Dokumentenmenge täuscht über das tatsächliche Spezifikationsniveau hinweg. Mehrere zentrale Architekturentscheidungen sind nicht entschieden, sondern als „vorbereiten" umschrieben – Mandantenfähigkeit, Datenbankwahl, API-Authentifizierung, Modul-Contract, Secrets-Management, Audit-Unveränderbarkeit, Frontend-Strategie. „Vorbereiten" ist in Softwarearchitektur fast immer das Synonym für „später unter Schmerzen nachrüsten". + +Das zweite Grundmuster ist innere Widersprüchlichkeit. Strategie-Dokumente, Modulbeschreibungen, Roadmap und MVP-Liste erzählen an mehreren Stellen unterschiedliche Geschichten: + +- V1-Zielgröße: 1–500 Kunden (Vision) vs. 1–50 Kunden (Roadmap/MVP) +- KI-Assistent: V1-Modul vs. V2-Roadmap-Eintrag +- Kundenportal: eigenes V1-Modul vs. fehlt in MVP-Muss-Funktionen +- Billing/Customer-Portal: existieren als Modul-Dokument, aber tauchen in `module-structure-v0.1.md` weder unter Service- noch unter Integrationsmodulen auf +- Adapter-Pattern („Core kennt keine Anbieterlogik") vs. Datenmodell (`Server.KeyHelp-Referenz`) +- Mandantenfähigkeit: zwei IDs (`organisation_id` + `tenant_id`) ohne erklärte Beziehung + +Diese Inkonsistenzen sind keine Schönheitsfehler. Sie zeigen, dass Strategie- und Modul-Dokumente unabhängig voneinander gewachsen sind, ohne dass eine Quelle die andere kontrolliert. Bevor Code geschrieben wird, muss die Modul-Struktur zur einzigen verbindlichen Wahrheit erhoben werden – sonst entstehen drei verschiedene Implementierungen aus drei verschiedenen Dokumenten. + +Die zentrale Empfehlung dieses Reviews ist nicht „Stoppt das Projekt" und auch nicht „Macht weiter wie geplant". Sie lautet: **Entscheidet jetzt eine begrenzte Anzahl harter Architekturfragen, reduziert V1 weiter, und stellt sicher, dass die Adapter-/Modul-Architektur nicht durch das Datenmodell sabotiert wird.** Alles andere lässt sich später korrigieren. Diese drei Punkte nicht. + +Das Projekt ist gut positioniert, schlank zu bleiben. Es ist gleichzeitig schlecht positioniert, modular zu bleiben. Beide Eigenschaften kollidieren in der aktuellen Core-Größe. + +--- + +## Architekturkritik + +**Der Core ist faktisch die ganze Anwendung.** +Die Aussage „Core enthält ausschließlich zentrale Plattformlogik" wird durch die Core-Liste sofort widerlegt: Kunden, Verträge, Produkte, Domains, Hostingpakete, Server, Dokumente, Benachrichtigungen, plus Identity/RBAC/Audit/API/Settings. Das sind 13 Bereiche, davon mindestens 6 (Domains, Hostingpakete, Server, Dokumente, Notifications, Produkte) klare Service-Domänen mit eigener Geschäftslogik. Wenn diese sechs Bereiche im Core leben, gibt es genau einen Bounded Context, und das System ist per Definition ein Monolith mit angeflanschten Integrationen – exakt das, was in der Vision vermieden werden soll. Modularität entsteht nicht durch Modul-Verzeichnisse, sondern durch klare Bounded Contexts mit eigenen Datenmodellen und definierten Kontrakten. + +**„API-first" wird nicht konsequent durchgehalten.** +„API-first" ist in den Strategiepapieren proklamiert, aber: +- Frontend-Strategie ist offen („Blade oder später Vue/Nuxt") – das ist mit echtem API-first nicht vereinbar +- Es existiert kein API-Vertrag (kein OpenAPI/Stoplight/etc.), keine spec-first-Disziplin +- Auth-Strategie ist nicht entschieden („Tokenbasiert, später OAuth/Sanctum möglich") +- Idempotenz, Pagination, Filterung, Error-Modell sind nicht beschrieben +- Versionierung beschränkt sich auf URL-Path (`/api/v1/`), ohne Deprecation/Sunset-Strategie + +Solange die API kein Vertrag vor dem ersten Endpoint ist, ist „API-first" Marketing, nicht Architektur. + +**Adapter-Pattern und Datenmodell widersprechen sich direkt.** +Das Adapter-Pattern wird als zentrales Architekturprinzip beschrieben („Core kennt keine direkte Anbieterlogik"). Im Datenmodell stehen aber `Server.KeyHelp-Referenz` und `Rechnung.externes System` als Core-Felder. Das ist nicht ein bisschen unsauber – das ist genau der Verstoß gegen das eigene Pattern. Sobald V1 mit dieser Schema-Form deployt wird, ist das Adapter-Pattern auf Konzept-Ebene tot. + +**Mandantenfähigkeit ist eine Absichtserklärung, kein Design.** +Das Multi-Tenancy-Dokument beschreibt nur Ziele, nicht den Mechanismus. Zwei ID-Spalten auf jeder Tabelle (`tenant_id` und `organisation_id`, ohne dass deren Verhältnis erklärt ist) sind keine Multi-Tenancy. Ohne entschiedenes Isolationsmodell (Scope-basiert, Schema-basiert, DB-basiert) und ohne enforcement-Mechanismus (Global Scope, Row-Level Security, Connection-Switching) ist V1 ein Single-Tenant-System, das *behauptet*, vorbereitet zu sein. Diese Behauptung trägt nicht in V3, wenn Reseller-Strukturen kommen sollen. + +**Daten im Core, Logik in Modulen – das klassische Anti-Pattern.** +`Rechnung` und `Zahlung` stehen im Core-Datenmodell. Billing-Logik ist als Modul gedacht und über externe Integrationen (Lexware, Invoice Ninja) angebunden. Das ergibt: Module schreiben in Core-Tabellen, kennen also das Core-Schema, und jede Schema-Änderung im Core bricht Module. Saubere Variante: Billing ist eine eigene Bounded-Context-Domäne mit eigenem Datenmodell, der Core kennt höchstens eine `InvoiceReference`-Tabelle ohne semantische Tiefe. + +**WordPress-Plugin ist eine zweite Datensphäre ohne Sicherheitsmodell.** +Die Entscheidung gegen WordPress als Core ist richtig und gut begründet (ADR 0001). Die Folgekosten sind aber unterschätzt: Das Plugin ist ein vollständiger API-Client mit eigener Session-Domäne, eigenem Update-Zyklus, eigener Plugin-Ökosystem-Risikofläche und eigener Auth-Brücke zu Hosting-Backoffice. Was passiert, wenn die WP-Site kompromittiert ist – welche API-Rechte hatte das Plugin? Gibt es Scope-begrenzte Tokens? Wer ist Mandant aus Sicht der API, wenn ein WP-User auf das Plugin klickt? Diese Fragen sind nicht beantwortet, und Plugin-Entwicklung kann nicht beginnen, bevor sie es sind. + +--- + +## Core- und Modulbewertung + +Die Modulstruktur in `module-structure-v0.1.md` ist nicht die einzige Quelle der Wahrheit. Sie listet weniger Module, als das Repository tatsächlich definiert. Vor allem fehlen **Billing** und **Customer Portal** in der Struktur, obwohl sie eigene Modul-Dokumente haben. Vor dem Codebeginn muss diese Liste verbindlich und vollständig sein. + +**Was sinnvoll im Core gehört (kleinster nötiger Core):** +- Identity / Authentication (User, Tenant) +- RBAC / Policy +- Audit Trail (append-only) +- Settings / Configuration +- Module Registry & Lifecycle +- Event Bus / Notification Routing (Routing, nicht Channels) +- Tenant Scope Enforcement + +**Was aktuell im Core ist und herausgeschoben werden sollte:** +- Domains → eigene Domäne (Service-Modul) +- Hostingpakete → eigene Domäne (Service-Modul) +- Server → eigene Domäne (Service-Modul) +- Dokumente / Content → Document-Archive-Modul (existiert bereits separat – warum dann auch im Core?) +- Notifications (Channels, nicht Routing) → eigenes Modul oder Adapter +- Produkte → entweder zu Billing-Domäne oder eigene kleine Domäne + +**Module, die fehlen oder unscharf sind:** +- **Billing/Invoicing-Domäne** als eigenständige Service-Domäne (heute im Core-Datenmodell, in Modul-Beschreibung unspezifisch) +- **Mahnwesen / Offene Posten** – „kein Payment-System" heißt nicht „kein Forderungsmanagement" +- **DNS-Management** – gehört nicht in Domain-Verwaltung +- **Provisioning** – Hostingpaket-Lifecycle ist eigene Domäne +- **Tenant-Lifecycle** (Onboarding, Suspend, Offboarding, Export) +- **Secrets-Vault** für Registrar-/Provider-Credentials +- **Reporting/Export** (GoBD-Z3-Export, DSGVO-Auskunft) +- **Webhooks / Outbound-Events** – für API-first praktisch zwingend +- **Tax/VAT-Logik** (kein Wort zu MwSt, OSS, Reverse Charge B2B EU) + +**Modul-Contract muss formalisiert werden.** +„Definierte Interfaces" reicht nicht. Konkret zu spezifizieren: +- Wie ist ein Modul aufgebaut (Composer-Package, in-app Namespace, Nwidart-Module) +- Wie deklariert ein Modul Abhängigkeiten zur Core-API-Version +- Wie kommunizieren Module untereinander (Events? Service-Contracts? Beides?) +- Was passiert bei Deinstallation eines Moduls mit existierenden Daten und Referenzen +- Wie sind Migrationen pro Modul versioniert und mit Core-Migrationen verzahnt + +--- + +## Datenmodellbewertung + +Das Dokument `data-model-v0.1.md` ist kein Datenmodell. Es ist eine Objektliste mit Feldnamen. Die schwierigen Teile fehlen vollständig: Beziehungen, Kardinalitäten, Lebenszyklen, Statusmaschinen, Nummernkreise, Aggregat-Grenzen. + +**Konkrete Probleme im aktuellen Stand:** +- `Server.KeyHelp-Referenz` und `Rechnung.externes System` verdrahten konkrete Anbieter im Core und brechen das Adapter-Pattern. Saubere Form: generische `external_references`-Tabelle mit `owner_type`, `owner_id`, `adapter_id`, `external_id`, `metadata`. +- `Registrar-Account.Zugangsdaten/API-Referenzen` impliziert Credentials im Core-Datenmodell. Es darf keine Credential-Spalten in DB-Tabellen geben – nur Referenzen in einen Vault. +- `Kunde` enthält „Stammdaten + Ansprechpartner + Kontaktdaten" als undifferenziertes Bündel. Klassisches Anti-Pattern. Üblich: `Party` (Person/Organisation) + `Address` (mit Verwendungszweck) + `ContactPoint`. DSGVO-Auskunft und -Löschung werden sonst sehr teuer. +- `organisation_id` + `tenant_id` parallel ohne erklärte Semantik – entweder Duplikat (eines streichen) oder Hierarchie (dann benennen und Modell zeigen). +- B2B/B2C-Unterscheidung fehlt komplett – beeinflusst Steuer, AGB, Widerrufsrecht, Rechnungsfelder. +- Nummernkreise (Kundennummer, Vertragsnummer, Rechnungsnummer) – pro Mandant lückenlos, GoBD-konform – nirgends modelliert. + +**Was im Datenmodell fehlt:** +- Statusmaschinen für Vertrag, Domain, Hostingpaket, Ticket, Rechnung mit erlaubten Übergängen +- Beziehungstabellen explizit (Many-to-many: Vertrag–Produkt? Domain–Vertrag? Hostingpaket–Vertrag?) +- Subscription-/Recurring-Logik (Laufzeit, Up-/Downgrade, Pro-rata) +- Soft-Delete vs. Archivierung vs. DSGVO-Löschung – diese drei Anforderungen konkurrieren und müssen entschieden werden +- Audit-Log-Schema (was wird wie granular geloggt, append-only-Mechanismus) +- Versionierung von Belegen (für GoBD: unveränderbar nach Festschreibung) +- Datei-/Asset-Modell mit Hashes, Content-Addressing, Versionen + +**Empfehlung:** +Vor dem Codebeginn sollte ein vollständiges ER-Modell (z.B. dbdiagram.io oder vergleichbar) entstehen, das Beziehungen, Kardinalitäten und mindestens die wichtigsten Statusmaschinen zeigt. Aus dem aktuellen Objektliste-Format lassen sich keine sauberen Migrationen ableiten. + +--- + +## API-Bewertung + +Die API-Strategie und API-Conventions sind die schwächsten Dokumente im Bestand, gemessen daran, dass „API-first" das zentrale Architekturversprechen ist. + +**Was vorhanden ist:** +- URL-Path-Versionierung (`/api/v1/`) +- Ressourcen-Endpoints sinnvoll benannt +- Konsistentes Antwortformat (`data`, `meta`, `errors`) +- Bewusstsein für Auth, Rechteprüfung, Rate-Limiting, Logging + +**Was fehlt:** +- **Spec-first**: Kein OpenAPI/AsyncAPI-Dokument. Ohne maschinenlesbare API-Spec gibt es keinen Vertrag, kein Contract-Testing, keinen Client-Generator, kein verbindliches Schema. Für API-first ist OpenAPI 3.x die Mindestanforderung. +- **Auth-Strategie konkret**: „Tokenbasiert, später OAuth/Sanctum" mischt Konzeptebenen. Konkret zu entscheiden: Sanctum Personal Access Tokens (gut für M2M und einfache Clients), Sanctum SPA-Mode (für eigenes Frontend), oder Passport/OAuth2 (für Drittanbieter-Apps). Antwort: vermutlich Sanctum für V1 (alles), Passport in V2/V3 wenn das WP-Plugin von Mandant zu Mandant deployed wird. +- **Idempotenz**: Bei `POST` auf Domain-Registrierung, Vertragsanlage, Rechnungserstellung essentiell. Idempotency-Key-Header sollte Standard sein. +- **Pagination-Strategie**: Offset/Limit, Cursor, Page? Cursor ist für skalierende APIs robuster. +- **Filtering & Sorting**: einheitliches Schema (z.B. `filter[status]=open`, `sort=-created_at`). +- **Error-Modell**: Problem Details (RFC 7807) ist Standard – kein einzelnes Wort dazu. +- **Deprecation/Sunset**: `/api/v2/` ohne Strategie, wie alte Versionen abgekündigt werden. +- **Webhooks**: Out-of-band Notifications nach außen (an WordPress-Plugin, an Integratoren) sind in den V1-Plänen unsichtbar. +- **Rate-Limit pro Mandant**: nicht nur pro IP/Token, sondern pro Tenant-Budget. + +**Empfehlung:** +Bevor der erste Endpoint implementiert wird, sollte ein OpenAPI-Stub mit den ~20 wichtigsten Ressourcen und Auth-Flows entstehen. Daraus folgen Controller-Skelette, Resource-Klassen und Validation Rules praktisch automatisch. + +--- + +## Mandantenfähigkeitsbewertung + +Dies ist der größte einzelne Risikobereich des Projekts. + +**Aktueller Stand:** +- Multi-Tenancy-Strategie listet Ziele, keinen Mechanismus +- V1 ist explizit Single-Tenant +- `tenant_id` und `organisation_id` werden auf alle Tabellen gehängt +- Sicherheitsprinzip lautet: „Mandanten dürfen niemals auf fremde Daten zugreifen" + +**Was problematisch ist:** +1. **„Vorbereiten" ohne Mechanismus** ist keine Vorbereitung. Wenn V1 ohne Tenant-Scope-Enforcement implementiert wird (Global Scopes, Policy-Checks, RLS, Connection-Switching), wird jede Query, jede Policy, jeder Job, jeder Cache-Key, jeder Webhook und jede Integration beim Multi-Tenant-Schritt aufgegriffen werden müssen. +2. **Zwei IDs ohne erklärtes Modell.** Falls die Doppelung eine Hierarchie meint (z.B. Plattformbetreiber → Reseller-Organisation → Mandant), muss das ER-Modell die Hierarchie zeigen. Falls beides Synonym ist, muss eines weg. +3. **Tenant-Lifecycle nirgends modelliert.** Provisioning, Suspend, Termination, Datenexport, Datenmigration, Offboarding – keine dieser Operationen ist beschrieben. Bei DSGVO-Beendigung muss ein Mandant seine Daten innerhalb angemessener Frist erhalten und der Plattformbetreiber sie löschen können (mit GoBD-Vorbehalt). +4. **Cross-Tenant-Datenflüsse** (z.B. shared Templates, shared Knowledge Base, shared Module Registry) – architektonisch nicht vorgesehen, aber realistisch. + +**Empfehlung:** +- Tenancy-Modell *jetzt* entscheiden – mein Vorschlag: Shared Database, Tenant-ID-Scope, Row-Level Security on Postgres als zweite Verteidigungsschicht. Begründung: gut testbar, ein Schema, gute Migration-Hygiene, RLS als Defense-in-Depth, später ohne Datenstruktur-Bruch auf DB-per-Tenant für Premium-Mandanten erweiterbar. +- Tenant-Scope von Tag 1 als Global Scope auf allen mandantenscoped Eloquent-Modellen. +- Verpflichtende Tenant-ID-Spalte auf allen mandantenrelevanten Tabellen mit FK, NOT NULL, indexed. +- Audit-Test in CI: keine Query ohne Tenant-Scope (statische Analyse oder Runtime-Assertion). +- Klarstellung `organisation_id` vs. `tenant_id` mit ER-Modell. + +--- + +## V1-Scope-Bewertung + +V1 hat ein klares Erfolgsversprechen („Ordnung schaffen für kleine Anbieter mit 1–50 Kunden"), das durch die V1-Non-Goals-Disziplin unterstützt wird. Allerdings ist V1 intern nicht konsistent und an mehreren Stellen ambitionierter, als das Erfolgsversprechen rechtfertigt. + +**Was widersprüchlich oder zu groß ist:** +- **KI-Assistent** ist v0.1-Modul, aber Roadmap listet KI in V2. KI bringt DSGVO-Subprozessor-Komplexität (Auftragsverarbeitung, Drittlandtransfer), die V1 nicht braucht. Empfehlung: aus V1 raus, in V2 zusammen mit WordPress-Plugin. +- **Customer Portal** ist v0.1-Modul, fehlt aber in den MVP-Muss-Funktionen. Empfehlung: explizit entscheiden. Wenn V1 kein Kundenportal hat, sind viele Folgekosten weg (Self-Service-Auth, BFSG, AGB-Annahme). Wenn ja, dann mit reduziertem Funktionsumfang. +- **SEPA-Lastschrift** als V1-Zahlungsart ohne SEPA-Modell (Mandate, UMR, Pre-Notification, IBAN-Speicherung). Empfehlung: Lastschrift aus V1 raus oder Modell ergänzen. +- **1blu Business** + **KeyHelp** als V1-Integrationen mit Import-Funktion – realistisch für 3–5 Pilotkunden, aber **API-Sync** sollte explizit V2 bleiben (steht so in der Roadmap, sollte aber auch im V1-Modul-Dokument klargestellt sein). +- **PayPal, Wero** als V1-Zahlungsarten – sind Zahlungsarten reine Anzeige/Status (dann OK) oder Integrationen (dann viel mehr Aufwand)? Aktuell mehrdeutig. + +**Was in V1 fehlt und gebraucht wird:** +- **Steuer-/MwSt-Logik** mindestens minimal (deutscher Standardfall, mit Erweiterbarkeit für EU-OSS) +- **Mahnwesen** mindestens als Status („überfällig" + manuelle Erinnerung) – steht in V1-Non-Goals als „eigenes Mahnwesen in voller Tiefe", aber ohne *jegliches* Mahnwesen ist Hosting-Betrieb nicht durchführbar +- **DSGVO-Auskunft** als Funktion (Datenexport pro Endkunde) – wenn V1 wirklich produktiv genutzt wird, ist das Pflicht +- **Nummernkreis-Verwaltung** (mindestens Rechnungs- und Kundennummer pro Mandant) +- **E-Mail-Versand-Infrastruktur** (SMTP/Transactional Mail, SPF/DKIM/DMARC-Hinweise) + +**Empfehlung:** +- V1-Kundenzahl auf 1–50 vereinheitlichen (Roadmap-Wert). +- KI raus aus V1. +- Customer Portal entweder explizit IN oder OUT, mit allen Folgekosten. +- SEPA aus V1 raus oder vollständig modellieren. +- Tax und Nummernkreise als V1-Pflicht ergänzen. + +--- + +## Roadmap-Bewertung + +Die V1→V2→V3-Progression ist als Konzept stimmig. V1 schafft Ordnung, V2 automatisiert, V3 öffnet Plattform-Funktionen. Das Problem liegt in den V1-Vorarbeiten für V2/V3. + +**Was V2/V3 voraussetzt und V1 nicht liefert:** +- V3-Reseller / tiefere Mandantenfähigkeit: setzt voraus, dass V1 strikten Tenant-Scope von Tag 1 hat. V1 hat das aktuell nicht. +- V3-Servermigration: setzt voraus, dass Hostingpaket-Server-Zuordnung versioniert und auditierbar ist. V1 hat heute nur eine direkte Zuordnung ohne History. +- V2-API-Synchronisation: setzt voraus, dass externe Referenzen als generisches Pattern existieren. V1 hat hartkodierte Anbieter-Referenzen. +- V2-WordPress-Plugin: setzt voraus, dass die API ein vollständiger, versionierter, mit Auth-Scopes versehener Vertrag ist. V1 hat „/api/v1/" ohne Vertrag. +- V2-KI-Funktionen: setzt DSGVO-Auftragsverarbeitungsmodell und Subprozessor-Transparenz voraus. Beides fehlt. + +**Empfehlung:** +Die Roadmap sollte um eine Spalte ergänzt werden: *„V1-Voraussetzungen für dieses V2/V3-Feature"*. Jedes V2/V3-Feature, dessen V1-Voraussetzungen heute fehlen, ist entweder ein verstecktes V1-Item oder ein gefährlicher Selbstbetrug. + +--- + +## Empfehlungen für die nächste Arbeitsphase + +Diese Empfehlungen sind die Konsequenz der bisherigen Bewertung. Sie sind in absteigender Priorität sortiert. + +### 1. NOW-Entscheidungen vor Codebeginn + +Zehn Entscheidungen, die *jetzt* fallen müssen: + +1. **Tenancy-Modell konkret entscheiden** (Vorschlag: Shared DB + Tenant-Scope + Postgres RLS) +2. **Datenbank-Engine entscheiden** (Postgres empfohlen, weil RLS, JSONB, transaktionales DDL) +3. **`organisation_id` vs. `tenant_id` klären** und einen davon streichen, oder Hierarchie als ER-Modell +4. **Auth-Stack festlegen** (Vorschlag: Sanctum für V1, Passport für V2 WP-Plugin) +5. **Modul-Container festlegen** (Composer-Packages, Nwidart-Module, oder eigenes Modul-System) +6. **Secrets-Strategie** (Laravel Encryption nicht ausreichend für Mandanten-Credentials; eigener Vault-Service oder externer Secret-Manager) +7. **Frontend-Modell** (Blade-Renderer als API-Konsument *oder* echtes SPA – nicht „später entscheiden") +8. **GoBD-Eigner** (ist Hosting-Backoffice der Beleg-Originalspeicher oder nur Spiegel? Empfehlung: Spiegel) +9. **KI-Assistent V1 oder V2** (Empfehlung: V2) +10. **Customer Portal V1 oder V2** (Empfehlung: V2, falls möglich) + +### 2. Strukturhygiene vor Codebeginn + +- Modulstruktur in `module-structure-v0.1.md` als einzige Wahrheit etablieren. Alle Modul-Dokumente müssen darin gelistet sein. +- Roadmap und MVP-Liste auf gleichen Kundenzahl-Bereich (1–50) bringen. +- Adapter-Pattern-Konformität im Datenmodell herstellen: keine anbieter-spezifischen Felder im Core, generische `external_references`. +- ADRs ergänzen: ADR 0004 (Tenancy-Modell), ADR 0005 (Datenbankwahl), ADR 0006 (Auth-Strategie), ADR 0007 (Modul-Container), ADR 0008 (GoBD-Verantwortlichkeit). + +### 3. Datenmodell auf v0.2 bringen + +- ER-Diagramm mit Beziehungen und Kardinalitäten +- Statusmaschinen für Vertrag, Domain, Hostingpaket, Ticket, Rechnung +- Party/Address/ContactPoint-Trennung statt monolithischem `Kunde`-Objekt +- Nummernkreis-Mechanismus +- Generisches External-Reference-Pattern +- Audit-Log-Schema mit Unveränderbarkeitsmechanismus + +### 4. API-Vertrag vor Endpoint-Implementierung + +- OpenAPI 3.x als verbindliche API-Spezifikation +- Auth-Flows dokumentiert +- Idempotency-, Pagination-, Filtering-, Error-Modell festgelegt +- Webhook-Strategie als eigenes Dokument + +### 5. V1 weiter verschlanken + +- KI raus +- Customer Portal entscheiden (idealerweise raus) +- SEPA raus oder vollständig modellieren +- Aber: Tax, Nummernkreise, einfaches Mahnwesen, DSGVO-Auskunft hinzunehmen + +### 6. Was bewusst nicht jetzt entschieden werden muss + +- SaaS-vs-Self-hosted-Mix +- Konkrete Cloud-Strategie +- Marketplace-/Reseller-Detail +- Mehrsprachigkeit (außer dass UI-Layer das nicht blockiert) +- Mobile App + +Diese Bereiche dürfen in v0.x bleiben – sie sind unkritisch für die Architekturqualität. + +--- + +## Schlussbemerkung + +Hosting-Backoffice ist nicht in der Gefahr, ein schlechtes Produkt zu werden. Vision, Positionierung und Disziplin sind über dem Branchendurchschnitt. Es ist aber in der Gefahr, **als modulares Produkt geplant und als verstecker Monolith gebaut zu werden**, wenn die hier beschriebenen NOW-Entscheidungen nicht vor dem ersten Endpoint fallen. Die einzelnen Probleme sind alle lösbar – aber in Summe und ungelöst sind sie das Material, aus dem teure Refactorings gemacht sind. + +Die nächste Arbeitsphase sollte nicht „mit V1-Implementierung beginnen" heißen, sondern „v0.2 mit den entschiedenen NOW-Punkten herausgeben". Erst dann lohnt sich Code. diff --git a/reviews/open-decisions-for-olaf.md b/reviews/open-decisions-for-olaf.md new file mode 100644 index 0000000..21b7fd3 --- /dev/null +++ b/reviews/open-decisions-for-olaf.md @@ -0,0 +1,62 @@ +# Offene Entscheidungen für Olaf + +## Zweck +Diese Datei sammelt Punkte, bei denen später eine geschäftliche oder strategische Entscheidung nötig ist. + +Technische Architekturentscheidungen wurden soweit sinnvoll vorbereitet. + +## 1. SaaS oder Self-hosted? + +### Kurz erklärt +SaaS bedeutet: +Du betreibst die Software zentral für Kunden. + +Self-hosted bedeutet: +Kunden installieren/betreiben die Software selbst. + +### Empfehlung aktuell +Noch nicht final entscheiden. + +V1 als eigene interne produktive Instanz planen. +Später SaaS-/Self-hosted-Strategie bewerten. + +## 2. Customer Portal in V2 wirklich öffentlich? + +### Kurz erklärt +Ein öffentliches Kundenportal bedeutet, dass Endkunden sich selbst einloggen können. + +### Empfehlung aktuell +V1 ohne öffentliches Portal. +V2 bewusst entscheiden. + +## 3. WordPress-Plugin früh oder später? + +### Empfehlung aktuell +Architektur vorbereiten, aber nicht in V1 bauen. + +## 4. KI-Assistent + +### Empfehlung aktuell +Nicht V1. +In V2 neu bewerten, wenn Datenschutz- und Anbieterfrage klar ist. + +## 5. Zahlungsarten mit Gebühren + +### Kurz erklärt +Ein Zahlungsaufschlag für bestimmte Zahlungsarten kann rechtlich heikel sein. + +### Empfehlung aktuell +Architektur erlaubt Gebührenregeln. +Aktivierung erst nach rechtlicher Prüfung. + +## 6. Invoice Ninja als echte Alternative zu Lexware? + +### Empfehlung aktuell +Als Referenz-/Integrationsziel ja. +Aber GoBD-Rolle sauber prüfen, wenn produktiv für echte Rechnungen genutzt. + +## 7. Marke / Produktname + +### Empfehlung aktuell +Später separat behandeln. +Nicht vor Architektur v0.2 abschließend entscheiden. diff --git a/reviews/perplexity-research-placeholder.md b/reviews/perplexity-research-placeholder.md new file mode 100644 index 0000000..aec65c0 --- /dev/null +++ b/reviews/perplexity-research-placeholder.md @@ -0,0 +1,12 @@ +# Perplexity Research Placeholder + +Hier können spätere Rechercheergebnisse abgelegt werden. + +Themen: +- WHMCS-Alternativen +- KeyHelp API +- Lexware API +- Invoice Ninja CE +- 1blu Export/API +- GoBD-Archivierung +- Wero/Payment-Integration diff --git a/reviews/review-notes-template.md b/reviews/review-notes-template.md new file mode 100644 index 0000000..c9ae385 --- /dev/null +++ b/reviews/review-notes-template.md @@ -0,0 +1,32 @@ +# Review Notes Template + +## Quelle / Modell + + +## Datum + + +## Thema + + +## Wichtigste Erkenntnisse + +- + +## Risiken + +- + +## Vorschläge + +- + +## Entscheidung erforderlich? + +Ja / Nein + +## Übernahme ins Projekt + +- übernehmen +- später prüfen +- verwerfen diff --git a/roadmap/roadmap-v1-v3.md b/roadmap/roadmap-v1-v3.md new file mode 100644 index 0000000..ee6e293 --- /dev/null +++ b/roadmap/roadmap-v1-v3.md @@ -0,0 +1,39 @@ +# Roadmap V1–V3 + +## V1 — Produktiv nutzbare Grundversion + +Ziel: Produktiv nutzbar für kleine Anbieter mit 1–50 Kunden. + +Fokus: +- Kundenverwaltung +- Verträge +- Produkte +- Domains +- Registrar-Import +- Hostingpakete +- Server +- Rechnungsübersicht +- Billing-Integrationen +- Ticketsystem light +- Dokumentenarchiv +- Audit-Logs + +## V2 — Erweiterte Automatisierung + +- API-Synchronisation +- weitere Registrare +- TLD-Regeln +- tiefere KeyHelp-Synchronisation +- KI-Funktionen +- verbessertes Kundenportal +- WordPress-Plugin + +## V3 — Erweiterte Plattformfunktionen + +- Hostingmigrationen +- Serverwechsel +- Mailmigrationen +- Server-Templates +- tiefere Mandantenfähigkeit +- Resellerstrukturen +- erweiterte APIs diff --git a/roadmap/v1-minimum-viable-product.md b/roadmap/v1-minimum-viable-product.md new file mode 100644 index 0000000..cbd51d0 --- /dev/null +++ b/roadmap/v1-minimum-viable-product.md @@ -0,0 +1,38 @@ +# V1 Minimum Viable Product + +## Ziel + +Eine erste stabile und produktiv nutzbare Version für kleine Hostinganbieter mit ca. 1–50 Kunden. + +## Kernziel + +Ordnung schaffen. + +## V1 Muss-Funktionen + +- Kundenverwaltung +- Verträge +- Domains +- Registrar-Import +- Hostingpakete +- Server +- Rechnungsübersicht +- Billing-Integrationen +- Ticketsystem light +- Archivierung +- Audit-Logs + +## Kein Ziel von V1 + +- automatische Provisionierung +- VM-Orchestrierung +- Kubernetes +- automatische Migrationen +- cPanel/Plesk +- große Resellerstrukturen +- Marketplace +- komplexes ERP + +## Erfolgsdefinition V1 + +Ein kleiner Anbieter soll sein Hostinggeschäft organisieren, Kunden zentral verwalten, Domains nachvollziehen, Rechnungen referenzieren und Support professionell bearbeiten können. diff --git a/roadmap/v1-non-goals.md b/roadmap/v1-non-goals.md new file mode 100644 index 0000000..3c92855 --- /dev/null +++ b/roadmap/v1-non-goals.md @@ -0,0 +1,35 @@ +# V1 Non-Goals + +## Grundprinzip + +V1 soll bewusst klein bleiben. + +## Nicht Teil von V1 + +### Infrastruktur +- Cloud-Orchestrierung +- VM-Management +- Kubernetes +- automatische Serverbestellung + +### Hosting +- automatische Provisionierung +- automatische Migrationen +- Plesk/cPanel +- komplexe Serversteuerung + +### Billing +- eigenes Payment-System +- eigene Buchhaltung +- komplexe Steuerlogik +- eigenes Mahnwesen in voller Tiefe + +### Enterprise +- Marketplace +- große Multi-Provider-Systeme +- komplexe Resellerstrukturen +- Enterprise-Ticketsystem + +## Ziel + +Feature-Explosion vermeiden. diff --git a/roadmap/v1-scope-v0.2.md b/roadmap/v1-scope-v0.2.md new file mode 100644 index 0000000..60f6a3a --- /dev/null +++ b/roadmap/v1-scope-v0.2.md @@ -0,0 +1,53 @@ +# V1 Scope v0.2 + +## Zweck +Dieses Dokument ersetzt frühere widersprüchliche V1-Beschreibungen. + +## Zielgruppe V1 +Kleine Anbieter mit 1–50 Kunden. + +## V1-Ziel +Ordnung schaffen und internes Backoffice produktiv nutzbar machen. + +## V1 enthält + +- Admin-/Backoffice-Oberfläche +- Tenant-Grundstruktur +- Benutzer und Rollen +- Kundenverwaltung +- Kontakt-/Adressmodell +- Verträge +- Produkte/Leistungen +- Domains +- 1blu Import +- Server-/Hosting-Zuordnung +- Rechnungsreferenzen +- Lexware-/Invoice-Ninja-Referenzfähigkeit +- Tickets light intern +- Dokumentenablage +- Audit-Logs +- Nummernkreise +- minimale Tax-/VAT-Metadaten +- Secret-Service-Grundlage +- External References + +## V1 enthält nicht + +- vollständiges öffentliches Kundenportal +- WordPress-Plugin +- KI-Assistent +- SEPA-Mandatsverwaltung +- eigenes Payment-System +- eigene führende Rechnungsstellung +- automatische Servermigration +- Plesk/cPanel +- Marketplace +- Cloud-/VM-Provisionierung + +## Erfolgsdefinition +Ein kleiner Anbieter kann seine Kunden, Domains, Hostingpakete, Rechnungsreferenzen und Supportfälle intern professionell verwalten. + +## Wichtig +V1 ist keine WHMCS-Kopie. + +V1 ist ein stabiles internes Hosting-Backoffice. diff --git a/ui/customer-dashboard-concept-v0.1.md b/ui/customer-dashboard-concept-v0.1.md new file mode 100644 index 0000000..b0b5193 --- /dev/null +++ b/ui/customer-dashboard-concept-v0.1.md @@ -0,0 +1,24 @@ +# Customer Dashboard Concept v0.1 + +## Ziel + +Das Kundendashboard zeigt alle wichtigen Informationen eines Kunden auf einen Blick. + +## Bereiche + +- Kundendaten +- aktive Verträge +- Domains +- Hostingpakete +- offene Rechnungen oder Zahlungsstatus +- offene Tickets +- letzte Aktivitäten +- Dokumente + +## Supportkontext + +Bei jedem Ticket soll der Mitarbeiter sofort den Kundenkontext sehen. + +## Zielgefühl + +Der Kunde soll professionell betreut wirken; der Anbieter soll schnell handlungsfähig sein. diff --git a/ui/ui-principles-v0.1.md b/ui/ui-principles-v0.1.md new file mode 100644 index 0000000..445ec65 --- /dev/null +++ b/ui/ui-principles-v0.1.md @@ -0,0 +1,33 @@ +# UI Principles v0.1 + +## Grundprinzip + +Die Oberfläche soll Ordnung schaffen und nicht überfordern. + +## Leitlinien + +- kundenzentriert +- verständlich +- ruhig +- professionell +- keine Enterprise-Überladung +- klare Statusanzeigen +- wenig Klickwege + +## Zentrale Ansicht + +Die Kundenakte ist der wichtigste UI-Bereich. + +Dort sichtbar: +- Stammdaten +- Verträge +- Domains +- Hostingpakete +- Rechnungen +- Tickets +- Dokumente +- Historie + +## Ziel + +Ein Anwender ohne tiefes Entwicklerwissen soll das System sicher bedienen können. diff --git a/vision/product-vision-v0.1.md b/vision/product-vision-v0.1.md new file mode 100644 index 0000000..3e409ec --- /dev/null +++ b/vision/product-vision-v0.1.md @@ -0,0 +1,19 @@ +# Produktvision v0.1 + +Hosting-Backoffice ist ein europäisches, kundenzentriertes Backoffice-System für kleine Hostinganbieter, Webagenturen, Freelancer und IT-Dienstleister. + +Es soll Ordnung in Kunden, Hostingpakete, Domains, Rechnungen, Zahlungen, Support und Dokumentation bringen. + +Das System richtet sich an Anbieter mit 1–500 Kunden und soll bereits ab dem ersten Kunden sinnvoll nutzbar sein. + +## Kernversprechen + +Professionelles Hosting-Backoffice. Einfach ab dem ersten Kunden. + +## Positionierung + +Keine Enterprise-Monsterlösung, kein WHMCS-Klon, sondern ein verständliches, modulares und europäisch ausgerichtetes Hosting-Backoffice. + +## Grundidee + +Der Kunde steht im Mittelpunkt.