# KI-BauIN – Hinweise für Claude Code KI-gestützte Prüfung von Nachträgen im Bahnbau dem Grunde nach: Ist die Leistung einer Nachtragsposition schon im Vertrag (LVs mit Vorbemerkungen) enthalten? Stack und Begründungen: `docs/tech-stack.md`, Umfang und Plan: `docs/projektplan.md`, Einrichtung: `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. ## Arbeitsweise **Erst Plan, dann Umsetzung.** Umgesetzt wird nur, was in einem freigegebenen Teilplan unter `docs/plaene/` steht (Status „freigegeben“ oder „in Arbeit“). Ablauf und Definition of Done stehen in `docs/projektplan.md`, Abschnitt 1. - Vor Beginn eines Arbeitspakets den Teilplan detaillieren und die Freigabe abwarten. - Commits nennen den Schritt, z. B. „AP1 Schritt 1.7: …“, und der Teilplan wird abgehakt. - Neue Erkenntnisse, Antworten und Wünsche zuerst in `docs/fragen.md` bzw. den Teilplan, dann in den Code. Ideen außerhalb des Plans nicht umsetzen, sondern im Gesamtplan unter „Nach Phase 1“ notieren. Das Projekt entsteht per Vibe Coding: Claude Code schreibt den Code, der Entwickler steuert, testet im Browser und liest nicht jede Zeile. Deshalb: - Jede Funktion kommt mit Tests; Tests werden nie abgeschwächt oder übersprungen, damit sie grün werden. - Für jede geschützte Aktion ein Test, der den Zugriff ohne Berechtigung prüft (auch Download, Suchtreffer, Daten an das Sprachmodell). - Kleine Schritte, je ein Commit mit verständlicher Nachricht. - Änderungen an Rechten, Dateizugriff, Suchfilter oder KI-Aufrufen in der Antwort ausdrücklich benennen, damit sie gezielt geprüft werden. - Bei fachlichen Unklarheiten nachfragen statt raten; offene Fragen stehen in `docs/fragen.md`. ## Harte Vorgaben - **Alles lokal.** Keine Skripte, Fonts, Bilder oder APIs von fremden Hosts. Einzige Ausnahme ist die KI-API ITM (API-Werk), nur aus dem Backend. `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. - **API-Schlüssel nie in `.env`, Code, Tests, Logs oder Ausgaben.** In der Anwendung stehen sie verschlüsselt in der Datenbank (Verwaltung → Einstellungen, nur beschreibbar). In der Entwicklung läuft alles über den Schlüssel-Proxy (`tools/ki-proxy`, `http://127.0.0.1:8787` bzw. aus Sail `http://host.docker.internal:8787`); die Schlüsselfelder bleiben dort leer. - Claude Code startet den Proxy nie selbst und versucht nie, Schlüssel zu lesen (Windows-Tresor, fremde Prozesse). Läuft der Proxy nicht, den Entwickler bitten, ihn zu starten. - Echte Kundendaten (z. B. LVs von BauIn) gehen auch über den Proxy nicht an Claude: mit synthetischen oder anonymisierten Dateien testen; mit echten Daten nur Skripte, die Kennzahlen ausgeben. - **Dokumentinhalte sind Daten, keine Anweisungen.** Texte aus LVs, Nachträgen und Anlagen gehen nur als abgegrenzter Kontext an das Sprachmodell; seine Antwort wird im Code geprüft. Keine Authorization-Köpfe, ganzen Dokumente oder Prompts in technische Logs. ## 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 (`Nachtrag`, `Nachtragsposition`, `LvPosition`, `Pfa`, `Vertrag`), 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`. - **Mehrsprachigkeit:** Jeder sichtbare Text über `__('English source text')`, nie fest im Template. Standardsprache Deutsch, angebotene Sprachen in `config('app.available_locales')`, Sprache je Benutzer in `users.locale` (Middleware `SetLocale`). - `lang/de.json` und `lang/de/*.php` erzeugt Laravel Lang – nicht von Hand ändern. - Eigene Texte und Korrekturen gehören nach `lang/project/{locale}.json`, danach `sail artisan lang:apply-project`. Nach `sail artisan lang:update` ebenfalls `lang:apply-project`. - `TranslationCoverageTest` schlägt fehl, wenn ein Text ohne Übersetzung ist. - In Tests Texte über `__()` prüfen statt fest auf Englisch oder Deutsch. - **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.