From cdd2d5b676a48f62655b2ad982210736dc0d9deb Mon Sep 17 00:00:00 2001 From: Christoph Date: Thu, 1 Oct 2026 09:35:13 +0200 Subject: [PATCH] =?UTF-8?q?CLAUDE.md=20und=20Tech-Stack-Dokumentation=20er?= =?UTF-8?q?g=C3=A4nzt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md: Befehle, harte Vorgaben (alles lokal, keine Kundendaten, Rechteprüfung), Entwicklungsgrundsätze und Konventionen; wird versioniert, damit alle Entwickler dieselben Regeln haben (aus .gitignore entfernt) - docs/tech-stack.md: Stack auf Basis der Kollegen-Referenz mit bewussten Abweichungen und offenen Punkten - README an TallStackUI und Wegfall von Redis angepasst Co-Authored-By: Claude Opus 5.5 --- .gitignore | 1 - CLAUDE.md | 61 ++++++++++++++++++++++ README.md | 5 +- docs/tech-stack.md | 127 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 191 insertions(+), 3 deletions(-) create mode 100644 CLAUDE.md create mode 100644 docs/tech-stack.md diff --git a/.gitignore b/.gitignore index fa9163c..2503046 100644 --- a/.gitignore +++ b/.gitignore @@ -33,7 +33,6 @@ yarn-error.log /.pi /.mcp.json /AGENTS.md -/CLAUDE.md /boost.json /opencode.json /opencode.jsonc diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6ac7aca --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# KI-BauIN – Hinweise für Claude Code + +KI-gestützte Prüfung von Mehrkostenanzeigen (MKA) und Nachträgen im Bahnbau. Stack und +Begründungen: `docs/tech-stack.md`. Einrichtung und Adressen: `README.md`. + +## Befehle (immer über Sail, PHP 8.5 im Container) + +```bash +./vendor/bin/sail up -d +./vendor/bin/sail artisan test # alle Tests +./vendor/bin/sail artisan test --filter=NameDesTests # einzelner Test +./vendor/bin/sail bin pint # Code-Stil +./vendor/bin/sail bin phpstan analyse # statische Analyse, Stufe 7 +./vendor/bin/sail composer require … # Pakete nur im Container installieren +npm run build # Assets (oder npm run dev) +``` + +Vor jedem Commit: Tests, Pint und PHPStan ohne Fehler. Der gitleaks-Hook (`.githooks`) +wird nicht umgangen. + +## Harte Vorgaben + +- **Alles lokal.** Keine Skripte, Fonts, Bilder oder APIs von fremden Hosts. Einzige Ausnahme + ist später die KI-API des Kunden. `tests/Feature/NoExternalResourcesTest.php` muss grün bleiben. + - `` nur mit `text` (Initialen), nie mit `model`, `gravatar` oder Bild-URL – + sonst lädt TallStackUI von ui-avatars.com bzw. gravatar.com. + - `` nicht verwenden (lädt Emojis von Google). +- **Keine echten Kundendaten** in Code, Tests, Fixtures, Seedern, Commits oder Prompts. + Nur erfundene Beispieldaten (z. B. Projekt „Musterstadt Süd“). +- **Rechte bei jeder geschützten Aktion prüfen** (Policies/Gates, Spatie laravel-permission): + in Controllern und Livewire-Aktionen, bei Downloads, bei Suchtreffern und bevor Inhalte an + ein Sprachmodell gehen. Die Oberfläche auszublenden reicht nicht. +- **Dateien privat speichern** (Disk `local`) und nur über eine Route mit Rechteprüfung ausliefern. + +## Entwicklungsgrundsätze + +- Eingaben serverseitig validieren. +- Geschäftslogik in Services (`app/Services/…`); Livewire-Komponenten steuern nur Anzeige und + Interaktion. +- Zusammengehörige Datenänderungen in einer Datenbanktransaktion. +- Lang laufende oder wiederholbare Arbeit (Dokumentverarbeitung, Embeddings, KI-Aufrufe) als + Job in der Warteschlange (`database`), mit begrenzten Wiederholungen und nachvollziehbarem Status. +- Tabellen, Formulare und Navigation aus gemeinsamen Layouts und Komponenten aufbauen. +- Jede fachliche Änderung mit Feature-Test. + +## Konventionen + +- **Livewire 4, klassenbasierte Komponenten:** Klasse in `app/Livewire/…`, View in + `resources/views/livewire/…`. +- **UI: TallStackUI 4 mit Präfix `ts-`** (``, ``, `` …). + Kurzdoku je Komponente: `vendor/tallstackui/tallstackui/.ai/components/`. Kein Flux. + Toasts/Dialoge aus Livewire über `TallStackUi\Traits\Interactions` (`$this->toast()->success(…)->send()`). +- **Eigene Blade-Komponenten ohne Präfix**, z. B. ``, ``, ``. +- **Dark Mode** über `tallstackui_darkTheme()` am ``-Element; Speicherschlüssel `dark-theme`. +- **Benennung:** Fachbegriffe deutsch (`Mehrkostenanzeige`, `LvPosition`, `Los`), technische + Begriffe nach Laravel-Konvention englisch (`Controller`, `Policy`, `Job`). +- **Länder DE/AT:** gemeinsamer Kern, länderspezifische Logik hinter Schnittstellen in + `app/Laender/DE` bzw. `app/Laender/AT`. Fachliche Tabellen bekommen `mandant_id` und `land`. +- **Tests:** Pest als Runner, Tests im PHPUnit-Klassenstil (`tests/Feature`, `tests/Unit`). + Tests laufen gegen die Datenbank `testing`, nie gegen `ki_bauin`. +- **Commit-Nachrichten** auf Deutsch. diff --git a/README.md b/README.md index 395d653..c915ec4 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,9 @@ KI-gestützte Prüfung von Mehrkostenanzeigen und Nachträgen im Bahnbau. -Laravel 13 mit dem Livewire-Starter-Kit (Livewire 4, Flux, Fortify), Spatie laravel-permission, -Pest. Entwicklung mit Laravel Sail: PHP 8.5, MySQL 8.4, Redis, Meilisearch, Mailpit. +Laravel 13, Livewire 4, TallStackUI 4, Fortify, Spatie laravel-permission, Pest. Entwicklung mit +Laravel Sail: PHP 8.5, MySQL 8.4, Meilisearch, Mailpit. Details und Begründungen in +[`docs/tech-stack.md`](docs/tech-stack.md), Arbeitsregeln für Claude Code in [`CLAUDE.md`](CLAUDE.md). ## Einrichten diff --git a/docs/tech-stack.md b/docs/tech-stack.md new file mode 100644 index 0000000..29898de --- /dev/null +++ b/docs/tech-stack.md @@ -0,0 +1,127 @@ +# KI-BauIN – Tech-Stack + +Stand: 1. Oktober 2026. Grundlage ist die allgemeine Tech-Stack-Referenz einer bestehenden +Laravel-Verwaltungsanwendung (Kollegenprojekt). Dieses Dokument übernimmt deren Grundsätze +und benennt, wo KI-BauIN bewusst abweicht und warum. + +## 1. Backend und Oberfläche + +| Technologie | Einsatz | Vergleich zur Referenz | +|---|---|---| +| PHP 8.5 | Laufzeit (Entwicklung und Produktion gleich) | abweichend (Referenz: 8.4), siehe Abschnitt 6 | +| Laravel 13 | Framework | gleich | +| Livewire 4, klassenbasierte Komponenten | Interaktive Oberfläche; Klasse plus separate Blade-View | abweichend (Referenz: Livewire 3) | +| Blade | Templates, Layouts, eigene Komponenten | gleich | +| Tailwind CSS 4 | Gestaltung | gleich | +| TallStackUI 4 (Präfix `ts-`) | UI-Komponenten | Version abweichend (Referenz: 3) | +| Laravel Fortify | Login, Passwort-Reset, E-Mail-Bestätigung, 2FA, Passkeys | ergänzt | +| Vite 8, Node.js/npm | Asset-Build | gleich | +| Composer | Abhängigkeiten mit Lockfile | gleich | +| PhpSpreadsheet | Excel-Export der Bewertungsmatrix | geplant, sobald die Vorlage vorliegt | +| Dompdf | PDF-Erzeugung | vorerst nicht nötig | + +Aufbau als modularer Laravel-Monolith: Livewire-Komponenten für die Interaktion, Services für +fachliche Abläufe, Eloquent-Modelle für die Daten, Policies und Spatie-Rollen für den Zugriff. +Länderspezifisches (DE/AT) hinter Schnittstellen im Kern, Umsetzungen in `app/Laender/…`. + +## 2. Daten und Hintergrundverarbeitung + +| Baustein | Umsetzung | Vergleich zur Referenz | +|---|---|---| +| MySQL 8.4 LTS | Anwendungsdaten, Rechte, Protokoll; Rohvektoren als BLOB | gleich (Vektoren ergänzt) | +| Eloquent, Migrationen | Datenmodell und Schemaänderungen | gleich | +| Privater Dateispeicher | Uploads (Verträge, LVs, MKAs); Auslieferung nur mit Rechteprüfung | gleich | +| Datenbank-Warteschlange | Dokumentverarbeitung, Embeddings, KI-Aufrufe | gleich | +| Laravel Scheduler | Wiederanlauf hängender Aufträge, Aufräumarbeiten | gleich | +| Meilisearch | Hybride Suche (Volltext + Vektoren) mit Rechte-Filtern; Index jederzeit aus MySQL neu aufbaubar | ergänzt | +| KI-API des Kunden | OCR, Embeddings (Qwen3-Embedding-8B), Reranker | ergänzt; Anbindung folgt | +| Persistenter Ereigniseingang mit HMAC-Prüfung | Falls die KI-API Ergebnisse per Webhook meldet | geplant, abhängig von der API | +| Nachrichten-Outbox | – | vorerst nicht nötig; Benachrichtigungen über die Warteschlange | + +Redis wird nicht eingesetzt: Warteschlange, Cache und Sessions laufen über die Datenbank. + +## 3. Sicherheit + +| Baustein | Umsetzung | Vergleich zur Referenz | +|---|---|---| +| Anmeldung | Fortify, serverseitige Sitzungen; keine Selbstregistrierung | gleich | +| Rollen und Rechte | Spatie laravel-permission | gleich | +| 2FA | TOTP über Fortify (intern Google2FA), Wiederherstellungscodes | gleich; Pflicht für alle noch offen | +| Passkeys | WebAuthn über Fortify | ergänzt | +| API-Authentifizierung | – | Sanctum vorerst nicht nötig (keine eigene API) | +| Verschlüsselung sensibler Werte | Verschlüsselte Casts, u. a. für Zugangsdaten der KI-API | gleich | +| Transport | HTTPS/TLS | gleich | +| Formularschutz | CSRF, serverseitige Validierung | gleich | +| Protokollierung | Verwaltungsaktionen (Upload, Rechte, Freigaben) und technische Logs | gleich | +| Geheimnisse im Code | gitleaks als Pre-Commit-Hook | ergänzt | +| Keine externen Ressourcen | Test prüft alle Seiten auf fremde Hosts | ergänzt (Vorgabe „alles lokal“) | + +Rechte werden an den Zugriffswegen und an den auslösenden Aktionen geprüft, zusätzlich bei +Suchtreffern und bevor Inhalte an ein Sprachmodell gehen. + +## 4. Entwicklung und Qualität + +| Baustein | Umsetzung | Vergleich zur Referenz | +|---|---|---| +| Lokale Umgebung | Laravel Sail (Docker in WSL2): PHP 8.5, MySQL 8.4, Meilisearch, Mailpit | ergänzt | +| Tests | Pest 4 auf PHPUnit 12; Tests im PHPUnit-Klassenstil | gleich (Runner ergänzt) | +| Code-Stil | Laravel Pint | gleich | +| Statische Analyse | PHPStan/Larastan Stufe 7 | ergänzt | +| Versionsverwaltung | Git, Gitea (lokal führend, Kunde als Push-Mirror) | gleich | + +## 5. Betrieb (Produktion, geplant) + +Übernommen aus der Referenz: Linux-Server, Nginx, PHP-FPM, Worker unter systemd, Cron für den +Scheduler, Bereitstellungsablauf (Abhängigkeiten, Assets, Migrationen, Caches, Dienste neu laden, +Prüfung), Lebenszeichen von Worker und Scheduler, Überwachung fehlgeschlagener und überfälliger +Jobs. Meilisearch läuft als eigener systemd-Dienst. Sail dient nur der Entwicklung; Versionen von +PHP, MySQL und Meilisearch sind in Entwicklung und Produktion gleich. + +Ergänzt bzw. anders als in der Referenz: + +- **Externe Alarmierung von Anfang an** (z. B. Mail), wenn Worker oder Scheduler ausfallen, + Jobs fehlschlagen oder die KI-API nicht erreichbar ist. +- **Backups verschlüsselt**, bevor sie den Server verlassen (z. B. restic). Speicherort und + Aufbewahrungsdauer legt der Kunde fest. Gesichert werden Datenbank, private Uploads und + Konfiguration; der Meilisearch-Index nicht, er wird aus MySQL neu aufgebaut. +- **Wiederanlauf auf einem Ersatzserver** einmal vollständig testen; Datenverlust und + Wiederanlaufzeit mit dem Kunden festlegen. + +## 6. Bewusste Abweichungen von der Referenz + +| Thema | Referenz | KI-BauIN | Begründung | +|---|---|---|---| +| Livewire | 3 | 4 | Neues Projekt; das Starter-Kit von Laravel 13 baut auf Livewire 4 auf, ein späterer Umstieg entfällt. | +| TallStackUI | 3 | 4 | TallStackUI 3 läuft nur mit Livewire 3; Version 4 setzt Livewire ≥ 4.3 voraus. | +| PHP | 8.4 | 8.5 | Sicherheitsupdates bis Ende 2029 statt Ende 2028. | +| Backups | unverschlüsselt, Hetzner Object Storage | verschlüsselt, Ort nach Vorgabe des Kunden | Vertrauliche Vertragsunterlagen; Vorgabe „alles lokal“. | +| Suche | – | Meilisearch | Hybride Suche und Vektorsuche für die Nachtragsprüfung. | + +## 7. Offene Punkte + +- Ist 2FA für alle Benutzer Pflicht? +- Verlangt die IT des Kunden eine Festplattenverschlüsselung auf der VM? +- Speicherort und Aufbewahrungsdauer der Backups. +- Deutsche Übersetzung der Oberflächentexte (das Starter-Kit liefert englische Texte). + +## Architekturübersicht + +```mermaid +flowchart LR + Browser[Oberfläche] --> Nginx[Nginx / HTTPS] + Nginx --> PHP[PHP-FPM] + PHP --> App[Laravel / Livewire / Services] + App --> DB[(MySQL)] + App --> Files[Privater Dateispeicher] + App --> Search[(Meilisearch)] + App --> Queue[Datenbank-Warteschlange] + Queue --> Worker[Worker unter systemd] + Worker --> KI[KI-API des Kunden: OCR, Embeddings, Reranker] + Worker --> DB + Worker --> Search + Cron[Cron] --> Scheduler[Laravel Scheduler] + Scheduler --> Queue + Health[Statusprüfung und Alarmierung] --> Worker + Health --> Scheduler + Backup[Verschlüsselte Sicherung] --> Storage[Speicherort nach Vorgabe des Kunden] +```