Architektur und Entwicklung
Diese Übersicht richtet sich an Personen, die die Terminverwaltung ändern oder warten. Für Einrichtung und tägliche Nutzung siehe Nutzung, für Konfiguration und Datensicherung Betrieb und für die Endpunkte die HTTP-Schnittstelle.
Überblick
Die Anwendung ist ein einzelner Go-Prozess mit eingebettetem Browser-Frontend. Externe Kalender-Feeds sind die führende Quelle für importierte Termine; Mitglieder, Berechtigungen und Rückmeldungen werden lokal verwaltet. Daneben können lokale Termine direkt angelegt, bearbeitet oder aus festgelegten Abstimmungen übernommen werden. Der Server liest ICS-, jCal-, xCal-, RSS-, JSON- und CSV-Feeds sowie einen Teilumfang von Schema.org-JSON-LD, gleicht sie mit dem lokalen Zustand ab und stellt gefilterte Termine über HTTP und eigene Kalenderabos bereit. Er schreibt keine Termine an den Anbieter zurück.
Kalenderanbieter -- HTTPS/Feeds --> Abgleich und Formatparser
|
Browser <-- HTML, CSS, JS und JSON --> HTTP-Server <--> Anwendungszustand
Kalender-App <------- eigene Feeds --------| |
tinySQL-Snapshot
Der Prozess startet den HTTP-Server, einen Hintergrundabgleich und die Sicherungsrotation. Der Server ergänzt das HTML um sitzungsunabhängige Linkvorschauen (internal/server/share_pages.go); geschützte Terminangaben werden dabei auch mit Verwaltungscookie ausgeschlossen. Das Frontend besteht aus HTML, CSS und JavaScript und wird beim Go-Build eingebettet; es braucht keinen eigenen Build-Schritt oder separaten Webserver. Die Oberfläche unterstützt Deutsch und Englisch; die Anzeige von Uhrzeiten verwendet die Zeitzone des Browsers.
Wegweiser durch den Code
| Pfad | Aufgabe |
|---|---|
cmd/terminverwaltung/ |
Einstiegspunkt, Konfiguration, Serverstart, Offline-Kommandos und Sicherungen |
internal/config/ |
Laden der .env-Datei |
internal/core/ |
Zustandsmodell, Validierung, Sichtbarkeit und Berechtigungsregeln |
internal/persist/ |
tinySQL-Speicherung, Transaktionen und Prozesssperre |
internal/ical/ |
HTTPS-Feedabruf, Formatparser und Auflösung von Serien; Details in der ICS-Dokumentation |
internal/server/ |
HTTP-Routing, Konten, Verwaltung, Termine, Kalenderausgabe und Synchronisierung |
web/ |
Eingebettete Benutzeroberfläche und QR-Code-Erzeugung |
tests/ |
Frontend-, QR- und Release-Smoke-Tests |
docs/ |
Anleitungen, API-Übersicht und historischer Prüfbericht |
Zustand und Berechtigungen
core.State enthält Mitglieder, Gruppen, Kalender, Termine, Rückmeldungen, Sitzungen, Einrichtungszugänge und Einstellungen. Zusätzliche Gruppen werden im Backend definiert. Ein Kalender hat genau eine Zielgruppe. Öffentliche Kalender sind für alle sichtbar, all für aktive Mitglieder; die weiteren Gruppen erfordern die jeweilige Mitgliedschaft. Die Administration sieht alle aktiven Kalender. Ein Leitungsrecht für Rückmeldungen wird separat vergeben; für öffentliche Kalender gilt dafür die Leitungsgruppe all. Mitglieder sehen in Terminlisten nur ihre eigene Antwort. Eine Antwort ist nur möglich, wenn der Kalender Rückmeldungen erlaubt, der Termin sichtbar und weder abgesagt noch ungeklärt ist und die Frist noch läuft.
Eine Rückmeldung gehört zu einem Termin und einem Mitglied und trägt die Terminrevision. Der Abgleich erhöht diese Revision bei Änderungen von Beginn, Ende, Ort oder Status. So können bestehende Antworten nach relevanten Änderungen erneut bestätigt werden. Titel- und Beschreibungskorrekturen erhöhen die Revision nicht.
Beim ersten Start wird über ein Einrichtungstoken ein Administrationskonto angelegt. Die Administration meldet sich mit einem Passwort an; Mitglieder erhalten einmalige Zugangslinks für ihre Geräte. Widerruf oder Deaktivierung entwertet die betreffenden Sitzungen, offenen Zugangslinks und persönlichen Abos. Einzelheiten und Laufzeiten stehen in der Nutzungsanleitung.
Kalenderabgleich
Aktive Quellen werden beim Start und danach standardmäßig alle fünf Minuten sowie auf Wunsch manuell abgeglichen. Standardmäßig reicht der Zeitraum von 90 Tagen vor dem Abruf bis 18 Monate danach. Intervall und Zeitraum sind in der Verwaltung einstellbar. Kalender-ID und stabiler Quellschlüssel bestimmen die lokale Termin-ID. Die Oberfläche meldet einen überfälligen Stand nach dem größeren Wert aus 30 Minuten und dem Doppelten des eingestellten Abgleichintervalls; gemeldete Abruffehler erscheinen sofort. Fehlt ein Termin innerhalb des Abgleichfensters im Feed, wird er als ungeklärt markiert, nicht automatisch abgesagt. Abruf- und Importfehler erhalten den bisherigen Terminbestand und werden am Kalender angezeigt.
Lokale Kalender sind mit Calendar.Local gekennzeichnet, haben keine Quelladresse und werden vom Abgleich ausgelassen. Die Übernahme einer Abstimmung erstellt Kalender und Ereignis bei Bedarf atomar und speichert Poll.EventID. Ein stabiler Quellschlüssel poll:<Abstimmungs-ID> und die gespeicherte Verknüpfung verhindern Duplikate bei Wiederholung. Zielgruppe und Leitungsrecht werden serverseitig geprüft; die Übernahme überträgt keine Stimmen in Responses. Eine übernommene Auswahl bleibt geschlossen. Das Entfernen einer Abstimmung entfernt nicht deren Kalendertermin. Lokale Statusänderungen erhöhen bei tatsächlichen Wechseln die Ereignisrevision; damit greift dieselbe erneute Rückmeldebestätigung wie bei importierten Änderungen.
Direkt angelegte lokale Termine verwenden local:<Termin-ID> als Quellschlüssel. Der Editor hält Kalender, Status und Sichtbarkeit fest und verwendet Updated als exakten Konkurrenzschutz. Die RSVP-Revision bleibt bei Titel-/Beschreibungskorrekturen erhalten; materielle Änderungen erhöhen sie. So können parallel geöffnete Formulare keine neueren Änderungen überschreiben, ohne jede Textkorrektur zur erneuten Teilnahmebestätigung zu machen. Ganztägige Datumsbereiche werden serverseitig in ihrer expliziten Zone in Mitternachtszeitpunkte übersetzt; der Browser zeigt das Enddatum einschließlich, die API verwendet es exklusiv. Unveränderte Uhrzeitfelder behalten beim Bearbeiten den ursprünglichen UTC-Zeitpunkt, damit die doppelte Stunde der Herbstumstellung nicht versehentlich verschoben wird.
Lokale Serien speichern ihre Vorgaben als EventSeries in State.Series. ExpandLocalSeries erzeugt einen endlichen Plan mit maximal 200 Vorkommen und fünf Kalenderjahren Laufzeit. Die Kalenderarithmetik erfolgt über bürgerliche Datumswerte und die explizite Serienzeitzone; nicht existierende Uhrzeiten sowie fehlende Monatsdaten werden übersprungen. Ganztägige Serien zählen Kalendertage, zeitgebundene Serien behalten die verstrichene Dauer. Snapshotprüfungen validieren Regel, Kalenderbindung und sämtliche Verweise zwischen Serie und Vorkommen; ältere Snapshots benötigen kein Serienfeld.
Jede Position hat einen stabilen Schlüssel series:<Serien-ID>:<Index>. Die Termin-ID wird deterministisch aus Serien-ID und Index gebildet. Die Serienbearbeitung erzeugt den neuen Plan atomar und gleicht Positionen anhand ihres Index ab. Einzeländerungen werden als SeriesException erhalten, sofern nicht ausdrücklich das Zurücksetzen gewählt wird. Außerhalb des neuen Plans liegende Positionen werden als SeriesRetired abgesagt und behalten ihre Antworten. Spätere Erweiterungen können ihre Identität wiederverwenden. Die Serien-ID und Position bleiben beim Verschieben eines Vorkommens unverändert; materielle Änderungen verlangen eine neue RSVP-Bestätigung.
Der Serienzeitstempel dient als Konkurrenzschutz und wird auch bei Änderungen an einzelnen Vorkommen fortgeschrieben. Ganze Serienänderungen und Serienstatusaktionen prüfen ihn unter derselben Datenänderung wie die erzeugten Termine. Der Browser arbeitet bei der Serienbearbeitung mit der gespeicherten Serienzeitzone und kann geänderte Uhrzeiten als startLocal/endLocal übermitteln. In den Ausgaben bleiben die materialisierten Vorkommen eigenständige Ereignisse mit stabilen UIDs. Das hält die bisherigen Ausgabeformate und die Behandlung von Absagen konsistent; Antworten werden weder exportiert noch zwischen Positionen kopiert.
Überschneidungen verwenden einen pro Anfrage aufgebauten Index ausschließlich sichtbarer, bestätigter und nicht ungeklärter Termine. Der Index liefert pro Vorschlag eine Gesamtzahl und maximal fünf Details. Er enthält keine Antworten und wird nicht an Gäste ausgegeben. Kalenderverknüpfungen werden nur bei bestehender Sichtbarkeit ausgegeben. Ursprüngliche Vorschläge und Stimmen bleiben beim Bearbeiten eines übernommenen Termins historisch erhalten; aktuelle Titel-, Zeit-, Orts- und Statusangaben werden zusätzlich im Gastzugang angezeigt. Die spätere Kalenderbeschreibung wird Gästen nicht ausgegeben.
Der Abruf akzeptiert HTTPS- und webcal-Feedadressen öffentlich erreichbarer Anbieter; webcal wird über HTTPS abgerufen. Höchstens fünf HTTPS-Weiterleitungen sind erlaubt. DNS-Antworten werden geprüft und die Verbindung an eine geprüfte öffentliche IP-Adresse gebunden; Proxys und private Netzwerkziele sind ausgeschlossen. Nicht unterstützte oder fehlerhafte Seriendaten lassen den gesamten Abruf scheitern, damit kein unvollständiger Stand veröffentlicht wird. Unterstützte Regeln und Grenzen sind in internal/ical/README.md beschrieben.
Speicherung und Änderungen am Datenmodell
Der vollständige Zustand liegt im Arbeitsspeicher und als JSON-Snapshot in der tinySQL-Tabelle snapshots in terminverwaltung.db. core.DB.Change kopiert den Zustand, führt die Änderung aus und validiert den gesamten Snapshot. Erst nach erfolgreichem Speichern in einer Transaktion wird der neue Zustand im Arbeitsspeicher übernommen. Eine Prozesssperre verhindert das gleichzeitige Öffnen desselben Datensatzes. Das Modell ist für einen Prozess und begrenzte Datenmengen gedacht; der Snapshot darf höchstens 16 MiB groß sein.
Das Schema heißt terminverwaltung/v1. Die Validierung in internal/core/db.go prüft unter anderem Referenzen, Formate und Obergrenzen. Änderungen an gespeicherten Feldern müssen deshalb mit Validierung, Tests und gegebenenfalls einer ausdrücklich implementierten Migration abgestimmt werden. Beim Start und Restore werden Snapshots des Vorgängers ff-ettling-lite/v1 ausdrücklich migriert; andere frühere tinyTreff-Formate werden nicht automatisch übernommen. Sicherungen enthalten vertrauliche Daten im Klartext; Vorgehen und Wiederherstellung stehen in Betrieb.
Lokal entwickeln und prüfen
Voraussetzungen sind Go ab der in go.mod angegebenen Version und Node.js für die Frontend-Tests. Die Go-Abhängigkeiten müssen verfügbar sein. Im Projektverzeichnis:
make run # Server aus den Quellen starten
make build # Programm nach bin/terminverwaltung bauen
make test # Go-Tests
make check # Go-Tests mit Race Detector, go vet und Frontend-Tests
make ohne Ziel zeigt die verfügbaren Befehle. Einzelne Prüfungen lassen sich über make test-go, make test-race, make vet, make check-js und make test-js ausführen. make check kombiniert sie ohne einen zusätzlichen gewöhnlichen Go-Testlauf. Mit make -j check laufen die unabhängigen Prüfungen parallel. Der Race Detector benötigt eine passende native Toolchain einschließlich C-Compiler.
Neue Dateien unter web/*.js werden automatisch auf Syntax geprüft; neue Tests unter tests/*.test.cjs werden automatisch vom Node-Testrunner ausgeführt. GO und NODE lassen sich für andere Programmpfade überschreiben. Beispiele:
make run ARGS='-addr 127.0.0.1:8090 -public-url http://127.0.0.1:8090 -data ./data-dev'
make build BINARY=bin/terminverwaltung-dev
make test-js NODE=node
make build baut mit deaktiviertem CGO und berücksichtigt über den Go-Buildcache auch eingebettete Hilfe- und Browserdateien. make fmt formatiert die Go-Dateien. make clean entfernt ausschließlich das durch BINARY bezeichnete Programm, standardmäßig bin/terminverwaltung; Datenordner und andere Releaseprogramme bleiben erhalten.
Standardmäßig verwendet der Server http://127.0.0.1:8080 und ./data-lite. Für Entwicklungs- und Testdaten einen eigenen privaten Datenordner konfigurieren; nur eine Instanz darf ihn gleichzeitig öffnen. make run verwendet die Quellen, während Start.sh ein vorhandenes lokales bin/terminverwaltung bevorzugt und andernfalls ein plattformspezifisches Releaseprogramm aus bin/ startet. Konfiguration und Offline-Kommandos stehen in Betrieb.
Die Go-Tests liegen bei den jeweiligen Paketen. tests/ui.test.cjs und tests/qr.test.cjs prüfen die Browserlogik; tests/start.test.cjs prüft die Auswahl des Startprogramms; tests/qr_decode.py und tests/release_smoke.py sind zusätzliche, nicht in make check enthaltene Prüfungen mit eigenen Voraussetzungen. Der Prüfbericht beschreibt einen konkreten früheren Teststand und ist kein Nachweis für spätere Änderungen.
Bei Änderungen an HTTP-Endpunkten oder Rechten die API-Übersicht, bei Änderungen an Bedienung oder Betrieb die zugehörigen Anleitungen mitpflegen. Besonders relevant sind Tests für Sichtbarkeit, getrennte Leitungsrechte, vertrauliche Daten, Kalenderabgleich und Wiederherstellung.
Teilen und geschützter Einstieg
chatSource übernimmt Terminangaben über eine Positivliste. Fremde Antworten, Teilnehmerlisten, Quelladressen und geheime Links gelangen nicht in den Nachrichtendialog. chatLink baut ausschließlich gewöhnliche lokale Zieladressen; die aktuelle Browseradresse mit möglichen Geheimnissen wird nicht kopiert. Interne Titel, Zeiten und Orte verlangen eine ausdrückliche Auswahl. Texte werden als Formularwerte gesetzt, nicht als HTML interpretiert.
Der Dialog hält bei gesperrter Zwischenablage den Text zum manuellen Kopieren bereit. Das native Teilen-Menü wird nur angeboten, wenn der Browser es unterstützt. Abbrechen löst keine Ersatzaktion aus. Die Tests in tests/chat_sharing.test.cjs prüfen diese Fälle sowie erlaubte Rückkehrpfade und private Standardtexte; internal/server/share_pages_test.go prüft öffentliche und geschützte HTML-Vorschauen.
Eingebettete Nutzungsanleitungen
docs/embed.go nimmt die bestehenden Markdown-Dateien in das Programm auf. internal/ical/documentation.go ergänzt die verlinkte Parserreferenz. internal/server/help_content.go begrenzt die Auswahl auf einen festen Katalog, rendert mit goldmark und Tabellenunterstützung und erhält deutsche Sprungmarken. Relative Dokumentationslinks werden auf Hilfeadressen umgeschrieben. Rohes HTML, unsichere Linkschemata und nicht eingebettete Bildquellen werden nicht freigegeben.
Der unveränderliche Katalog wird einmal geladen. Für die Anzeige eines Artikels werden Links mit dem erlaubten Empfehlungskontext versehen, ohne den gemeinsamen Katalog zu verändern. internal/server/help.go liefert die Seiten, rollenbezogene Empfehlungen und eine Suche über die Anleitungstexte. Die Hilfe liest keine privaten Termin-, Abstimmungs- oder Antwortdaten für die Darstellung oder Suche. Die öffentliche Organisationsbezeichnung und Akzentfarbe werden wie in der Anwendung verwendet. Der normale Pfadschutz greift vor dem Hilfekontroller.
web/help.html und web/help.css bilden die selbstständige HTML-Ansicht; web/help.js ergänzt ausschließlich den Druckknopf. Die App verwendet gewöhnliche Links mit target="_blank" und rel="noopener noreferrer". Dadurch werden beim Öffnen weder Formulare ersetzt noch Gastschlüssel in neue URLs kopiert. Der Empfehlungshinweis fuer dient nur der Navigation und ist keine Berechtigungsprüfung.
Bei neuen Anleitungen den Katalog und gegebenenfalls die App-Einstiege ergänzen. Inhaltliche Änderungen an den Markdown-Dateien werden beim nächsten Go-Build übernommen. internal/server/help_test.go prüft auch die eingebetteten Querverweise und Sprungmarken; tests/help.test.cjs prüft Rollen, Kontextlinks und die Trennung von persönlichen Schlüsseln. Die Inhalte bleiben in der aktuellen Fassung auf Deutsch; neue Oberflächenbeschriftungen der App sind deutsch und englisch vorhanden.