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.