Wegwichtel/docs/Gruppenbearbeitung.md

# Gemeinsam bearbeiten

In „Strecken bearbeiten“ öffnet der kleine Button mit zwei gezeichneten Wichteln
zwischen Stift und Löschen zuerst ein großes Popup zur Codeauswahl. Die fünf
Drehräder sind zufällig vorbelegt. Du kannst jeden Wichtel ändern; Wiederholungen
sind erlaubt. Erst „Diesen Code verwenden“ bestätigt deine Auswahl. Abbrechen
legt keine Gruppe an und überträgt keine Strecke. Bei lokalen Entwürfen fragt
die App danach, ob Weg, Stationen, Bilder und Ton übertragen werden dürfen.
Ein bereits eingesandter eigener Entwurf wird zuerst aktualisiert. Anschließend
zeigt ein eigenes Popup den gespeicherten Code. Die Bearbeitung beginnt erst
mit „Entwurf bearbeiten“. Das Original bleibt unverändert.

Andere öffnen in der Streckenverwaltung „Gruppencode eingeben“. Dort schieben
sie die Bilder in fünf Drehrädern nach oben oder unten. Es zählen die Wichtel
in der Mitte, von links nach rechts. Pfeiltasten und 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 60 Minuten. Erfolgreiches Mitmachen, Öffnen zur
  Bearbeitung, Übernehmen einer Station, gemeldete tatsächliche Bearbeitungsaktivität
  und erfolgreiches Speichern setzen die Frist erneut auf 60 Minuten.
  Listen, Codeanzeige, reine Datenabrufe und Sperrstatusabfragen verlängern sie nicht.
- Das Code-Popup zeigt Ablaufzeit und verbleibende Minuten und Sekunden. Die
  Restzeit zählt herunter; neue Aktivität wird spätestens nach 30 Sekunden übernommen.
- Der Code wird niemals automatisch geändert oder neu erzeugt. Nach Ablauf
  erlaubt er keinen neuen Beitritt. Bereits beigetretene Personen behalten ihren
  Zugang und können durch erneute Bearbeitung die Gültigkeit desselben Codes verlängern.
- „Gruppencode“ zeigt den gespeicherten Code erneut an. „Code auswählen“ öffnet
  die Auswahl; nur eine ausdrückliche Bestätigung ändert oder reaktiviert den Code.
  Während einer Stationsbearbeitung wartet ein Codewechsel, bis die Stationen frei sind.
  Bereits verwendete Codes anderer Gruppen werden mit einem Hinweis abgewiesen.
- „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 fehlende STRICT-Tabellen an, einschließlich `collaboration_invitations`
für die dauerhaft gespeicherten Codes. 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. Eingaben sowie
Bedienaktionen in der Station melden bei bestehender Verbindung spätestens alle
30 Sekunden Aktivität. Das bloße Offenlassen des Fensters oder Abfragen des
Sperrstatus verlängert die Sperre nicht. 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. Sperren ohne gemeldete Aktivität werden nach 60 Minuten entfernt. Die Wartung
läuft beim App-Start und anschließend jede Minute; API-Zugriffe prüfen die Frist
zusätzlich unmittelbar.

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.

Die ausgewählten Codes liegen in `collaboration_invitations`, der zugehörige
SHA-256-Abdruck und Ablaufzeitpunkt in `collaboration_groups`. Nur die berechtigte
eröffnende Sitzung kann den Code abrufen. Nach einem App-Neustart wird derselbe
Code wieder angezeigt; es findet kein automatischer Ersatz statt. Bestehende
Gruppen aus der vorherigen Version enthalten noch keinen gespeicherten Klartext.
Für sie muss die eröffnende Person einmal ausdrücklich einen Code auswählen.