mvp

docs/hauspilot-domain.md

@@ -0,0 +1,215 @@
+# HausPilot-Fachmodule
+
+## MVP-Abschluss 2026-07
+
+### Neue Migration und Datenmodelle
+
+`1720000005000-AddMentionsAndReminders.ts` ergänzt `task_comment_mentions`, `reminder_deliveries` und `applied_project_templates`. Eindeutige Constraints deduplizieren Benutzer pro Kommentar, Reminder-Schlüssel sowie Vorlagen je Projekt und Ziel. Die Tabellen referenzieren weiterhin ausschließlich bestehende Benutzer- und Projekt-UUIDs.
+
+### Listen-API
+
+Räume, Aufgaben, Meilensteine, Ausgaben, Dokumente, Kommentare und Aktivitäten liefern serverseitig `{ items, page, pageSize, totalItems, totalPages }`. `pageSize` ist auf 100 begrenzt. Filter enthalten stets `projectId`. Sortierfelder sind DTO-Whitelists und werden nie als frei übergebener SQL-Ausdruck ausgeführt. Aufgaben unterstützen Suchtext, mehrere Statuswerte, Priorität, Raum, Verantwortlichen, Kategorie, Datumsbereiche, überfällig, blockiert, nicht zugewiesen und „nur meine“. Ausgaben und Dokumente besitzen Zuordnungs- und Datumsfilter.
+
+Neue gezielte Leseendpunkte sind `GET /projects/:projectId/tasks/:taskId` und `GET /projects/:projectId/calendar?from=YYYY-MM-DD&to=YYYY-MM-DD`. Die stabile Angular-Route `/projekte/:projectId/aufgaben/:taskId` enthält Stammdaten, Schnellstatus, Checkliste, Vorgänger und Nachfolger, Kommentare, Erwähnungen, Dokumente und den Aktivitätsauszug. Der Zeitplan bietet eine responsive Monats- und Agendaansicht ohne neue UI-Bibliothek und lädt nur den benötigten Zeitraum.
+
+### Vorlagen
+
+Die unveränderlichen Systemvorlagen „Reihenhaus-Renovierung“, „Schlüsselübergabe“, „Renovierung eines Raums“ und „Umzug“ werden transaktional kopiert. Die Reihenhausvorlage enthält fünf Bereiche, 15 Räume, 13 Budgetkategorien, Meilensteine und allgemeine Aufgaben. Die Raumvorlage erzeugt 14 Aufgaben samt Abhängigkeitskette. `applied_project_templates` erkennt Wiederholungen je Projekt und Zielraum; erneute Anwendung verlangt `confirmDuplicate`. Fehler rollen alle Kopien und die Aktivität gemeinsam zurück.
+
+### Strukturierte Erwähnungen
+
+Kommentare übertragen neben sichtbarem `@Anzeigename` eine validierte Liste stabiler Benutzer-UUIDs. Nur aktive Mitglieder desselben Projekts werden akzeptiert. Mehrfachnennungen werden dedupliziert, Selbst-Erwähnungen erzeugen keine Nachricht und beim Bearbeiten werden nur neu hinzugekommene Benutzer benachrichtigt. Die In-App-Nachricht verweist direkt auf Aufgabe und Kommentar.
+
+### Scheduler und Reminder
+
+Der offizielle Nest-Scheduler führt den `ReminderService` standardmäßig alle 15 Minuten aus. Er erfasst bald fällige und überfällige Aufgaben, Meilensteine, überfällige offene Ausgaben sowie bald ablaufende Einladungen mit bekanntem Benutzer. Entfernte oder global deaktivierte Mitglieder erhalten nichts. `reminder_deliveries.dedupe_key` enthält Reminder-Art, Entität, Empfänger und Bezugsdatum; der Unique Constraint schützt auch parallele Läufe. Eine Datumsänderung erzeugt einen neuen fachlich relevanten Schlüssel.
+
+- `REMINDER_INTERVAL_MS`: mindestens 60.000, Standard 900.000
+- `REMINDER_DUE_SOON_DAYS`: Standard 3
+
+### Development-Seed
+
+Nach Migrationen und mindestens einem vorhandenen aktiven SSO-Benutzer wird der ausschließlich explizite Seed gestartet:
+
+```text
+npm run seed:development
+```
+
+Er erzeugt idempotent „Umzug Reihenhaus“ mit fünf Etagen, 15 Räumen, 30 Aufgaben, zehn Abhängigkeiten, 20 Checklistenpunkten, zehn Kommentaren, acht Meilensteinen, 13 Budgetkategorien, 15 Ausgaben, vier Dokumentmetadaten, 20 Aktivitäten, In-App-Benachrichtigungen und – sofern vorhanden – bis zu vier bestehende Benutzer in unterschiedlichen Rollen. Er legt weder Benutzer noch Passwörter an. In `NODE_ENV=production` verweigert er Ausführung und Reset. Der gezielte Reset entfernt nur das eindeutig markierte Seed-Projekt:
+
+```text
+npm run seed:development -- --reset
+```
+
+Seed-Dokumente enthalten absichtlich nur Metadaten, keine fingierten Binärdateien.
+
+### Abhängigkeitssicherheit und Grenzen
+
+Die produktiven Advisories wurden ohne Major-Upgrade geschlossen: `@nestjs/swagger` 11.4.6 und TypeORM 0.3.31 beheben die gemeldeten transitiven Risiken in `js-yaml`, `lodash`, `path-to-regexp` und TypeORM. `npm audit --omit=dev` meldet danach keine bekannte Schwachstelle. `@nestjs/schedule` 6.1.3 (MIT, Nest-10/11-kompatibel) ist die einzige neue Laufzeitabhängigkeit.
+
+Der Scheduler läuft pro Backend-Instanz; der Datenbank-Constraint macht die Auslieferung mehrfach laufender Instanzen idempotent, ersetzt bei sehr großen Installationen jedoch kein verteiltes Job-Leasing. Komplexe Gantt-, Offline-, E-Mail- und externe Kalenderfunktionen bleiben außerhalb des MVP.
+
+## Ausgangsarchitektur und Wiederverwendung
+
+Die Umsetzung erweitert die bestehende Angular-/NestJS-Anwendung. Globale Anmeldung, OIDC, serverseitige MySQL-Session, CSRF, `PermissionsGuard`, `ProjectAccessService`, `ProjectMembershipEntity`, `NotificationsService` und `ProjectActivityEntity` bleiben die einzigen Mechanismen für Identität, Projektzugriff, Benachrichtigungen und Aktivitäten. Es gibt keine zweite Benutzer-, Login-, Session- oder Projektverwaltung.
+
+Die fachlichen Controller tragen weiterhin `@RequirePermissions(Permission.ProjectsUse)`. Danach prüft `ProjectAccessService` die aktive Mitgliedschaft und die Projektrolle. Jede Unterentität wird zusätzlich mit der Kombination aus `id` und `projectId` geladen. Dadurch reicht weder eine gültige Anmeldung noch eine fremde Entitäts-ID zum Zugriff.
+
+## Datenmodell und Module
+
+`RenovationModule` bündelt die eng zusammenhängende Renovierungsdomäne und besteht aus Controller, Service, Persistence-Repository, Dokumentablage und DTO-Validierung. Die Migration `1720000004000-AddRenovationDomain.ts` ergänzt:
+
+- Gebäude, Etagen und Räume
+- Renovierungsaufgaben, Checklisten, Abhängigkeiten und Kommentare
+- Meilensteine
+- Budgetkategorien und Ausgaben
+- projektbezogene Dokumentmetadaten
+- Projektstatus, Währung und Gesamtbudget-Grundlage
+
+Historische Benutzerbeziehungen verwenden die bestehende interne User-UUID. Beim Entfernen eines Mitglieds werden offene Zuweisungen in derselben Transaktion geleert; abgeschlossene und historische Beziehungen bleiben erhalten.
+
+## API
+
+Die API liegt unter `/api/projects/:projectId` und stellt Listen sowie Create-/Patch-/Delete-Endpunkte für `buildings`, `floors`, `rooms`, `tasks`, `milestones`, `budget-categories`, `expenses` und `documents` bereit. Aufgaben besitzen zusätzlich `checklist`, `dependencies` und `comments`. Weitere gezielte Endpunkte sind:
+
+- `GET /projects/:projectId/dashboard`
+- `GET /projects/:projectId/activities`
+- `GET /templates`
+- `POST /projects/:projectId/apply-template/:templateId`
+- `GET /projects/:projectId/documents/:id/download`
+
+Request-DTOs enthalten weder Ersteller noch handelnde Benutzer. Diese IDs stammen ausschließlich aus dem bestehenden Sessionkontext.
+
+## Rollen
+
+- Eigentümer und Projektadministratoren verwalten die gesamte Struktur, Budgets und Vorlagen.
+- Bearbeiter verwalten Räume, Aufgaben, Checklisten, Kommentare, Ausgaben und Dokumente.
+- Leser können ausschließlich lesen.
+
+Budgetkategorien sind bewusst Eigentümern und Projektadministratoren vorbehalten, weil ihre Änderung den finanziellen Projektrahmen verändert. Globale SSO-Rollen erzeugen weiterhin keine Projektmitgliedschaft.
+
+## Fortschritt und Abhängigkeiten
+
+Die einzige Fortschrittsberechnung liegt in `renovation/progress.ts`: Idee 0, geplant 10, beauftragt 25, in Arbeit 50, blockiert 25, Abnahme 90 und erledigt 100 Prozent. Entfallene Aufgaben werden ausgeschlossen. Das optionale positive Gewicht bildet einen gewichteten Mittelwert; ohne fachliches Gewicht wird `1` verwendet.
+
+Die zentrale Zykluserkennung erweitert den gerichteten Graphen probeweise um die neue Kante und führt eine Tiefensuche mit `visiting`-/`visited`-Mengen aus. Selbstbezüge sowie direkte und indirekte Zyklen werden mit HTTP 409 abgewiesen. Eine Aufgabe ist blockiert, sobald ein zwingender Vorgänger nicht erledigt ist; der Start wird dann serverseitig verhindert.
+
+## Dashboard und Budget
+
+Der Dashboard-Endpunkt berechnet aggregiert Gesamtfortschritt, offene, überfällige, blockierte, kritische, eigene und nicht zugewiesene Aufgaben, Raumstatus, nächste/gefährdete Meilensteine, aktive Mitglieder sowie geplante, tatsächliche, offene und bezahlte Kosten. Handlungsorientierte Hinweise werden serverseitig aus denselben Daten erzeugt.
+
+Geldbeträge werden in MySQL als `DECIMAL` gespeichert und erst für Aggregationen explizit in Zahlen überführt. Stornierte Ausgaben fließen nicht in tatsächliche Kosten ein.
+
+## Optimistische Nebenläufigkeit
+
+Gebäude, Etagen, Räume, Aufgaben, Meilensteine, Budgetkategorien, Ausgaben und Dokumentmetadaten besitzen eine Versionsnummer. Updates verwenden atomar `WHERE id = ? AND project_id = ? AND version = ?` und erhöhen die Version in derselben SQL-Anweisung. Ein veralteter Stand überschreibt daher keine neueren Daten und liefert HTTP 409. Angular zeigt dafür einen konkreten Konflikthinweis und führt keine verlustbehaftete automatische Zusammenführung durch.
+
+## Dokumentablage
+
+Dateien werden nicht öffentlich ausgeliefert. Upload und Download laufen nach Projektzugriffsprüfung über das Backend. Erlaubt sind PDF, JPEG, PNG und WebP bis zum konfigurierten Limit. Endung, MIME-Typ und Dateisignatur müssen zusammenpassen; der Speichername ist eine zufällige UUID und Pfadbestandteile aus dem Client werden nie übernommen. Metadaten liegen in MySQL, Inhalte unter `DOCUMENT_STORAGE_PATH`.
+
+Konfiguration:
+
+- `DOCUMENT_STORAGE_PATH` (Standard `storage/documents`)
+- `DOCUMENT_MAX_FILE_SIZE_BYTES` (Standard 10 MiB)
+
+Für mehrere Backend-Instanzen muss der Pfad als gemeinsames, geschütztes Volume bereitgestellt werden. Virenscanning und objektbasierter Cloud-Speicher sind sinnvolle Produktionsausbaustufen.
+
+## Frontend
+
+Der responsive Projektarbeitsbereich nutzt ausschließlich bestehende Design-Tokens und UI-Komponenten. Die horizontale, tastaturbedienbare Projektnavigation umfasst Übersicht, Räume, Aufgaben, Zeitplan, Budget, Dokumente, Aktivitäten und die bestehende Mitgliederseite. Listen wechseln auf kleinen Displays in Karten; Hauptaktionen benötigen kein Hover.
+
+## Vorlagen und Erweiterbarkeit
+
+Systemvorlagen werden als unveränderliche Definitionen angeboten. Die Raumrenovierung kopiert Aufgaben und Abhängigkeiten; ein vorhandener Aufgabenbestand verlangt eine explizite Duplikatbestätigung. Die Servicegrenze ist für weitere transaktionale Vorlagen vorbereitet.
+
+Spätere Module für Kartons/QR-Codes, Inventar, Lieferanten/Angebote, Materialmengen, Rechnungserkennung, KI-Planung, E-Mail-Erinnerungen und Kalenderintegration können über `projectId`, bestehende Mitgliedschaften, Dokumentreferenzen, Aktivitäten und Benachrichtigungen angebunden werden, ohne Authentifizierung oder Projektzugriff zu duplizieren.
+
+## Tests
+
+Die Verhaltenstests decken insbesondere die gewichtete Fortschrittsberechnung, ausgeschlossene Aufgaben, direkte/indirekte Abhängigkeitszyklen, kombinierte Aufgabenfilter und den Concurrency-Hinweis ab. Bestehende Tests sichern SSO, Projektzugriff, Einladungen, Sessions und Benachrichtigungen weiterhin ab.
+
+## Frühere MVP-Grenzen
+
+Die zuvor fehlenden Vorlagen, strukturierten Erwähnungen und deduplizierten Reminder wurden mit dem oben dokumentierten MVP-Abschluss umgesetzt. Eine Queue wurde dafür bewusst nicht eingeführt.
+
+# Möbel- und Einrichtungsplanung
+
+## AG-Grid-Arbeitsoberfläche
+
+Die Möbelverwaltung nutzt `ag-grid-angular` und `ag-grid-community` 36.0.1 (MIT, Community
+Edition). Registriert wird ausschließlich `AllCommunityModule`. Enterprise-Funktionen wie Row
+Grouping und Master/Detail werden weder importiert noch vorausgesetzt. Bedarfe, Alternativen,
+Bestellungen und Szenarien sind getrennte Grid-Ansichten; die vorhandenen Formulare bleiben für
+die vollständige Detailbearbeitung zuständig.
+
+Listen verwenden die bestehende Page-Antwort (`items`, `page`, `pageSize`, `totalItems`,
+`totalPages`). Bedarfe unterstützen zusätzlich `openDecision` und `overBudget`; die projektweite
+Alternativenliste unterstützt `roomId`, `requirementId`, `status`, `availability`, `favorite`,
+`selected`, `ordered` und `delayed`. Sortierfelder werden im Service gegen Positivlisten geprüft.
+Bedarfsantworten enthalten aggregierte Optionen, Preise, Budgetabweichung, Bestellstatus und
+Lieferdatum. Die Repository-Abfragen laden Optionen gebündelt für die aktuelle Seite.
+
+Inline-Änderungen senden die vorhandene Versionsnummer. Bei Fehlern wird der alte Zellwert
+wiederhergestellt; bei HTTP 409 wird der Serverstand neu geladen und der Konflikt sichtbar gemeldet.
+Favorit und Auswahl verwenden die bestehenden Fachendpunkte. Leser erhalten keine Editoren; die
+serverseitige Projektberechtigung bleibt verbindlich.
+
+Spaltenzustand wird ohne Fachdaten lokal unter Benutzer-, Projekt- und Ansichtsschlüssel gespeichert.
+Die Suche wird um 300 ms entprellt, Row-IDs sind stabile Datenbank-IDs und CSV-Export nutzt die
+Community-Funktion. Auf kleinen Displays gelten eine reduzierte Höhe und die vorhandene
+Dialogbearbeitung für komplexe Eingaben.
+
+Die Möbelplanung ist Bestandteil des vorhandenen `RenovationModule` und verwendet dessen
+`ProjectAccessService`, Dokumentablage, Ausgaben, Aktivitäten und Benachrichtigungen. Ein
+`FurnitureRequirement` beschreibt den Bedarf eines Raums; konkrete Produkte werden als
+`FurnitureOption` gespeichert. `FurnitureScenario` und `FurnitureScenarioSelection`
+kombinieren höchstens eine Alternative je Bedarf zu vergleichbaren Einrichtungsvarianten.
+
+## Preis- und Kostenregeln
+
+Der geplante Gesamtpreis lautet `Einzelpreis × Menge + Versand + Zusatzkosten − Rabatt`.
+Bei vorhandenem Mobiliar entfallen Anschaffungskosten; Umzug und Aufbereitung werden dennoch
+berücksichtigt. Alle persistierten Geldwerte sind `DECIMAL(13,2)` und werden im Backend als
+Strings verarbeitet; die zentrale Berechnung in `furniture-pricing.ts` rechnet in Cent.
+Planwerte stammen aus der ausgewählten Alternative bzw. einem Szenario. Ist-Kosten stammen
+ausschließlich aus nicht stornierten, über `furniture_option_id` verknüpften Ausgaben. Damit
+wird eine Bestellung nicht zugleich als Produktpreis und Ausgabe doppelt gezählt.
+
+## API und Listenmodell
+
+Die Endpunkte liegen unter `/projects/:projectId/furniture-requirements`,
+`/furniture-options`, `/furniture-scenarios`, `/furniture-summary` sowie
+`/rooms/:roomId/furniture-summary`. Bedarfslisten unterstützen `page`, `pageSize` (maximal
+100), `search`, Raum, Kategorie, Status, Priorität, Verantwortlichen, Favorit, Auswahl,
+Bestell-/Lieferstatus und Lieferverzug. Erlaubte Sortierungen sind Name, Raum, Kategorie,
+Preis, Priorität, Status, Lieferdatum, Änderungsdatum und Sortierreihenfolge.
+
+## Auswahl, Szenarien und Nebenläufigkeit
+
+Das Auswählen eines Produkts sperrt die betroffene Alternative und deren Bedarf
+transaktional, prüft die Version, entfernt die bisherige Auswahl und erzeugt eine Aktivität.
+Damit bleibt auch bei parallelen Anforderungen höchstens eine aktive Auswahl bestehen. Bedarfe,
+Alternativen und Szenarien besitzen Versionsnummern; veraltete Änderungen liefern HTTP 409.
+Automatische Szenarien wählen günstigste, bevorzugte (Auswahl, Favorit, günstigste), teuerste
+oder vorhandene Alternativen und können danach manuell verändert werden.
+
+## Dokumente, Ausgaben, Status und Sicherheit
+
+`furniture_option_documents` referenziert ausschließlich geschützte Projektdokumente; es
+existiert keine zweite Dateiablage. Ausgaben können Bedarf und Alternative referenzieren.
+Sämtliche Unterentitäten werden zusätzlich zur authentifizierten Projektmitgliedschaft gegen
+die Pfad-`projectId` geprüft. Leser dürfen lesen und vergleichen; Eigentümer,
+Administratoren und Bearbeiter verwenden die bestehende Projektaktion `edit`.
+Bestellungen speichern Besteller, Nummer und Liefertermin. Teil- und Komplettlieferung sowie
+Verspätung werden ausgewertet. Liefererinnerungen laufen über den vorhandenen Scheduler und
+die bestehende `ReminderDelivery`-Deduplizierung; eine Terminänderung erzeugt durch das Datum
+im Schlüssel eine neue, wiederholte Jobläufe dagegen keine weitere Benachrichtigung.
+
+## Migration und Development-Seed
+
+Migration `1720000007000-AddFurniturePlanning` erstellt die Möbel- und Szenariotabellen und
+ergänzt optionale Expense-Referenzen. Der Development-Seed bleibt produktionsgesperrt und
+legt 16 Bedarfe, 48 Alternativen, drei Szenarien, Favoriten, Auswahlen, Bestellungen, eine
+Lieferung, einen Lieferverzug, sichere Dokumentmetadaten und verknüpfte Ausgaben an. Die
+Etagen des Seeds sind Keller, Erdgeschoss, 1. Stock und Dachboden.