BauIN/docs/projektplan.md

# KI-BauIN – Projektplan Phase 1

Stand: 5. Oktober 2026 (KW 41). Dieses Dokument ist der Gesamtplan. Die Einzelheiten stehen in
den Teilplänen unter `docs/plaene/`, offene Fragen mit Status in `docs/fragen.md`.

## Inhalt

1. [Arbeitsweise](#1-arbeitsweise)
2. [Beteiligte und Zuständigkeiten](#2-beteiligte-und-zuständigkeiten)
3. [Ziel und Umfang](#3-ziel-und-umfang)
4. [Rahmen und Annahmen](#4-rahmen-und-annahmen)
5. [Meilensteine mit Abnahmekriterien](#5-meilensteine-mit-abnahmekriterien)
6. [Arbeitspakete](#6-arbeitspakete)
7. [Zeitplan nach Kalenderwochen](#7-zeitplan-nach-kalenderwochen)
8. [Zulieferungen](#8-zulieferungen)
9. [Risiken](#9-risiken)
10. [Entscheidungen](#10-entscheidungen)
11. [Nach Phase 1](#11-nach-phase-1)
12. [Änderungen an diesem Plan](#12-änderungen-an-diesem-plan)

## 1. Arbeitsweise

Es wird nur umgesetzt, was in einem freigegebenen Teilplan steht.

1. **Teilplan detaillieren:** Vor Beginn eines Arbeitspakets beschreibt Claude Code den Teilplan
   in `docs/plaene/`. Er enthält Ziel, Umfang, Schritte (je höchstens ein Tag), offene Fragen,
   Entscheidungen und Abnahmekriterien.
2. **Freigabe:** Du liest den Teilplan, triffst die offenen Entscheidungen und setzt den Status
   auf „freigegeben“.
3. **Umsetzung in Schritten:** Jeder Schritt endet mit grünen Tests, Pint und PHPStan und einem
   Commit, der den Schritt nennt (z. B. „AP1 Schritt 1.7: …“). Änderungen an Rechten,
   Dateizugriff, Suchfiltern oder KI-Aufrufen nennt Claude Code ausdrücklich.
4. **Abnahme:** Am Ende eines Arbeitspakets prüfst du die Abnahmekriterien im Browser. Danach
   steht der Status auf „erledigt“, und Plan und Fragenliste werden nachgezogen.
5. **Neue Erkenntnisse zuerst in den Plan:** Antworten, neue Wünsche und Probleme kommen zuerst
   in `docs/fragen.md` oder den Teilplan, dann in den Code. Ideen außerhalb des Plans kommen in
   den Abschnitt [Nach Phase 1](#11-nach-phase-1).
6. **Rollierend:** Die nächsten zwei bis drei Wochen sind im Detail geplant, alles Weitere grob.
   Ein Teilplan wird spätestens eine Woche vor seinem Start detailliert.
7. **Rhythmus:** Vor jedem Freitagstermin mit BauIn gibt es einen Statusbericht mit Screenshots.
   Danach werden Antworten und Termine eingepflegt.

**Status eines Teilplans:** grob geplant → detailliert (wartet auf Freigabe) → freigegeben →
in Arbeit → erledigt.

**Definition of Done, für jeden Schritt:**
- Tests sind vorhanden und grün, bei geschützten Aktionen auch ohne Berechtigung.
- Pint und PHPStan Stufe 7 laufen ohne Fehler.
- Sichtbare Texte stehen in `__()` und sind übersetzt.
- Keine externen Ressourcen, keine Geheimnisse, keine echten Kundendaten.
- Doku und Teilplan sind aktualisiert, der Commit ist auf Deutsch.

## 2. Beteiligte und Zuständigkeiten

| Wer | Aufgabe im Projekt |
|---|---|
| **Du** (Entwicklung, Steuerung) | Planung freigeben, entscheiden, im Browser testen, mit BauIn und ITM sprechen, echte Daten auf Staging testen, pushen. Du schreibst selbst keinen Code. |
| **Claude Code** | Teilpläne ausarbeiten, den gesamten Code mit Tests schreiben, Doku, Statusberichte entwerfen. Sieht keine echten Kundendaten und keine API-Schlüssel. |
| **ITM-Entwickler** | KI-API (API-Werk, Modelle, Schlüssel, Grenzen), Aufbau von Staging- und Produktionsserver nach `docs/server-anforderungen.md` |
| **ITM-Projektleitung** | Projektleitung, Abrechnung, Kostenrahmen für BauIn, Server und Gitea |
| **Claude Design** | Oberflächenentwürfe (Prototyp, Designsystem); Übergaben im Format seiner Übergabe, Abschnitt 9 |
| **BauIn – Nachtragsbearbeitung** | Fachliche Fragen, Testdaten, Referenzfälle, Vorlagen, Bewertung im Pilot |
| **BauIn – IT** | Anmeldung, Zugriff, Domain, Datenschutz und Informationssicherheit |

BauIn ist der Endkunde und prüft als Bauüberwachung im Auftrag der DB die Nachträge der
Auftragnehmer dem Grunde nach. Kontakt läuft über Teams, Termine sind freitags.

## 3. Ziel und Umfang

**Ziel von Phase 1:** Für jede Position eines eingereichten Nachtrags zeigt KI-BauIN, ob die
Leistung schon im Vertrag enthalten ist, also in den LVs einschließlich Vorbemerkungen. Dazu
gehören Fundstellen mit Sprung ins PDF, eine Begründung und bei geänderter Leistung die
Bezugsposition. Der Bearbeiter entscheidet; seine Rückmeldungen verbessern die Vorschläge.

**Enthalten:**
- Projekte mit PFA (Abschnitten), Verträgen und Auftragnehmern
- Upload von LVs als X86 und PDF, Import der Positionen und Vorbemerkungen
- LV-Suche über Vertrag, PFA oder Projekt mit Sprung ins PDF
- Nachträge anlegen (Nachtrags-LV, Anschreiben, Anlagen) und Vorprüfung aller Positionen
- Prüfmaske mit Fundstellen, Bezugsposition, Einschätzung, Begründung, KI-Sicherheit, Feedback
- Regeln, Referenzfälle, einstellbare Freigaben
- Ergebnisliste mit Excel-Export
- Rollen und Rechte, vertrauliche Dokumente, Protokoll, Deutsch und Englisch
- Betrieb auf den Servern von ITM: Staging und Produktion, Backups, Alarmierung

**Optional, wenn Zeit und Vorlagen da sind:** Bewertungsmatrix in der Excel-Vorlage der DB (OP1),
Stellungnahme BÜW als Word-Datei (OP2).

**Nicht enthalten** (macht BauIn selbst oder kommt später):
- rechtliche Einordnung, Fristen, § 2 Abs. 8, § 6 Abs. 6, Anordnungen
- Prüfung der Höhe nach (Phase 2)
- Regelwerk mit Chat (Phase 3)
- DOXIS-Anbindung, Österreich

## 4. Rahmen und Annahmen

- **Gliederung:** Projekt → PFA (Planfeststellungsabschnitt) → Vertrag mit einem Auftragnehmer →
  viele LVs; Nachträge gehören zu einem Vertrag. Datenmodell in `docs/datenmodell.md`.
- **Daten:** LVs liegen immer als X86, D86 und PDF vor. Grundlage ist die X86-Datei, das PDF dient
  der Anzeige. Texterkennung über die KI-API braucht es nur für PDFs ohne GAEB-Datei.
- **KI-API ITM** über API-Werk: Dokumentdienst, `embed`, `rerank`, `chat`, `chat-noreasoning`.
  Es gibt keine Webhooks, Ergebnisse werden abgefragt. Grenzen: 120 Anfragen/min je Schlüssel,
  50 MB je Datei. Einzelheiten in `docs/tech-stack.md`.
- **Schlüssel:** In der Entwicklung über den Schlüssel-Proxy (`tools/ki-proxy`), in der Anwendung
  verschlüsselt in der Datenbank, nie in `.env`.
- **Echte Daten:** Entwickelt wird mit öffentlichen bzw. erfundenen GAEB-Dateien und einem
  anonymisierten Beispielablauf von BauIn. Echte Pilotdaten gibt es nur auf den Servern von ITM
  und erst nach der Datenschutzfreigabe (Fragen A19, B6, C2).
- **Aufwand** in deinen Personenwochen (PW, 40 h) mit Claude Code: Kern rund 11 PW, mit Puffer
  13–14 PW, die Optionen je 0,5 PW. Ohne KI-Unterstützung wären es rund 23 PW. Beim
  ITM-Entwickler kommen 1–1,5 PW für die Server dazu.
- **Verfügbarkeit:** rund 30 h pro Woche (≈ 0,75 PW). Bis M4 sind das ≈ 11,25 PW, genau der Kern.
  Empfehlung: in KW 44–51 auf 35–40 h erhöhen, dann passen die Optionen und etwas Reserve.
- **Pause:** KW 52–53 (21.12.2026 – 03.01.2027).

## 5. Meilensteine mit Abnahmekriterien

| | Termin | Abnahmekriterien |
|---|---|---|
| – | Fr 16.10. (KW 42) | Termin BauIn: Statusbericht, Plan, Kostenrahmen (ITM), ★-Fragen besprochen, Liefertermine vereinbart |
| **M1** | Fr 30.10. (KW 44) | Siehe unten |
| **M2** | Fr 20.11. (KW 47) | Siehe unten |
| **M3** | Fr 18.12. (KW 51) | Siehe unten |
| **M4** | Fr 29.01.2027 (KW 4) | Siehe unten |
| Puffer | KW 5–6/2027 | für Verzögerungen bei Zulieferungen oder Import |

**M1 – Grundgerüst** (Demo 30 min, lokal oder auf Staging):
- Ein Administrator legt Benutzer an; Anmeldung mit 2FA funktioniert.
- Ein Projekt wird mit PFA, Verträgen und Mitgliedern angelegt.
- Ein LV-Paket (X86 + PDF) wird hochgeladen; die Paare werden erkannt, das LV wird importiert und
  als Baum mit Vorbemerkungen angezeigt.
- Ein Benutzer ohne Projektrecht sieht nichts davon, auch nicht über eine direkte URL (Tests).
- Das Protokoll zeigt Uploads und Rechteänderungen; CI ist grün.
- Das Designsystem aus Claude Design ist angewendet.

**M2 – LV-Suche und erste Vorprüfung** (Prüftermin 60 min, auf Staging):
- Staging bei ITM läuft, der Pilot-PFA ist importiert (nach Datenschutzfreigabe).
- Die LV-Suche findet über Vertrag, PFA oder Projekt und springt im PDF an die Stelle.
- Für die ersten Nachträge liefert die Vorprüfung ohne Sprachmodell Fundstellen je Position.
- Für mindestens 5 Nachträge ist gemeinsam mit BauIn erfasst, ob die richtige Fundstelle unter
  den ersten drei ist.

**M3 – Nachträge durchgängig** (Präsentation 60–90 min):
- Prüfmaske mit Einschätzung „im Vertrag enthalten?“, Bezugsposition und Begründung mit
  anklickbaren Quellen.
- Feedback und Korrektur, Regeln mit Freigabe, Ergebnisliste mit Excel-Export.
- Bewertungsmatrix (OP1), falls die Vorlage rechtzeitig da war.
- Produktionsserver steht.

**M4 – Pilot abgeschlossen** (Abschluss):
- Alle Nachträge des Pilot-PFA sind durchlaufen.
- Kennzahlen liegen vor: richtige Fundstelle unter den ersten drei in X % (Ziel aus Frage A21),
  Prüfzeit je Nachtrag vorher und nachher.
- Produktion mit Backups, Alarmierung und erfolgreichem Restore-Test, Betriebsdoku.
- Entscheidung über Phase 2.

## 6. Arbeitspakete

PW = deine Personenwochen mit Claude Code. Status nach Abschnitt 1.

| AP | Teilplan | PW | Zeitraum | Status | Hängt ab von |
|---|---|---|---|---|---|
| AP0 | [Steuerung, Klärung, Doku](plaene/AP00-steuerung.md) | 0,75 | laufend | in Arbeit | – |
| AP1 | [Fundament: CI, Rechte, Benutzer, Projekte, Upload, Protokoll](plaene/AP01-fundament.md) | 1,25 | KW 40–43 | in Arbeit; Schritte ab 1.5 warten auf Freigabe | A1, A25, B1 |
| AP2 | [Meilisearch-Test](plaene/AP02-meilisearch-test.md) | 0,25 | KW 41 / KW 46 | detailliert, wartet auf Freigabe | Teil 2: Staging, A20 |
| AP3 | [Anbindung KI-API ITM](plaene/AP03-ki-api.md) | 0,5 | KW 42–44 | in Arbeit; Schritte ab 3.2 warten auf Freigabe | C1, C4–C8 |
| AP4 | [Indexierung und LV-Suche](plaene/AP04-indexierung-suche.md) | 1,0 | KW 44–46 | grob geplant | AP2, AP3, AP5, A10 |
| AP5 | [GAEB-Import und PDF-Anzeige](plaene/AP05-gaeb-pdf.md) | 1,25 | KW 41 / KW 43–45 | detailliert, wartet auf Freigabe | A3, A5, A18 |
| AP6 | [Vorprüfung Stufe 1 und Prüfmaske](plaene/AP06-vorpruefung-stufe1.md) | 1,25 | KW 46–47 | grob geplant | AP4, AP5, AP13 |
| AP7 | [Vorprüfung Stufe 2 mit Sprachmodell](plaene/AP07-vorpruefung-stufe2.md) | 1,0 | KW 48–49 | grob geplant | AP6, C6 |
| AP8 | [Regeln, Referenzfälle, Freigaben](plaene/AP08-regeln.md) | 0,75 | KW 49–50 | grob geplant | A23, A24 |
| AP9 | [Ergebnisliste und Export](plaene/AP09-ergebnis-export.md) | 0,25 | KW 50 | grob geplant | A9 |
| AP10 | [Dashboard, Benachrichtigungen, Auswertungen](plaene/AP10-dashboard-auswertungen.md) | 0,5 | KW 47, KW 2 | grob geplant | – |
| AP11 | [Betrieb (unser Teil und ITM)](plaene/AP11-betrieb.md) | 0,5 (+ ITM 1–1,5) | KW 41–44, 50–51, 3 | in Arbeit | C10, B2, B5 |
| AP12 | [Pilot und Messung](plaene/AP12-pilot.md) | 1,5 | KW 1–2/2027 | grob geplant | A20, A21 |
| AP13 | [Designsystem aus Claude Design](plaene/AP13-designsystem.md) | 0,5 | KW 43 | detailliert, wartet auf Freigabe | Stand von Claude Design |
| | **Summe Kern** | **≈ 11,25** | | | |
| OP1/OP2 | [Optionen: Bewertungsmatrix, Stellungnahme](plaene/OP-optionen.md) | je 0,5 | KW 51 / KW 2 | grob geplant | A14, A15 |

Bereits erledigt (KW 40–41):
- Entwicklungsumgebung, Grundgerüst mit TallStackUI und Mehrsprachigkeit
- Server-Anforderungen, Schlüssel-Proxy mit Sperren, gitleaks-Regel
- Datenmodell Kern. Es wurde vor dem Teilplan umgesetzt; das Review steht in AP1, Schritt 1.4.

## 7. Zeitplan nach Kalenderwochen

| KW | Datum | Du + Claude Code | ITM-Entwickler | Kunde / gemeinsam |
|---|---|---|---|---|
| 40 | 28.09.–04.10. | ✓ Umgebung, Grundgerüst, TallStackUI, Mehrsprachigkeit, Doku | – | ✓ Besprechung BauIn (02.10.) |
| 41 | 05.–11.10. | ✓ Server-Anforderungen, Schlüssel-Proxy, Datenmodell; Plan und Teilpläne; Freigaben; Meilisearch-Test Teil 1; GAEB-Test; CI; Rechtekonzept | Server-Anforderungen erhalten; Schlüssel | Fragen raus; Rückmeldung an Claude Design |
| 42 | 12.–18.10. | Rechte und Policies; Benutzer- und Projektverwaltung; Upload; KI-API Schnelltest und Einstellungen; Statusbericht | Staging aufbauen | Aufwand an ITM (14.10.); **Termin BauIn 16.10.** |
| 43 | 19.–25.10. | Antworten einarbeiten, Teilpläne AP4/AP6 detaillieren; GAEB-Import, LV-Ansicht; Protokoll; Designsystem | Staging: Dienste, TLS | neuer Stand von Claude Design |
| 44 | 26.10.–01.11. | PDF-Anzeige mit Sprung; KI-Clients und Jobs; Deploy-Vorlagen; erste Bereitstellung | Staging fertig | **M1 Demo 30.10.** |
| 45 | 02.–08.11. | Indexierung, hybride LV-Suche mit Rechtefilter; Nachtrags-Import | Unterstützung | – |
| 46 | 09.–15.11. | Suchreihenfolge, LV-Suche-Oberfläche; Vorprüfung Stufe 1; Meilisearch-Test Teil 2 | – | Pilotdaten auf Staging (du) |
| 47 | 16.–22.11. | Prüfmaske v3 ohne Sprachmodell, Feedback; Dashboard (Teil 1) | – | **M2 Prüftermin 20.11.** |
| 48 | 23.–29.11. | Sprachmodell: Einschätzung, Bezugsposition, strukturierte Antwort | – | – |
| 49 | 30.11.–06.12. | Begründung mit Quellen; Referenzfälle; Regeln beginnen | – | Demo 04.12. |
| 50 | 07.–13.12. | Regeln und Freigaben; Ergebnisliste, Excel-Export | Produktionsserver | – |
| 51 | 14.–20.12. | OP1 Bewertungsmatrix (falls Vorlage und Stunden); Feinschliff | Produktion fertig | **M3 Präsentation 18.12.** |
| 52–53 | 21.12.–03.01. | Pause | Pause | – |
| 1 | 04.–10.01. | Pilot: alle Nachträge des Pilot-PFA, messen | – | Fachexperte bewertet |
| 2 | 11.–17.01. | Nachschärfen; Dashboard, Auswertungen; OP2 Stellungnahme (falls Stunden) | – | Demo 15.01. |
| 3 | 18.–24.01. | Produktion: Inbetriebnahme, Backups, Alarmierung, Restore-Test | Backups, Restore-Test | – |
| 4 | 25.–31.01. | Auswertung, Übergabe, Doku | – | **M4 Abschluss 29.01.** |
| 5–6 | 01.–14.02. | Puffer | Puffer | – |

## 8. Zulieferungen

| Bis | Von | Was | Für |
|---|---|---|---|
| ✓ 02.10. | ITM | API-Dokumentation | AP3 |
| KW 41 | ITM | API-Schlüssel für die Entwicklung, Antworten Teil C, Preise | AP3, Kostenrahmen |
| KW 41 | BauIn | Antworten auf die ★-Fragen | Teilpläne |
| ✓ KW 41 | wir → ITM | Server-Anforderungen (noch verschicken) | AP11 |
| KW 42 | Claude Design | Neuer Stand nach unserer Rückmeldung: Übergabe und `.dc.html`-Dateien | AP13 |
| 16.10. | BauIn | Matrix-Vorlage (leer und ausgefüllt), Word-Vorlage, anonymisierter Beispielablauf | AP5, AP9, OP1, OP2 |
| KW 43 | BauIn | Entscheidung Rollen, Freigabe-Variante, Anmeldung | AP1, AP8 |
| KW 43 | BauIn, ITM | Datenschutzfreigabe für echte Pilotdaten | M2 |
| KW 44 | ITM | Staging-Server mit Zugang, Domain, Zertifikat | M2 |
| KW 46 | BauIn | Pilotdaten: alle LVs eines PFA (X86 + PDF), nur auf Staging | M2 |
| KW 47 | BauIn | 10–20 abgeschlossene Nachträge mit Ergebnis | AP2, AP12 |
| KW 51 | ITM | Produktionsserver | AP11 |
| KW 51 | offen | Backups: Ziel, Aufbewahrung, Zuständigkeit | AP11 |

## 9. Risiken

| Risiko | Auswirkung | Gegenmaßnahme |
|---|---|---|
| Zulieferungen kommen spät | Pakete verschieben sich | Termine am 16.10. vereinbaren; Unabhängiges vorziehen |
| Datenschutz für echte Daten bleibt offen | Kein realistischer Test, M2 gefährdet | Früh fragen (A19, B6, C2); bis dahin anonymisierte Daten |
| Vibe Coding: Fehler in Rechten oder Suchfiltern fallen nicht auf | Unbefugte sehen vertrauliche Inhalte | Tests ohne Berechtigung sind Pflicht; CI; diese Stellen gezielt im Browser prüfen |
| Claude Code sieht keine echten Daten | Nachschärfen dauert länger | Messskripte mit Kennzahlen; anonymisierte Problemfälle |
| Nur eine Person kennt die Anwendung | Ausfall stoppt das Projekt | Doku, Teilpläne, Tests aktuell halten |
| X86 weicht vom Standard ab | GAEB-Import aufwendiger | Beispieldatei früh (A18); D86 als Rückfall |
| Sprachmodell antwortet unzuverlässig strukturiert | Stufe 2 schwächer | Prüfung im Code; Stufe 1 allein schon nützlich |
| Meilisearch mit 4.096 Dimensionen zu langsam | Suche muss umgebaut werden | Test KW 41; Plan B Qdrant |
| KI-API ausgelastet (120/min gemeinsam) | Wartezeiten | Asynchron, Stapel, Vorrang für Suchanfragen (C8) |
| Excel-Vorlage der DB mit Makros | OP1 schwieriger | Vorlage früh testen |
| Fachexperte wenig verfügbar | Keine Messung | Feste Freitagstermine, Referenzfälle früh |

## 10. Entscheidungen

| Datum | Entscheidung | Wer |
|---|---|---|
| 01.10. | Laravel 13, Livewire 4, TallStackUI 4, PHP 8.5, MySQL + Meilisearch, kein Redis | du |
| 02.10. | Phase 1 nur „dem Grunde nach“, Nachträge statt MKA, Höhe Phase 2, Regelwerk Phase 3 | BauIn, du |
| 02.10. | Team: du + Claude Code (Vibe Coding), ITM-Entwickler für KI-API und Server | du |
| 05.10. | API-Schlüssel im Windows-Tresor mit Schlüssel-Proxy; in der App verschlüsselt in der DB, nie in `.env` | du, ITM |
| 05.10. | Projektrollen in eigener Tabelle, globale Rollen über Spatie (Review in AP1, Schritt 1.4) | Claude Code, Freigabe offen |
| 05.10. | Strukturiertes Vorgehen: nur Umsetzung nach freigegebenem Teilplan | du |

Offene Entscheidungen stehen in den Teilplänen unter „Entscheidungen“.

## 11. Nach Phase 1

- **Phase 2 – Prüfung der Höhe nach:**
  - Preis gegen Bezugsposition und gleiche Leistung in anderen PFAs vergleichen.
  - Auszüge der Urkalkulation und Nachtragskalkulation einbeziehen.
- **Phase 3 – Regelwerk:**
  - Richtlinien der DB (263 PDFs, 743 MB) in die Suche aufnehmen.
  - Interner Chat, der mit PDF, Seite und Stelle zitiert.
- **Weitere Ideen:**
  - Dokumentenmanagement, E-Mail- und DOXIS-Anbindung
  - Österreich (ÖNORM B 2110/B 2118, A 2063)
  - Bauzeitenplan-Analyse, weitere Sprachen
- **Nebenprojekt datenschleuse:** Phase 1–2 muss fertig sein, bevor echte Kundendateien mit Claude
  bearbeitet werden. Sie hilft beim anonymisierten Beispielablauf.

## 12. Änderungen an diesem Plan

| Datum | Änderung |
|---|---|
| 01.10. | Erster Plan (MVP, 2 Entwickler) |
| 02.10. | Nach Besprechung mit BauIn: Umfang, Gliederung, Optionen, Ausbaustufen; Team du + Claude Code; 30 h/Woche |
| 05.10. | Neu gegliedert: Arbeitsweise mit Freigaben, Meilensteine mit Abnahmekriterien, Teilpläne je Arbeitspaket, Fragenliste mit Status in `docs/fragen.md` |