From 30d80174ac1c1ed9539aea82679e70b9ed104bf3 Mon Sep 17 00:00:00 2001 From: Christoph Date: Thu, 1 Oct 2026 11:33:23 +0200 Subject: [PATCH] Beteiligte festgehalten: KI-API ITM, Endkunde BauIn MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - "KI-API des Kunden" heißt jetzt "KI-API ITM" (Tech-Stack, CLAUDE.md, Projektplan) - ITM: Anbieter der KI-API, Projektleitung, abrechnende Firma; BauIn: Endkunde - Zulieferungen im Projektplan nach ITM und BauIn getrennt; Hosting der VMs noch zu klären Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 2 +- docs/projektplan.md | 48 +++++++++++++++++++++++++++------------------ docs/tech-stack.md | 14 ++++++++++--- 3 files changed, 41 insertions(+), 23 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 41f5662..7c245b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,7 @@ 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. + ist später die KI-API ITM. `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). diff --git a/docs/projektplan.md b/docs/projektplan.md index 633582a..faa7818 100644 --- a/docs/projektplan.md +++ b/docs/projektplan.md @@ -2,6 +2,14 @@ Stand: 1. Oktober 2026 (KW 40). Wird nach dem Kundentermin (KW 42) zum Detailplan geschärft. +## Beteiligte + +- **ITM:** Anbieter der KI-API (OCR, Embeddings, Reranker, ggf. Sprachmodell), Projektleitung und + abrechnende Firma. +- **BauIn:** Endkunde. Liefert Fachdaten (LVs, MKAs, Bewertungsmatrizen), stellt den Fachexperten + und nutzt das System. +- „Kunde“ meint in diesem Dokument BauIn; wo ITM gemeint ist, steht ITM. + ## Rahmen und Annahmen - **Ziel des MVP:** Nachtragsprüfung „dem Grunde nach“ am Pilotprojekt, von der hochgeladenen @@ -14,8 +22,8 @@ Stand: 1. Oktober 2026 (KW 40). Wird nach dem Kundentermin (KW 42) zum Detailpla - **B** (Kollege): Oberfläche mit TallStackUI, GAEB-Import, Betrieb - Mit nur einem Entwickler verdoppelt sich die Dauer ab Phase 2 (siehe Variante unten). - **Pause:** KW 52–53 (21.12.2026 – 03.01.2027). -- **Abhängigkeit:** Viele Pakete brauchen Zulieferungen des Kunden. Kommen sie später als unten - geplant, verschiebt sich der Plan entsprechend. +- **Abhängigkeit:** Viele Pakete brauchen Zulieferungen von ITM (KI-API) und BauIn (Fachdaten, + Fachexperte). Kommen sie später als unten geplant, verschiebt sich der Plan entsprechend. ## Meilensteine @@ -36,12 +44,12 @@ Stand: 1. Oktober 2026 (KW 40). Wird nach dem Kundentermin (KW 42) zum Detailpla |---|---|---|---|---|---| | AP0 | Klärung, Kundentermine, Jour fixe, Dokumentation | 1,0 | A+B | laufend | – | | AP1 | Fundament: Umgebung ✓, Laravel/TallStackUI ✓, Mehrsprachigkeit ✓, CI, Datenmodell (Mandant, Land, Projekt, Los, Dokument), Rollen/Rechte mit Benutzerverwaltung, privater Upload und Download, Protokoll, Länderstruktur | 4,0 (1,0 erledigt) | A+B | KW 40–43 | Rollenmodell (Kunde) | -| AP2 | Meilisearch-Test: Teil 1 mit erzeugten Vektoren, Teil 2 mit echten Vektoren und Referenzfällen | 0,5 | A | KW 41 / KW 46–47 | Teil 2: API-Zugang, Referenz-MKAs | -| AP3 | KI-API-Anbindung: Client für OCR, Embeddings, Reranker (+ LLM), Jobs mit Wiederholung und Status, Überwachung, ggf. Webhook-Eingang | 1,5 | A | KW 44–45 | API-Doku und Testzugang | +| AP2 | Meilisearch-Test: Teil 1 mit erzeugten Vektoren, Teil 2 mit echten Vektoren und Referenzfällen | 0,5 | A | KW 41 / KW 46–47 | Teil 2: API-Zugang (ITM), Referenz-MKAs (BauIn) | +| AP3 | Anbindung KI-API ITM: Client für OCR, Embeddings, Reranker (+ LLM), Jobs mit Wiederholung und Status, Überwachung, ggf. Webhook-Eingang | 1,5 | A | KW 44–45 | API-Doku und Testzugang (ITM) | | AP4 | Dokumentverarbeitung und Suche: OCR → Abschnitte → Embeddings → MySQL + Meilisearch, Neuaufbau des Index, hybride Suche mit Pflichtfilter für Rechte | 2,0 | A | KW 45–47 | AP3 | | AP5 | GAEB-Import (D86/X86): Parser, LV-Baum, Vorbemerkungen, LV-Ansicht, MKA-Import (PDF + GAEB) | 2,5 | B | KW 44–46 | Beispieldateien | | AP6 | Prüfassistent Stufe 1 (ohne LLM): Vergleichspositionen mit Reranker, Prüfmaske, Feedback je Aspekt, Confidence | 2,5 | A+B | KW 48–49 | AP4, AP5 | -| AP7 | Prüfassistent Stufe 2 (mit LLM): Prompts, strukturierte Antwort, Prüfung der Antwort, Begründung mit Quellen | 2,0 | A | KW 50–51 | LLM-Zugang | +| AP7 | Prüfassistent Stufe 2 (mit LLM): Prompts, strukturierte Antwort, Prüfung der Antwort, Begründung mit Quellen | 2,0 | A | KW 50–51 | LLM-Zugang (ITM) | | AP8 | Regeln, Referenzfälle, einstellbare Freigaben, Versionen | 2,0 | B | KW 50–51 | Freigabe-Variante (Kunde) | | AP9 | Bewertungsmatrix, MKA-Status, Freigabe durch Projektleiter, Excel-Export | 1,0 | B | KW 51 | Matrix-Vorlage | | AP10 | Wissensbasis-Oberfläche, Dashboard, Benachrichtigungen, Auswertungen | 1,0 | B | KW 47, KW 2 | – | @@ -58,7 +66,7 @@ Stand: 1. Oktober 2026 (KW 40). Wird nach dem Kundentermin (KW 42) zum Detailpla | 41 | 05.–11.10. | Meilisearch-Test Teil 1; Datenmodell Kern | CI in Gitea Actions; Benutzerverwaltung beginnen | Fragenliste raus, Termin vereinbaren; Claude Design Durchgang 1 | | 42 | 12.–18.10. | Upload, privater Speicher, Download mit Rechteprüfung, Vertraulichkeit | Rollen und Rechte, Projekt-Mitglieder; Design-Feedback | **Kundentermin** + Lauffenburg-Walkthrough | | 43 | 19.–25.10. | Detailplan nach Kundenantworten; Protokoll; Länderstruktur | Designsystem übernehmen (AP13) | **M1 Demo** | -| 44 | 26.10.–01.11. | KI-API-Client, Jobs, Status | GAEB-Parser | – | +| 44 | 26.10.–01.11. | Client KI-API ITM, Jobs, Status | GAEB-Parser | – | | 45 | 02.–08.11. | Überwachung, Webhook-Eingang (falls nötig); Dokumentverarbeitung | GAEB: LV-Baum, Vorbemerkungen, LV-Ansicht | Demo | | 46 | 09.–15.11. | Embeddings → MySQL + Meilisearch; Meilisearch-Test Teil 2 | MKA-Import; Staging einrichten | – | | 47 | 16.–22.11. | Hybride Suche mit Rechte-Filter, Neuaufbau des Index | Wissensbasis-Oberfläche; Staging fertig | **M2 Prüftermin** (erste ~5 Dokumente) | @@ -76,27 +84,29 @@ Stand: 1. Oktober 2026 (KW 40). Wird nach dem Kundentermin (KW 42) zum Detailpla **Variante mit einem Entwickler:** M1 Ende KW 44, M2 Ende KW 51, M3 Ende KW 8/2027, M4 Ende KW 13/2027 (Anfang April). -## Zulieferungen des Kunden (Soll-Termine) +## Zulieferungen von ITM und BauIn (Soll-Termine) -| Bis | Was | Gebraucht für | -|---|---|---| -| KW 41 | Antworten auf die ★-Fragen, Termin, API-Dokumentation, Tech-Stack-Vorgaben | Detailplan, AP3 | -| KW 42 | Beispieldateien (GAEB, MKA als PDF + GAEB, Matrix-Vorlage), Kopie der relevanten Lauffenburg-Dateien | AP5, AP9 | -| KW 43 | API-Testzugang (OCR, Embedding, Reranker; LLM falls vorhanden); Entscheidung Rollenmodell, Freigabe-Variante, 2FA-Pflicht | AP1, AP3, AP8 | -| KW 46 | Staging-VM mit Zugang, Domain und Zertifikat | AP11, M2 | -| KW 47 | 10–20 abgeschlossene MKAs mit Bewertung (Referenzfälle) | AP2 Teil 2, AP12 | -| KW 48 | Kuratierte Wissensbasis (VOB, DB-Richtlinien, Standardleistungstexte, Vorlagen) | AP4, AP7 | -| KW 51 | Produktions-VM, Backup-Ziel und Aufbewahrungsdauer | AP11 | +| Bis | Von | Was | Gebraucht für | +|---|---|---|---| +| KW 41 | ITM | API-Dokumentation der KI-API (OCR, Embedding, Reranker, ggf. Sprachmodell) | AP3 | +| KW 41 | BauIn, ITM | Antworten auf die ★-Fragen, Termin | Detailplan | +| KW 42 | BauIn | Beispieldateien (GAEB, MKA als PDF + GAEB, Matrix-Vorlage), Kopie der relevanten Lauffenburg-Dateien | AP5, AP9 | +| KW 43 | ITM | Testzugang zur KI-API (OCR, Embedding, Reranker; Sprachmodell falls vorhanden) | AP3 | +| KW 43 | BauIn | Entscheidung Rollenmodell, Freigabe-Variante, 2FA-Pflicht | AP1, AP8 | +| KW 46 | klären | Staging-VM mit Zugang, Domain und Zertifikat | AP11, M2 | +| KW 47 | BauIn | 10–20 abgeschlossene MKAs mit Bewertung (Referenzfälle) | AP2 Teil 2, AP12 | +| KW 48 | BauIn | Kuratierte Wissensbasis (VOB, DB-Richtlinien, Standardleistungstexte, Vorlagen) | AP4, AP7 | +| KW 51 | klären | Produktions-VM, Backup-Ziel und Aufbewahrungsdauer | AP11 | ## Risiken | Risiko | Auswirkung | Gegenmaßnahme | |---|---|---| | Zulieferungen kommen spät | Pakete verschieben sich | Soll-Termine früh vereinbaren; vorziehen, was unabhängig ist | -| Kein LLM verfügbar | AP7 entfällt vorerst | Stufe 1 (Suche + Reranker) ist allein schon nützlich; Zeit in AP8/AP10 umschichten | +| ITM bietet kein Sprachmodell an | AP7 entfällt vorerst | Stufe 1 (Suche + Reranker) ist allein schon nützlich; Zeit in AP8/AP10 umschichten | | GAEB 90 (D86) statt XML | GAEB-Import aufwendiger | Beispieldatei früh anfordern; fertige Bibliothek prüfen | | Meilisearch mit 4.096 Dimensionen zu langsam | Suche muss umgebaut werden | Test in KW 41; Plan B Qdrant | -| KI-API ausgelastet | Lange Wartezeiten | Alles asynchron; Priorität für Suchanfragen erfragen; Cache | +| KI-API ITM ausgelastet | Lange Wartezeiten | Alles asynchron; Priorität für Suchanfragen bei ITM erfragen; Cache | | Fachexperte wenig verfügbar | Kein Feedback, keine Messung | Feste Jour-fixe-Termine; Referenzfälle früh anfordern | ## Aufgabenliste (nächste zwei Wochen) @@ -109,7 +119,7 @@ M4 Ende KW 13/2027 (Anfang April). **KW 41** - [ ] Fragenliste an den Kunden schicken, Termin für KW 42 vereinbaren (inkl. Lauffenburg-Walkthrough) -- [ ] API-Dokumentation, Tech-Stack-Vorgaben und Beispieldateien anfordern +- [ ] API-Dokumentation bei ITM, Beispieldateien bei BauIn anfordern - [ ] Claude Design: Durchgang 1 (Designsystem, Layout, Prüfmaske, Regeldialog) - [ ] **Meilisearch-Test Teil 1** (erzeugte 4.096-dim. Vektoren, z. B. 50.000 Stück): Indexierungszeit, Antwortzeit mit Filtern, RAM und Platte; jeweils ohne und mit binärer Quantisierung diff --git a/docs/tech-stack.md b/docs/tech-stack.md index 2a280e2..216f069 100644 --- a/docs/tech-stack.md +++ b/docs/tech-stack.md @@ -4,6 +4,14 @@ Stand: 1. Oktober 2026. Grundlage ist die allgemeine Tech-Stack-Referenz einer b Laravel-Verwaltungsanwendung (Kollegenprojekt). Dieses Dokument übernimmt deren Grundsätze und benennt, wo KI-BauIN bewusst abweicht und warum. +## Beteiligte + +- **ITM:** Anbieter der KI-API (OCR, Embeddings, Reranker, ggf. Sprachmodell), Projektleitung und + abrechnende Firma. +- **BauIn:** Endkunde. Liefert Fachdaten (LVs, MKAs, 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 | @@ -35,7 +43,7 @@ Länderspezifisches (DE/AT) hinter Schnittstellen im Kern, Umsetzungen in `app/L | 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 | +| KI-API ITM | OCR, Embeddings (Qwen3-Embedding-8B), Reranker, ggf. Sprachmodell | 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 | @@ -81,7 +89,7 @@ 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. + Jobs fehlschlagen oder die KI-API ITM 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. @@ -117,7 +125,7 @@ flowchart LR App --> Search[(Meilisearch)] App --> Queue[Datenbank-Warteschlange] Queue --> Worker[Worker unter systemd] - Worker --> KI[KI-API des Kunden: OCR, Embeddings, Reranker] + Worker --> KI[KI-API ITM: OCR, Embeddings, Reranker] Worker --> DB Worker --> Search Cron[Cron] --> Scheduler[Laravel Scheduler]