group editor implemented

docs/Gruppenbearbeitung.md

@@ -0,0 +1,143 @@
+# Gemeinsam bearbeiten
+
+In „Strecken bearbeiten“ trägt jede Strecke eine Schaltfläche mit zwei Wichteln:
+links der Vogel, rechts der Stein. „Gemeinsam bearbeiten“ legt einen gemeinsamen
+Entwurf auf der Website an. Das Original bleibt unverändert. Bei lokalen Entwürfen
+fragt die App vorher, ob Weg, Stationen, Bilder und Ton übertragen werden dürfen.
+Ein bereits eingesandter eigener Entwurf wird dabei zuerst aktualisiert.
+
+Danach zeigt die App acht Wichtel als Gruppencode. Andere öffnen in der
+Streckenverwaltung „Gruppencode eingeben“ und schieben die Bilder in den acht
+Drehrädern nach oben oder unten. Es zählen die Wichtel in der Mitte, von links
+nach rechts, zuerst in der oberen Reihe. Pfeiltasten und die Pfeilschaltflächen
+funktionieren ebenfalls. „Mitmachen“ öffnet den gemeinsamen Entwurf.
+
+## Arbeiten und Einladungen
+
+- Gemeinsame Entwürfe erscheinen im Bearbeitungsfenster in einer eigenen Liste.
+- Änderungen an Strecke, Stationen, Bildern und Ton werden über die bestehenden
+  Editor-Funktionen direkt auf der Website gespeichert. Internet ist erforderlich.
+- „Änderungen holen“ lädt den aktuellen Stand. Die App fragt vorher, weil dabei
+  noch nicht gespeicherte Eingaben ersetzt werden.
+- Wenn jemand zwischenzeitlich gespeichert hat, weist die App den veralteten
+  Speicherversuch zurück. Die Eingaben bleiben stehen und können vor dem Laden
+  des neuen Stands gesichert werden. Es gibt noch keine automatische Zusammenführung.
+- Der Einladungscode gilt eine Stunde. „Neuen Code anzeigen“ ersetzt ihn; bereits
+  beigetretene Personen behalten ihren Zugang. Nur die eröffnende Person kann das.
+- „Gruppe schließen“ entfernt den Zugang der anderen Personen und den Code.
+  Die eröffnende Person behält ihren Entwurf und kann wieder einen Code erzeugen.
+- Es sind höchstens 50 Zugänge je Gruppe und zwölf gleichzeitig offene Gruppen
+  je eröffnendem Zugang vorgesehen. Fehlerhafte Codeversuche werden begrenzt.
+
+Der Zugang wird mit einem geschützten Sitzungscookie für höchstens 30 Tage
+aufbewahrt. Es wird erst beim Öffnen einer Gruppe oder beim Beitritt angelegt,
+nicht beim bloßen Aufruf der App. Nach Ablauf oder Löschen der Browserdaten muss
+man erneut eingeladen werden. Eine Wiederherstellung des eröffnenden Zugangs
+nach Verlust dieses Cookies ist noch nicht enthalten. Die Gerätekennung allein
+reicht dafür nicht. Wer den Code kennt, kann während seiner Gültigkeit beitreten;
+Codes deshalb nur mit den gewünschten Personen teilen.
+
+## Berechtigungen und Freigabe
+
+Der gemeinsame Entwurf besitzt eine eigene Strecken-ID und eine Erstellerkennung.
+Die eröffnende Person hat zusätzlich die Gruppenverwaltung. Mitbearbeiter ändern
+diese Zuordnung nicht. Die Gerätekennung ist Metadatum; der tatsächliche Zugang
+wird anhand einer geheimen Sitzung und ihrer Gruppenmitgliedschaft geprüft.
+
+Gemeinsame Entwürfe erscheinen nicht in den öffentlichen Streckenlisten. Ihre
+Strecken-, Bild-, Ton- und Wegdateien sind vor der Veröffentlichung nur mit einem
+berechtigten Gruppenzugang abrufbar. Veröffentlichen erfolgt weiterhin durch die
+vorhandene serverseitige Moderation. Eine Freigabe macht die Kopie öffentlich
+und sperrt weitere Änderungen wie bei anderen freigegebenen Strecken.
+
+Das reine Beenden der Gruppe veröffentlicht oder löscht den Entwurf nicht.
+Nicht freigegebene Gruppenmedien benötigen auch bei der Prüfung einen
+Gruppenzugang; der bisherige Nginx-Passwortschutz allein erteilt keine zusätzliche
+Gruppenmitgliedschaft. Betreiber können auf dem Server die Dateien prüfen oder
+sich während der gültigen Einladung beteiligen. Bereits geladene Inhalte können
+beim Schließen einer Gruppe nicht aus fremden Geräten zurückgerufen werden.
+
+## Einspielen auf dem Server
+
+Nach dem Kopieren der Dateien und vor der Startprüfung bzw. dem Neustart:
+
+```bash
+npm run init-db
+npm run test:runtime-db
+systemctl --user restart wegwichtel.service
+```
+
+`init-db` legt die drei neuen STRICT-Tabellen an. Es verändert keine bestehenden
+Streckentabellen und löscht keine Strecken. Eine Neuerzeugung oder das Löschen
+der vorhandenen Datenbank ist hierfür nicht erforderlich.
+
+Die normale Nginx-Weiterleitung an die App muss auch `/api/groups` erreichen.
+HTTPS sowie die vorhandenen Header `Host` und `X-Forwarded-Proto` beibehalten.
+Der Zugriffsschutz in der App muss alle Geräte auf dieselbe SQLite-Datenbank
+und denselben App-Prozess führen. Die zusätzliche Schreibsperre für laufende
+Anfragen gilt pro Prozess; ein verteilter Mehrprozessbetrieb benötigt dafür eine
+gemeinsame Sperrverwaltung. Der vorhandene systemd-Betrieb mit einem Prozess ist
+unterstützt. `X-Real-IP` wird zur Begrenzung falscher Codeversuche nur bei einem
+lokalen Reverse Proxy ausgewertet und muss dort mit der tatsächlichen Client-IP
+überschrieben werden.
+
+## Stationen sperren und Änderungen aufbewahren
+
+Beim Öffnen einer gemeinsamen Station übernimmt das Gerät ihre Bearbeitung.
+Ist sie bereits geöffnet, fragt die App, ob die Bearbeitung übernommen werden
+soll. Erst die Bestätigung ersetzt die bisherige Sperre. Das andere Gerät darf
+danach nicht mehr speichern. Zwei Fenster desselben Geräts benötigen ebenfalls
+eine bestätigte Übernahme, damit sie einander nicht unbemerkt überschreiben.
+Beim Verlassen der Station wird ihre eigene Sperre entfernt. Bleibt nach einem
+Abbruch oder ohne Verbindung eine Sperre zurück, kann sie bestätigt übernommen
+werden. Während eine Speicherung läuft, ist keine Übernahme möglich.
+
+Vor dem Senden sichert die App Texte, ausgewählte Bild- und Tondateien sowie
+vorgemerkte Entfernungen auf diesem Gerät. Wird die Speicherung abgewiesen oder
+unterbrochen, sind diese unter „Noch nicht gesendete Änderungen“ erreichbar,
+auch ohne Verbindung und nach einem Neustart des Internetbrowsers. Das gilt auch
+für die vorgemerkte Entfernung einer Station. „Verwerfen“ entfernt diesen
+zurückgehaltenen Stand nach einer Rückfrage. Die Speicherung benötigt freien
+Gerätespeicher; bei einem Speicherfehler bleibt das Formular offen und die App
+behauptet nicht, dass die Sicherung gelungen sei. Bereits bestätigte einzelne
+Dateiübertragungen werden aus der Warteliste genommen.
+
+Zum erneuten Senden die Änderungen öffnen und „Speichern“ wählen. Die App
+beansprucht die Station erneut, gegebenenfalls nach einer Übernahme-Rückfrage.
+Sie vergleicht den Stand beim ursprünglichen Öffnen mit dem aktuellen Inhalt.
+Geänderte Texte, Koordinaten, Reihenfolge sowie geänderte Bild- und Tondateien
+lösen einen Vergleich aus. Unterschiedliche Dateiinhalte werden auch bei gleicher
+Adresse und gleicher Dateianzahl erkannt. Eine Tabelle zeigt die ursprünglichen,
+eigenen und aktuellen Angaben; aktuelle Aufnahmen können geprüft werden.
+„Meine Änderungen senden“ übernimmt die eigenen Angaben und vorgemerkten
+Dateiaktionen. „Auf diesem Gerät behalten“ sendet nichts. Ein weiterer Vergleich
+direkt vor dem Schreiben verhindert ein Überschreiben nach dieser Rückfrage.
+Es gibt kein unbeaufsichtigtes erneutes Senden oder automatisches Zusammenführen.
+Wenn eine Station entfernt wurde oder der Gruppenzugang fehlt, bleibt der Entwurf
+auf dem Gerät einsehbar; er wird nicht automatisch als neue Station angelegt.
+
+### Hinweise zum Betrieb
+
+Sperrdateien liegen unter `storage/active/routes/<Strecke>/locks/<Station>.json`
+(bzw. dem konfigurierten `STORAGE_DIR`). Sie enthalten `creator_id`, den Hash der
+Gruppensitzung, einen zufälligen Bearbeitungsschlüssel und den Erstellzeitpunkt.
+Nur die passende Kennung **und** die berechtigte Sitzung mit dem richtigen
+Bearbeitungsschlüssel dürfen schreiben oder ihre Sperre entfernen. Die Kennung
+wird aus der bereits eingerichteten Sitzung übernommen, nicht aus einem frei
+angegebenen Anfragefeld. Dateien werden atomar ersetzt und mit Modus 0600
+angelegt. Dieser Ordner darf nicht unmittelbar durch Nginx ausgeliefert werden.
+Schließen der Gruppe entfernt ihre Sperren; laufende Schreibanfragen müssen
+zunächst fertig werden. Erfolgreiches Entfernen einer Station entfernt auch
+ihre Sperrdatei. Zurückgebliebene Sperren werden nicht zeitgesteuert gelöscht.
+
+Stationsänderungen prüfen zusätzlich einen SHA-256-Abdruck aus Stationsangaben
+und den tatsächlichen Bild-/Tondateien. Andere Stationen können deshalb unabhängig
+vom alten Versionszähler der ganzen Strecke gespeichert werden. Änderungen der
+Streckenangaben selbst verwenden weiter `If-Match`. Sperrübernahmen und Dateischreiben
+sind im vorhandenen Einprozessbetrieb synchronisiert. Mehrprozessbetrieb ist
+weiterhin nicht unterstützt.
+
+Die Sicherungen liegen in IndexedDB (`wegwichtel.group-point-drafts.v1`) und zählen
+zur vorhandenen Anzeige des belegten Gerätespeichers. Browserdaten-Löschung kann
+sie entfernen. Sie enthalten nur die betroffene Station und neu ausgewählte
+Dateien; vorhandene Aufnahmen werden hierfür nicht gesammelt heruntergeladen.