ChristophandClaude Opus 5.5
f62541ff13
tests / ci (push) Canceled after 0s
- Fragenliste: erste Antworten von BauIn und ITM eingetragen, übrige Fragen auf „gestellt“ - Anmeldung mit eigenem Passwort, 2FA später Pflicht; keine E-Mails; Mehrfach-Upload ohne ZIP - Nur Produktionsschlüssel: Tests rufen die echte API nie auf - Stellungnahme BÜW und Österreich in Phase 2; „Vor dem Livegang zu klären“ in AP11 - Claude Design Stand 0.3 abgeglichen (AP13), Prüfmaske v4 in AP6 - Gitea von ITM als Push-Mirror eingetragen Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
149 lines
8.8 KiB
Markdown
149 lines
8.8 KiB
Markdown
# KI-BauIN – Tech-Stack
|
||
|
||
Stand: 2. 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.
|
||
|
||
## Beteiligte
|
||
|
||
- **ITM:** Anbieter der KI-API (über API-Werk: Dokumentdienst mit OCR, Embeddings, Reranker,
|
||
Sprachmodell), Projektleitung und abrechnende Firma. Stellt auch die Server (Staging, Produktion) und den Gitea, auf den das
|
||
Repository gespiegelt wird.
|
||
- **BauIn:** Endkunde. Prüft als Bauüberwachung im Auftrag der DB Nachträge dem Grunde nach.
|
||
Liefert Fachdaten (LVs, Nachträge, Bewertungsmatrizen), stellt den Fachexperten und nutzt das System.
|
||
- „Kunde“ meint in diesem Dokument BauIn; wo ITM gemeint ist, steht ITM.
|
||
|
||
## 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, 2FA, Passkeys; ohne E-Mail-Funktionen (keine E-Mails laut BauIn) | ergänzt |
|
||
| Mehrsprachigkeit | Deutsch (Standard) und Englisch, Sprache je Benutzer; Übersetzungen über Laravel Lang (nur Entwicklung), eigene Texte in `lang/project/` | ergänzt |
|
||
| Vite 8, Node.js/npm | Asset-Build | gleich |
|
||
| Composer | Abhängigkeiten mit Lockfile | gleich |
|
||
| GAEB-Import | LVs und Nachtrags-LVs aus GAEB DA XML (X86); D86 nur als Rückfall | ergänzt |
|
||
| pdf.js (lokal ausgeliefert, kein CDN) | Anzeige der LV- und Nachtrags-PDFs mit Sprung zur Fundstelle | ergänzt |
|
||
| PhpSpreadsheet | Ergebnisliste als Excel; Option: Bewertungsmatrix in der Vorlage der DB | geplant |
|
||
| PHPWord | Stellungnahme aus Word-Vorlage (nur .docx) | Phase 2 |
|
||
| 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 ITM (API-Werk, `https://api-werk.de`) | Dokumentdienst (OCR-Gateway/OpenDataLoader: PDF → Markdown/JSON, asynchron mit Abfrage des Ergebnisses), Modelle `embed`, `rerank`, `chat`, `chat-noreasoning` (OpenAI-kompatibel). Drei Schlüssel, nur im Backend; 120 Anfragen/min je Schlüssel; 50 MB je Datei; keine Idempotenz | ergänzt; Anbindung folgt |
|
||
| Persistenter Ereigniseingang mit HMAC-Prüfung | – | nicht nötig: API-Werk meldet nicht per Webhook, Ergebnisse werden abgefragt |
|
||
| 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; zunächst freiwillig, später Pflicht per Schalter |
|
||
| 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 |
|
||
| Schlüssel der KI-API | Nie in `.env`: verschlüsselt in der Datenbank, in der Oberfläche nur beschreibbar; in der Entwicklung Schlüssel-Proxy mit Windows-Anmeldeinformationsverwaltung (`tools/ki-proxy`) | ergänzt |
|
||
| 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, eigene Regel für API-Werk-Schlüssel (`.gitleaks.toml`) | 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 (vor dem Reranking) und bevor Inhalte an ein Sprachmodell gehen. Dokumentinhalte
|
||
sind für das Sprachmodell Daten, keine Anweisungen. Keine Authorization-Köpfe, ganzen Dokumente
|
||
oder Prompts in technischen Logs.
|
||
|
||
## 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; Push-Mirror nach `https://gitea.itm-technologies.de/ChristophGraf/BauIN`) | 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**, wenn Worker oder Scheduler ausfallen, Jobs fehlschlagen
|
||
oder die KI-API ITM nicht erreichbar ist. Die Anwendung verschickt keine E-Mails; der Weg wird
|
||
mit ITM abgestimmt (AP11, E11.3).
|
||
- **Backups verschlüsselt**, bevor sie den Server verlassen (z. B. restic). Speicherort,
|
||
Aufbewahrungsdauer und Zuständigkeit sind noch offen. 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 BauIn und ITM 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 noch offen | Vertrauliche Vertragsunterlagen; Vorgabe „alles lokal“. |
|
||
| Suche | – | Meilisearch | Hybride Suche und Vektorsuche für die Nachtragsprüfung. |
|
||
|
||
## 7. Offene Punkte
|
||
|
||
Vor dem Livegang zu klären (Liste in `docs/plaene/AP11-betrieb.md`): Zugriff, Adresse, Backups,
|
||
Datenschutz und Informationssicherheit, Einschalten der 2FA-Pflicht. Server, Verschlüsselung und
|
||
Datenverarbeitung bei API-Werk sind Sache von ITM.
|
||
|
||
- Weitere Sprachen über Deutsch und Englisch hinaus (technisch vorbereitet, fachlich nicht angefragt).
|
||
|
||
Geklärt am 05.10.: eigenes Passwort statt Microsoft-Konto, 2FA zunächst freiwillig und später
|
||
Pflicht, keine E-Mails, nur Schlüssel für die Produktion.
|
||
|
||
## 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 ITM über API-Werk: OCR, Embeddings, Reranker, Sprachmodell]
|
||
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 noch offen]
|
||
```
|