Initial commit

doc/planung.md

@@ -0,0 +1,121 @@
+# Gardomatic — Projektbeschreibung und Fahrplan
+
+*Planungsstand: 01.09.2026*
+
+## Projektbeschreibung
+
+Gardomatic ist eine mobile, mehrbenutzerfähige Webanwendung zur Organisation von
+Gärten. Nutzer verwalten Gärten, Arten und Sorten, konkrete Pflanzen, Pflanzorte und
+anstehende Arbeiten. Artenbezogene Aufgabenvorlagen erzeugen passend zum Kalender,
+zum Pflanzdatum oder zur letzten Erledigung automatisch konkrete Aufgaben. Ein Garten
+bildet dabei einen abgeschlossenen Daten- und Berechtigungsraum.
+
+Die Anwendung besteht aus einer JSON-API und einem serverseitig gerenderten
+Web-Client in Go. PostgreSQL ist die einzige unterstützte Datenbank. Das Frontend
+ist mobile-first, funktioniert in den wesentlichen Abläufen ohne JavaScript und
+nutzt htmx für komfortable Teilaktualisierungen. Die installierbare PWA bietet eine
+Offline-App-Shell; die eigentlichen Gartendaten bleiben serverseitig geführt.
+
+Gardomatic richtet sich an Einzelpersonen und kleine Gruppen, die einen oder mehrere
+Gärten gemeinsam pflegen. Zeitfenster statt starrer Einzeltermine bilden
+gärtnerische Arbeiten realistisch ab. Rollen, Einladungen und konsequente
+Gartenisolierung ermöglichen eine sichere Zusammenarbeit.
+
+## Verbindliche Leitplanken
+
+- Go mit `internal/`-Layout und getrennten Binaries für API, Web und Administration.
+- PostgreSQL 16 mit `database/sql`, `lib/pq` und versionierten SQL-Migrationen.
+- Garten-ID im Pfad (`/v1/gardens/{gardenID}/...` und `/g/{gardenID}/...`).
+- Fremde Garten-IDs liefern 404; unzulässige Aktionen innerhalb eines sichtbaren
+  Gartens liefern 403.
+- Gartenrollen sind `owner`, `admin`, `member` und `viewer`.
+- Artenstammdaten und konkrete Pflanzen bleiben getrennt; Pflanzen dürfen ohne Art
+  angelegt werden.
+- Aufgaben verwenden Fälligkeitsfenster. Wiederkehrende Zeiträume dürfen den
+  Jahreswechsel überspannen.
+- Aus Vorlagen erzeugte Aufgaben bleiben idempotent. Ein separater Scheduler wird
+  erst bei nachgewiesenem Bedarf eingeführt.
+- Authentifizierung und Autorisierung liegen in der API. Das Web reicht nur das
+  Session-Cookie über einen request-spezifischen API-Client weiter.
+- Neue Facharbeit wird als vollständiger Vertical Slice aus Migration, Storage,
+  API, Client, Web und Tests umgesetzt.
+
+## Weiterer Fahrplan
+
+### 1. Kalenderbereitstellung über CalDAV
+
+**Ziel:** Anstehende Aufgaben können in vorhandenen Kalender- und
+Aufgabenanwendungen abonniert werden.
+
+Vorgeschlagene Umsetzung:
+
+1. Zuerst einen technischen Prototyp mit einer nur lesbaren Collection pro Nutzer
+   und Garten erstellen. Die Collection erhält stabile Ressourcen-IDs, ETags und
+   separat widerrufbare Zugangsdaten.
+2. Aufgaben als `VTODO` abbilden: Titel, Beschreibung, Fälligkeitsfenster,
+   Priorität, Status sowie Pflanzen- und Ortsbezug. Gartenrollen begrenzen auch hier
+   die sichtbaren Daten.
+3. Optional eine schreibgeschützte `VEVENT`-Ansicht für Clients ergänzen, die
+   `VTODO` nicht sinnvoll darstellen. Mehrtägige Fälligkeitsfenster bleiben dabei
+   als Zeiträume erkennbar.
+4. Einrichtung und Widerruf im Benutzerkonto ergänzen und mindestens mit DAVx⁵,
+   Apple Kalender/Erinnerungen und Thunderbird prüfen.
+5. Schreibzugriffe bewusst zurückstellen, bis Konfliktauflösung, Optimistic
+   Locking, Zeitzonen und die Semantik externer Erledigungen festgelegt sind.
+
+**Abnahmekriterien:** Eine gartenbezogene, nur lesbare Collection lässt sich in
+mindestens zwei unterstützten Clients einrichten; Änderungen erscheinen nach der
+Synchronisation; widerrufene Zugänge und Zugriffe auf fremde Gärten funktionieren
+nicht.
+
+### 2. Erstes Erweiterungsmodul: Bewässerung
+
+**Ziel:** Den modularen Ausbau mit einem klar abgegrenzten Anwendungsfall erproben.
+
+Vorgeschlagener Umfang:
+
+1. Bewässerungszonen und deren Zuordnung zu vorhandenen Orten modellieren.
+2. Manuelle Laufzeiten sowie einfache, ausführbare Zeitprogramme bereitstellen.
+3. Tabellen mit `mod_irrigation_` benennen und Routen, Migrationen und
+   Berechtigungsprüfungen vom Kern abgrenzen.
+4. Maximale Laufzeit, konkurrierende Programme und Verhalten bei fehlender
+   Geräteverbindung definieren, bevor reale Ventile angesteuert werden.
+5. Hardware-Anbindung und Wetterautomatik erst nach einer nutzbaren manuellen
+   Planung auswählen. Ein allgemeines Modul-Interface erst einführen, wenn ein
+   zweites Modul tatsächlich gemeinsame Hooks benötigt.
+
+**Abnahmekriterien:** Das Modul kann deaktiviert werden, ohne Kernfunktionen zu
+beeinträchtigen; Planung und manuelle Ausführung sind nutzbar; Sicherheitsgrenzen
+sind automatisiert getestet.
+
+### 3. Aufgabenhistorie und Auswertung
+
+**Ziel:** Wiederkehrende Gartenarbeit später auswertbar machen, ohne den aktuellen
+Aufgabenablauf unnötig zu verkomplizieren.
+
+Vorgeschlagene Umsetzung:
+
+1. Vorab entscheiden, welche Fragen beantwortet werden sollen, beispielsweise
+   Erledigungen pro Zeitraum, Pflanze oder Ort.
+2. Erst danach ein append-only Ereignismodell für Erledigen, Wiederöffnen und
+   Terminänderungen entwerfen.
+3. Einen kompakten Export und wenige zielgerichtete Auswertungen vor komplexen
+   Dashboards priorisieren.
+
+**Abnahmekriterien:** Historische Daten verändern den aktuellen Aufgabenstatus nicht
+und bleiben gartenisoliert; die gewählten Auswertungen sind durch reale
+Nutzerfragen begründet.
+
+## Empfohlene Reihenfolge
+
+1. Als nächstes den lesenden CalDAV-Prototypen umsetzen und früh mit realen Clients
+   testen. Das reduziert das größte technische Kompatibilitätsrisiko.
+2. Danach den CalDAV-Zugang im Benutzerkonto produktionsreif machen und
+   dokumentieren.
+3. Anschließend das Bewässerungsmodul zunächst ohne Hardwareintegration liefern.
+4. Aufgabenhistorie und Reporting erst beginnen, wenn konkrete Auswertungsfragen
+   gesammelt wurden.
+
+Bidirektionales CalDAV, herstellerspezifische Bewässerungshardware und eine
+allgemeine Plugin-Architektur sind ausdrücklich keine Bestandteile der jeweils
+ersten Ausbaustufe.