Gardomatic/doc/planung.md

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.