CLAUDE.md und Tech-Stack-Dokumentation ergänzt

- 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 <noreply@anthropic.com>
2026-10-01 09:35:13 +02:00
parent f1bda604cb
commit cdd2d5b676
4 changed files with 191 additions and 3 deletions
@@ -33,7 +33,6 @@ yarn-error.log
 /.pi
 /.mcp.json
 /AGENTS.md
-/CLAUDE.md
 /boost.json
 /opencode.json
 /opencode.jsonc
@@ -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.
+  - `<x-ts-avatar>` nur mit `text` (Initialen), nie mit `model`, `gravatar` oder Bild-URL –
+    sonst lädt TallStackUI von ui-avatars.com bzw. gravatar.com.
+  - `<x-ts-reaction>` 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-`** (`<x-ts-button>`, `<x-ts-input>`, `<x-ts-modal>` …).
+  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. `<x-heading>`, `<x-subheading>`, `<x-user-menu>`.
+- **Dark Mode** über `tallstackui_darkTheme()` am `<html>`-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.
@@ -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

@@ -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]
+```