numolus/docs/konzept-teilen-und-zusammenarbeit.md

numolus: Teilen & gemeinsames Arbeiten – Konzept

Stand: 2026-09-28 · Autor: Wild Karl-Heinz

numolus-Dokumente liegen künftig auf einem eigenen Server, werden live gemeinsam bearbeitet und brauchen kein Konto. Ein Konto entsteht nur, wenn jemand es will oder ein Dokument an bestimmte Personen teilen möchte. Angemeldet wird ausschließlich per Magic Link (E-Mail).

---

1. Ziel & Grundsätze

• Anonym zuerst. App öffnen, Dokument anlegen, arbeiten, ohne Registrierung. Der Browser bekommt eine Gast-Identität per Cookie. Ein Sheet wird ohne anderslautende Angaben im Browser gespeichert.
• Konto nur bei Bedarf. Es gibt zwei Anlässe:
  1. Man will seine Dokumente auf mehreren Geräten haben bzw. nicht verlieren.
  2. Man will an bestimmte Personen teilen oder deren Rechte verwalten.
• Login nur per Magic Link. E-Mail eingeben, Link anklicken, fertig. Keine Passwörter.
• Nichts geht verloren. Beim Anlegen oder Anmelden eines Kontos werden alle Dokumente des bisherigen Gasts übernommen.
• Links sind Zugänge. Ein Bearbeiten- oder Lesen-Link funktioniert auch ohne Konto und lässt sich jederzeit widerrufen.
• Live-Zusammenarbeit per CRDT (Yjs). Gleichzeitige Änderungen werden ohne Sperren zusammengeführt; jede Person hat ihr eigenes Undo.
• Lokale Formate bleiben. .num, CSV und XLSX bleiben als Import/Export.

Nicht-Ziele (vorerst)

• Ende-zu-Ende-Verschlüsselung (siehe Kapitel 12)
• Kommentare und Versionsverlauf in der Oberfläche (das Datenmodell lässt beides später zu)

---

2. Nutzerflüsse

Sechs Abläufe decken alles ab; nur C und D führen zum Magic Link.

A – Anonym anlegen und arbeiten

1. Person öffnet numolus. Kein Cookie vorhanden → Server legt einen Gast an und setzt ein langlebiges Cookie.
2. „Neues Dokument“ → Server erzeugt ein Dokument mit UUID, Besitzer = Gast. Die URL wird /d/<uuid>.
3. Alle Dokumente bleiben generell lokal im Browser. Doch sollte ein User authentifiziert sein, dann wird jede Änderung geht sofort an den Server. Kein Speichern-Knopf.
4. Dezenter Hinweis: „Dieses Dokument ist nur in diesem Browser in deiner Liste. Mit E-Mail sichern, um es überall zu haben.“

B – Wiederfinden (ohne Konto)

1. Startseite zeigt „Meine Dokumente“: alles, was dem Gast gehört oder was er über einen Link geöffnet hat.
2. Die Liste liegt serverseitig am Gast, hängt aber am Cookie. Anderer Browser oder gelöschte Cookies = leere Liste.
3. Ohne Konto kein Restore wenn ein anderer Browser verwendet wird.

C – Konto anlegen, weil man es will

1. „Anmelden“ → E-Mail eingeben → Mail mit Magic Link.
2. Klick auf den Link (im selben oder einem anderen Browser) → angemeldet.
3. War im Browser ein Gast aktiv, werden dessen Dokumente, Mitgliedschaften und Link-Zugänge ins Konto übernommen (Kapitel 4.4).
4. Weiteres Gerät: E-Mail eingeben, Link klicken → dieselbe Liste.

Es gibt keine getrennte „Registrierung“: Die erste Anmeldung mit einer neuen E-Mail legt das Konto an.

D – An Personen teilen (erfordert Konto)

1. „Teilen“ → Dialog. Ohne Konto: „Um an Personen zu teilen, bestätige deine E-Mail“ → Ablauf C, danach geht der Dialog an derselben Stelle weiter. Mache darauf aufmerksam, dass fuer das Share die Daten auf dem Server gepeichert werden müssen.
2. E-Mail der Empfängerin + Rolle (Lesen/Bearbeiten) eingeben → Einladung per Mail.
3. Die Empfängerin klickt den Link in der Einladung. Die Einladung ist gleichzeitig ihr Magic Link: Sie ist damit angemeldet (Konto wird bei Bedarf angelegt), das Dokument öffnet sich und steht in ihrer Liste unter „Mit mir geteilt“.

E – Per Link teilen (kein Konto nötig)

1. „Teilen“ → „Link kopieren“ mit Auswahl Lesen/Bearbeiten.
2. Wer den Link öffnet, bekommt bei Bedarf eine Gast-Identität. Das Dokument erscheint danach in dessen Liste.
3. Der Besitzer kann den Link jederzeit neu erzeugen. Der alte Link und alle darüber entstandenen Zugänge sind dann ungültig.

Offene Entscheidung: Soll auch Ablauf E ein Konto verlangen? Siehe Kapitel 12.

F – Gemeinsam bearbeiten

1. Alle Beteiligten sehen Änderungen der anderen innerhalb von Sekundenbruchteilen.
2. Die Auswahl der anderen erscheint als farbiger Rahmen mit Namen (Konto: Anzeigename; Gast: zufälliger Name wie „Anonymer Fuchs“).
3. Oben rechts: Avatare der gerade Anwesenden.
4. Undo macht nur die eigenen Änderungen rückgängig.
5. Wer nur Leserechte hat, sieht alles live, kann aber nichts ändern (Eingabe gesperrt, Toolbar reduziert).

---

3. Architektur-Überblick

Ein einziger Rails-8-Server übernimmt Login, Dokumentverwaltung und Live-Sync. Der Browser hält den Dokumentinhalt als Yjs-CRDT und rechnet Formeln weiterhin selbst.

┌─ Browser (je Person) ─────┐          ┌─ Rails 8 (numolus-Server) ──┐
│                           │  HTTPS   │                             │      ┌────────────┐
│  Vue-App                  │◄────────►│  REST-API & Login           │─────►│            │
│  Oberfläche, Liste        │          │  Magic Link, Liste, Teilen  │      │ PostgreSQL │
│           │               │          │                             │      │ alle Daten │
│  Store auf Yjs            │ WebSocket│  DocumentChannel            │─────►│            │
│  Inhalt als CRDT,         │◄────────►│  ActionCable + y-rb         │      └────────────┘
│  Formeln rechnen lokal    │          │                             │      ┌────────────┐
│           │               │          │  Jobs & Mailer              │─────►│ SMTP       │
│  IndexedDB (Offline)      │          │  Kompaktieren, Aufräumen    │      └────────────┘
└───────────────────────────┘          └─────────────────────────────┘

Baustein	Wahl	Begründung
Backend	Rails 8	vorhandene Ruby/Rails-Kompetenz und Server
Live-Sync Server	ActionCable + y-rb (+ yrb-actioncable)	Yjs-Protokoll in Ruby, serverseitiges Zusammenfassen möglich
Live-Sync Client	yjs, @y-rb/actioncable, y-indexeddb	Standard-CRDT, offline-fähig
Datenbank	PostgreSQL	Binärdaten (bytea), später Volltextsuche
Jobs	Solid Queue (Rails-8-Standard)	kein Redis nötig
ActionCable-Adapter	Solid Cable (Rails-8-Standard)	kein Redis nötig; bei vielen Verbindungen später Redis oder AnyCable
Mail	Action Mailer über SMTP	Magic Links, Einladungen
Hosting	App und API unter einer Domain, z. B. numolus.wicom.li	First-Party-Cookies, kein CORS

Auslieferung der App: Der Vite-Build (dist/) wird von Rails bzw. dem vorgeschalteten Webserver unter derselben Domain ausgeliefert. Alle Pfade außer /api/* und /cable liefern index.html (Client-Routing für /d/<uuid>).

Warum Yjs und nicht selbst gebaut: Gleichzeitige Änderungen korrekt zusammenzuführen (inkl. Offline-Phasen) ist der schwierigste Teil. Yjs ist dafür etabliert; der Server muss das Zusammenführen nicht selbst verstehen, kann es mit y-rb aber (Kompaktierung, Suche, Export).

---

4. Identität & Login

4.1 Gast-Identität

• Keine Anlage eines Benutzers auf dem Server.
• Cookie: numolus_session, signiert, HttpOnly, Secure, SameSite=Lax, Laufzeit 1 Jahr, bei jeder Nutzung verlängert (gleitend).
• Anzeigename für Cursor: zufällig („Anonymer Fuchs“), im Browser änderbar, am Gast gespeichert.

4.2 Magic Link

1. POST /api/auth/magic_link mit E-Mail (+ optional return_to).
2. Server erzeugt ein zufälliges Token (32 Byte), speichert nur dessen SHA-256-Hash, Gültigkeit 15 Minuten, einmal verwendbar.
3. Mail mit Link https://numolus.wicom.li/auth/verify?token=…. Zusätzlich ein 6-stelliger Code in der Mail, damit man sich auch auf einem Gerät anmelden kann, auf dem die Mail nicht gelesen wird (z. B. Link am Handy, App am Desktop).
4. Aufruf des Links zeigt eine Bestätigungsseite mit Knopf „Anmelden“ (POST). Grund: Mail-Scanner (Outlook Safe Links u. ä.) rufen Links automatisch per GET auf und würden das Token sonst verbrauchen.
5. Nach dem POST: Token als verbraucht markieren, Konto anlegen falls neu, Gast übernehmen (4.4), neue Session, Weiterleitung zu return_to.

Antwort auf Schritt 1 ist immer gleich („Falls die Adresse gültig ist, ist eine Mail unterwegs“), damit nicht abgefragt werden kann, welche Adressen ein Konto haben.

4.3 Sessions

• Eine Session pro Browser/Gerät, in der Tabelle sessions (Rails-8-Generator bin/rails generate authentication als Basis, Passwort-Teil entfernt).
• „Abmelden“ löscht die Session. „Überall abmelden“ löscht alle Sessions des Kontos.
• Nach dem Abmelden ist der Browser wieder anonym, bekommt aber nicht den alten Gast zurück (der ist ins Konto übergegangen).

4.4 Übernahme Gast → Konto

Beim erfolgreichen Magic-Link-Login in einem Browser mit Gast-Session:

1. Dokumente werden nach Rückfrage auf dem Server gespeichert.
2. Alle document_memberships des Gasts → auf das Konto umhängen; bei Konflikt (Konto hat schon eine Mitgliedschaft) gilt die höhere Rolle.
3. Gast-Datensatz löschen, Gast-Session durch Konto-Session ersetzen.
4. Alles in einer Transaktion.

Existiert das Konto bereits (Anmeldung auf zweitem Gerät), passiert dasselbe: Die Gast-Dokumente des zweiten Geräts wandern ebenfalls ins Konto.

---

5. Datenmodell

users
  id              bigint PK
  email           citext, unique, null bei Gästen
  display_name    string
  color           string            -- Cursorfarbe
  last_seen_at    datetime
  created_at, updated_at

sessions
  id              bigint PK
  user_id         → users
  token_digest    string, unique    -- Cookie enthält nur das Token, DB den Hash
  user_agent, ip_address
  last_active_at  datetime
  created_at

magic_links
  id              bigint PK
  email           citext
  token_digest    string, unique
  code_digest     string            -- 6-stelliger Code
  purpose         enum: login | invitation
  document_id     → documents, null       -- bei Einladungen
  role            enum: viewer | editor   -- bei Einladungen
  return_to       string
  expires_at      datetime
  used_at         datetime
  created_at

documents
  id              uuid PK           -- steht in der URL
  owner_id        → users
  title           string
  state           bytea             -- kompaktierter Yjs-Stand
  state_vector    bytea             -- für effizientes Nachladen
  schema_version  integer           -- Version des Yjs-Datenlayouts (Kap. 7.1)
  size_bytes      integer
  last_opened_at  datetime
  deleted_at      datetime          -- Papierkorb
  created_at, updated_at

document_updates                     -- noch nicht kompaktierte Änderungen
  id              bigint PK
  document_id     → documents
  user_id         → users
  data            bytea             -- ein Yjs-Update
  created_at

document_memberships
  id              bigint PK
  document_id     → documents
  user_id         → users
  role            enum: viewer | editor
  source          enum: invite | link
  share_link_id   → share_links, null   -- für Widerruf per Link
  last_opened_at  datetime
  unique (document_id, user_id)

share_links
  id              bigint PK
  document_id     → documents
  role            enum: viewer | editor
  token_digest    string, unique
  created_by_id   → users
  revoked_at      datetime
  expires_at      datetime, null
  created_at

Hinweise

• Der Besitzer steht in documents.owner_id, nicht in document_memberships. Genau ein Besitzer pro Dokument; Übertragen ist eine spätere Funktion.
• Pro Dokument höchstens ein aktiver Link je Rolle (einfachere Oberfläche).
• Tokens (Session, Magic Link, Share Link) werden nur als Hash gespeichert. Ein Datenbank-Leak gibt damit keine gültigen Zugänge preis.
• Der Titel liegt als Spalte vor (für die Liste) und wird aus dem Yjs-Dokument synchron gehalten.

---

6. Zugriff & Rechte

6.1 Rollen

Aktion	Besitzer	Editor	Viewer
Lesen, Cursor der anderen sehen	ja	ja	ja
Bearbeiten	ja	ja	nein
Exportieren (.num, CSV, XLSX)	ja	ja	ja
Per Link teilen / Link widerrufen	ja	nein	nein
An Personen einladen / entfernen	ja (mit Konto)	nein	nein
Umbenennen	ja	ja	nein
Löschen (Papierkorb)	ja	nein	nein
Aus eigener Liste entfernen	–	ja	ja

Später denkbar: Editoren dürfen ebenfalls teilen (Schalter pro Dokument).

6.2 Wie Zugang entsteht

1. Besitz: Wer anlegt, ist Besitzer.
2. Einladung: Magic Link mit purpose = invitation → beim Einlösen entsteht eine Mitgliedschaft mit source = invite.
3. Link: Aufruf von /d/<uuid>#k=<token> → Client schickt Token an POST /api/documents/:id/join → Mitgliedschaft mit source = link und Verweis auf den Link.

Der Link-Token steht im Fragment (#). Browser senden Fragmente nicht an den Server; das Token landet also nicht in Access-Logs oder Referrer-Headern. Nach dem Einlösen entfernt die App das Fragment aus der Adresszeile.

6.3 Prüfung

Eine zentrale Methode Document#role_for(user) → :owner | :editor | :viewer | nil.

• REST: jeder Controller über before_action; kein Zugang → 404 (nicht 403, damit die Existenz einer UUID nicht bestätigt wird).
• WebSocket: ApplicationCable::Connection identifiziert den User über das Session-Cookie. DocumentChannel#subscribed prüft die Rolle und lehnt ab (reject). Viewer-Nachrichten, die Änderungen enthalten, werden verworfen und protokolliert.
• Rechte ändern sich live: Wird eine Mitgliedschaft entfernt oder ein Link widerrufen, schickt der Server den betroffenen Verbindungen ein access_revoked und schließt sie. Rollenwechsel Editor → Viewer ebenso (Client lädt im Lesemodus neu).

6.4 Widerruf

• Link neu erzeugen: alter Link revoked_at gesetzt, alle Mitgliedschaften mit share_link_id = alter Link werden gelöscht. Wer weiter Zugang haben soll, muss den neuen Link bekommen oder eingeladen werden.
• Person entfernen: Mitgliedschaft löschen.
• Eingeladene Personen (source = invite) sind vom Link-Widerruf nicht betroffen.

---

7. Echtzeit-Sync

7.1 Yjs-Datenlayout

Das heutige DocumentState (src/store/types.ts) wird auf Yjs-Typen abgebildet. Wichtig: Alles, was mehrere Personen gleichzeitig ändern können, muss eine eigene Yjs-Struktur sein, damit Änderungen feingranular zusammengeführt werden.

Y.Doc
├─ meta: Y.Map          { title, locale, csvDelimiter, schemaVersion }
├─ sheetOrder: Y.Array<sheetId>
├─ sheets: Y.Map<sheetId, Y.Map>
│    └─ { name, objectOrder: Y.Array<objectId>, objects: Y.Map<objectId, Y.Map> }
│         └─ Tabelle: {
│              kind, name, x, y, view…,
│              rowOrder: Y.Array<rowId>,     ← stabile IDs statt Indizes
│              colOrder: Y.Array<colId>,
│              rowHeights: Y.Map<rowId, number>,
│              colWidths:  Y.Map<colId, number>,
│              cells:   Y.Map<"colId:rowId", string>,
│              formats: Y.Map<"colId:rowId", Y.Map>
│            }
├─ namedRanges: Y.Map<id, Y.Map>
├─ customFunctions: Y.Map<id, Y.Map>
└─ macros: Y.Map<id, Y.Map>

Nicht im Yjs-Dokument: selection, activeSheetId, activeObjectId. Das ist Zustand pro Person (Kapitel 7.4 und 8.3).

Zelltext: Eine Zelle ist ein einfacher String (letzte Änderung gewinnt). Zwei Personen, die gleichzeitig dieselbe Zelle ändern, erzeugen keinen Mischtext; eine Fassung gewinnt. Das entspricht Google Sheets und ist für Tabellen richtig.

7.2 Protokoll über ActionCable

Standard-Yjs-Sync (wie y-websocket), transportiert über DocumentChannel, Binärdaten Base64-kodiert:

1. Beitritt: Client abonniert DocumentChannel mit document_id. Server prüft die Rolle, schickt sync_step1 (Server-State-Vector).
2. Client antwortet mit den Änderungen, die dem Server fehlen (Offline-Arbeit), und seinem State-Vector; Server schickt, was dem Client fehlt.
3. Laufend: Jede lokale Änderung → update an den Server → Server speichert in document_updates und broadcastet an alle anderen Abonnenten dieses Dokuments.
4. Awareness: Cursor/Auswahl/Name → awareness an den Server → nur broadcasten, nie speichern.

yrb-actioncable liefert Schritte 1–4 fertig; vor der Umsetzung ist zu prüfen, ob das Gem aktiv gepflegt ist (Kapitel 12). Fallback: dieselbe Logik direkt mit y-rb im eigenen Channel (überschaubar, ca. 150 Zeilen).

7.3 Speicherung & Kompaktierung

• Jedes Update wird sofort als Zeile in document_updates angehängt (schnell, kein Lesen nötig).
• Kompaktierung (Solid-Queue-Job): wenn ein Dokument > 200 offene Updates hat oder 30 s nach der letzten Änderung. Der Job lädt documents.state
  • alle offenen Updates in y-rb, fasst sie zu einem neuen state zusammen, schreibt state, state_vector, size_bytes, title und löscht die verarbeiteten Updates, alles in einer Transaktion.
• Beim Beitritt lädt der Server state + offene Updates.
• Grenze: Dokumente über 20 MB Yjs-Stand werden abgelehnt (anpassbar). Anlass: Missbrauchsschutz und Speicherbedarf im Browser.

7.4 Awareness (Anwesenheit)

Pro Verbindung ein kleines Objekt, nur live verteilt:

{ "user": { "name": "Anonymer Fuchs", "color": "#e67e22" },
  "sheetId": "…", "objectId": "…",
  "selection": { "anchor": "colId:rowId", "focus": "colId:rowId" },
  "editing": true }

• Rahmen der anderen nur zeichnen, wenn sie auf demselben Sheet sind.
• Avatarleiste oben rechts; Klick auf einen Avatar springt zu dessen Auswahl.

---

8. Frontend-Umbau

8.1 Store auf Yjs

Heute ist doc ein reaktives Vue-Objekt, das die Store-Funktionen in src/store/document.ts direkt verändern, und das als Ganzes in localStorage gespeichert wird.

Neu:

• Quelle der Wahrheit ist das Y.Doc.
• Schreiben: Jede Store-Funktion (setCell, insertRows, fillSelection, …) wird zu einer Transaktion auf dem Y.Doc (ydoc.transact(() => …, origin)).
• Lesen: Eine Vue-Spiegelung des Y.Doc (per observeDeep), damit alle Komponenten und das Formel-Engine unverändert auf reaktive Daten zugreifen. Die Spiegelung wird nur an den geänderten Stellen aktualisiert.
• Vorgehen schrittweise: erst eine Adapter-Schicht, die das heutige DocumentState-Format aus dem Y.Doc liefert; dann Funktion für Funktion die Schreibpfade umstellen. Tests in src/**/__tests__ sichern jeden Schritt ab.
• localStorage-Speicherung entfällt; an ihre Stelle tritt y-indexeddb (Offline-Kopie pro Dokument).

8.2 Undo pro Person

Heute: Snapshots des ganzen Dokuments (snapshot(), undo()), die bei gemeinsamer Arbeit fremde Änderungen zurückdrehen würden.

Neu: Y.UndoManager über die geteilten Strukturen, beschränkt auf lokale Transaktionen (trackedOrigins). Das heutige Zusammenfassen schneller Änderungen (HISTORY_COALESCE_MS) entspricht captureTimeout. Die Auswahl wird als Metadaten pro Undo-Schritt gespeichert, damit Undo auch die Auswahl zurücksetzt.

8.3 Auswahl aus dem Dokument lösen

selection, activeSheetId, activeObjectId wandern aus DocumentState in einen lokalen View-Store. Sie werden zusätzlich in die Awareness gespiegelt (als colId:rowId, damit sie bei Einfügungen anderer nicht verrutschen).

8.4 Stabile Zeilen- und Spalten-IDs

Der schwierigste Teil. Heute sind Zellen über Positionen adressiert (cells["c,r"]), und Einfügen/Löschen verschiebt Schlüssel und Formelbezüge. Bei gleichzeitiger Arbeit führt das zu falsch platzierten Werten.

Neu:

• Jede Zeile und Spalte hat eine stabile ID; rowOrder/colOrder legen die Reihenfolge fest. Einfügen = ID in die Liste einfügen; kein Verschieben von Zellen.
• Zellen sind über colId:rowId adressiert.
• Formeln bleiben im Text als A1-Bezüge gespeichert (so zeigt sie die Formelleiste). Beim Einfügen/Löschen passt heute die Store-Logik die Bezüge an; das bleibt so, läuft aber in derselben Transaktion wie die Strukturänderung. Rest-Risiko: Person A fügt eine Zeile ein, während Person B gleichzeitig eine Formel tippt, die sich auf spätere Zeilen bezieht. B's Formel wird dann nicht angepasst. Das ist bei Google Sheets ebenso und wird akzeptiert. Langfristige Alternative: Bezüge intern als IDs speichern und nur zur Anzeige in A1 übersetzen.
• Das Formel-Engine rechnet weiter mit Positionen; die Spiegelung (8.1) liefert ihm das heutige Positionsformat.

8.5 Makros

Makros laufen nur bei der Person, die sie startet. Alle Änderungen eines Makrolaufs sind eine Yjs-Transaktion und damit ein Undo-Schritt, der sich wie jede andere Änderung verteilt. Viewer können keine Makros starten.

8.6 Offline

• y-indexeddb hält eine Kopie jedes geöffneten Dokuments.
• Ohne Verbindung kann weitergearbeitet werden; die Statusleiste zeigt „Offline – Änderungen werden später übertragen“.
• Beim Wiederverbinden gleicht das Sync-Protokoll (7.2) automatisch ab.

8.7 Neue Oberflächenteile

Teil	Inhalt
Startseite / Dokumentliste	„Meine Dokumente“, „Mit mir geteilt“, Suche nach Titel, Neu, Import
Teilen-Dialog	Link (Lesen/Bearbeiten) kopieren und neu erzeugen; Personen einladen, Rolle ändern, entfernen
Anmelden-Dialog	E-Mail, Hinweis „Mail ist unterwegs“, Code-Eingabe
Konto-Menü	Anzeigename, Abmelden, Überall abmelden, Konto löschen
Anwesenheit	Avatare, farbige Auswahlrahmen, Namensschild am Cursor
Status	Verbunden / Offline / Synchronisiert
Lesemodus	Eingabe gesperrt, Hinweis „Nur Lesen“

---

9. API

9.1 REST (/api, JSON, Session-Cookie, CSRF-Token für schreibende Aufrufe)

Methode	Pfad	Zweck
GET	/api/me	aktueller User (Gast oder Konto), legt keinen Gast an
PATCH	/api/me	Anzeigename, Farbe
POST	/api/auth/magic_link	Magic Link anfordern {email, return_to}
POST	/api/auth/verify	Token oder Code einlösen {token} / {email, code}
DELETE	/api/auth/session	Abmelden
DELETE	/api/auth/sessions	Überall abmelden
GET	/api/documents	Liste (eigene + geteilte), Metadaten, Rolle
POST	/api/documents	neues Dokument, optional mit Inhalt (Import)
GET	/api/documents/:id	Metadaten + eigene Rolle
PATCH	/api/documents/:id	Titel
DELETE	/api/documents/:id	in den Papierkorb (Besitzer) bzw. aus Liste entfernen
POST	/api/documents/:id/restore	aus dem Papierkorb
POST	/api/documents/:id/join	Link-Token einlösen {token}
GET	/api/documents/:id/export?format=num	Export serverseitig (optional)
GET	/api/documents/:id/share	Links und Mitglieder
POST	/api/documents/:id/share_links	Link (neu) erzeugen {role} → Token einmalig zurück
DELETE	/api/documents/:id/share_links/:link_id	Link widerrufen
POST	/api/documents/:id/invitations	Person einladen {email, role}
PATCH	/api/documents/:id/members/:user_id	Rolle ändern
DELETE	/api/documents/:id/members/:user_id	Person entfernen

9.2 WebSocket (/cable, DocumentChannel)

Richtung	Nachricht	Inhalt
Client → Server	subscribe	{document_id}
beide	sync_step1	State-Vector (Base64)
beide	sync_step2	fehlende Updates (Base64)
beide	update	ein Yjs-Update (Base64)
beide	awareness	Awareness-Update (Base64)
Server → Client	access_revoked	{reason} → Client schließt Dokument
Server → Client	role_changed	{role} → Client lädt neu
Server → Client	error	{code} z. B. too_large, read_only

---

10. Sicherheit, Datenschutz & Betrieb

10.1 Sicherheit

• Tokens: 32 Byte aus SecureRandom, in der DB nur SHA-256-Hash; Vergleich zeitkonstant.
• Rate Limits (Rails 8 rate_limit):
  • Magic Link: 5 pro E-Mail und 20 pro IP je Stunde
  • Code-Eingabe: 5 Fehlversuche, dann Code ungültig
  • Dokument anlegen: 60 pro User/IP je Stunde
  • Link einlösen: 30 pro IP je Minute
  • WebSocket-Updates: Größe pro Nachricht max. 1 MB, Frequenz begrenzen
• Cookies: HttpOnly, Secure, SameSite=Lax; CSRF-Schutz für REST.
• ActionCable: allowed_request_origins auf die eigene Domain.
• Enumeration: UUIDs v4, 404 statt 403, gleiche Antwort beim Magic-Link-Anfordern.
• Makros/Custom Functions laufen im Browser. Da jetzt fremde Personen Makros in ein gemeinsames Dokument schreiben können, muss geprüft werden, wie Makros heute ausgeführt werden und ob sie auf Browser-APIs zugreifen können. Falls ja: Ausführung isolieren oder Makros aus fremder Hand erst nach Bestätigung ausführen (offene Frage, Kapitel 12).
• Inhalte: Zelltexte werden weiterhin nie als HTML gerendert.

10.2 Datenschutz (DSGVO)

• Gespeicherte Personendaten: E-Mail, Anzeigename, IP und User-Agent je Session, Zeitstempel. Keine Tracker.
• Datenschutzerklärung und Impressum auf der Startseite verlinkt.
• Gast-Cookie ist technisch notwendig (Zugang zu eigenen Dokumenten) → kein Einwilligungsbanner nötig; in der Datenschutzerklärung erklären.
• Konto löschen: löscht eigene Dokumente (nach Warnung), Mitgliedschaften, Sessions. Dokumente, die mit anderen geteilt sind: Option „Besitz an Editor übertragen“ oder löschen.
• Export aller Daten: ZIP mit allen eigenen Dokumenten als .num.
• IP-Adressen in Sessions nach 30 Tagen kürzen/entfernen.
• Mailversand über einen Anbieter in der EU/Schweiz.

10.3 Aufräumjobs (Solid Queue, täglich)

Job	Regel
Gäste	Gast ohne Dokumente und ohne Aktivität seit 30 Tagen → löschen
Gast-Dokumente	Besitzer ist Gast, nicht geöffnet seit 12 Monaten → löschen (Mitglieder vorher nicht warnbar)
Papierkorb	deleted_at älter als 30 Tage → endgültig löschen
Magic Links	abgelaufen oder verbraucht, älter als 7 Tage → löschen
Sessions	inaktiv seit 1 Jahr → löschen
Kompaktierung	Dokumente mit offenen Updates, die der Live-Job verpasst hat

10.4 Betrieb

• Backups: tägliches pg_dump, 30 Tage aufbewahrt, Wiederherstellung einmal pro Quartal testen.
• Monitoring: Anzahl WebSocket-Verbindungen, offene Updates je Dokument, Job-Warteschlange, Mail-Zustellfehler, Fehler-Tracking (z. B. Sentry o. ä.).
• Deployment: Kamal (Rails-8-Standard) oder bestehender Server; der heutige npm run sync-Schritt wird durch das Ausliefern des Builds über die Rails-App ersetzt.
• Skalierung: Ein Prozess reicht für den Anfang. Bei vielen gleichzeitigen Verbindungen: AnyCable (WebSocket-Server in Go, Rails-Logik bleibt).

---

Umsetzungsstand (Branch with-server, 2026-09-28)

Umgesetzt sind Phasen 1–3 in angepasster Form; Live-Sync (Phase 4) fehlt noch.

Thema	Umsetzung	Abweichung vom Konzept
Anonym	Dokumente bleiben lokal in IndexedDB (/?doc=<id>)	kein Gast-Konto auf dem Server
Konto	Magic Link + 6-stelliger Code, Konto entsteht bei der ersten Anmeldung	–
Übernahme	nach der ersten Anmeldung Rückfrage, welche lokalen Dokumente hochgeladen werden; hochgeladene werden lokal entfernt	statt automatischer Übernahme
Server-Dokumente	JSON-Inhalt mit Versionsnummer, /d/<id>; mit Konto werden neue Dokumente auf dem Server angelegt	Inhalt noch nicht als Yjs-Stand
Gleichzeitiges Bearbeiten	Sperre pro Browser-Tab (90 s ohne Heartbeat), andere sehen „Nur Lesen“ und folgen per Abfrage alle 10 s	Übergang bis Phase 4
Teilen per Link	ohne Konto nutzbar; Token im Browser gespeichert (localStorage), nach Anmeldung dem Konto zugeordnet	Link-Token im Klartext gespeichert, damit der Besitzer den Link erneut kopieren kann
Einladungen	Mail mit Link (7 Tage gültig), meldet gleichzeitig an	–
Sessions	signierte Session-ID im Cookie (Rails-8-Standard)	statt Token-Digest
Datenbank	App-Daten, Solid Queue, Cache und Cable in einer PostgreSQL-Datenbank	–
Papierkorb, Aufräumjobs, Konto löschen	noch offen	–

11. Umsetzung in Phasen

Jede Phase ist für sich nutzbar und wird einzeln ausgeliefert.

Phase 1 – Server-Dokumente, anonym (ohne Live-Sync)

• Rails-App: users (nur Gäste), sessions, documents mit Inhalt als JSON (heutiges .num-Format, src/io/json.ts), REST für Liste/Anlegen/Laden/ Speichern/Löschen.
• Frontend: Dokumentliste, URL /d/<uuid>, automatisches Speichern an den Server statt localStorage. Bestehende localStorage-Dokumente werden beim ersten Start einmalig hochgeladen.
• Konflikte: Versionsnummer am Dokument; veraltete Speicherung wird abgelehnt und der Client lädt neu (es arbeitet ohnehin nur eine Person).

Fertig, wenn: Dokument anonym anlegen, Browser schließen, wieder öffnen → Dokument in der Liste; .num-Import/Export funktioniert weiter.

Phase 2 – Konto & Magic Link

• magic_links, Login-Ablauf (4.2), Übernahme Gast → Konto (4.4), Mailer, Konto-Menü, Abmelden.

Fertig, wenn: Gast legt Dokument an, meldet sich an, öffnet auf zweitem Gerät per Magic Link → Dokument ist da. Mail-Scanner verbrauchen den Link nicht (Bestätigungsseite).

Phase 3 – Teilen (noch ohne Live-Sync)

• share_links, document_memberships, Einladungen, Teilen-Dialog, Rollenprüfung, Lesemodus.
• Gleichzeitiges Bearbeiten: einfache Sperre („Anna bearbeitet gerade – nur Lesen“), Freigabe nach 2 Minuten Inaktivität.

Fertig, wenn: Link teilen, zweite Person öffnet ohne Konto; Einladung per Mail kommt an und öffnet das Dokument; Link widerrufen sperrt sofort.

Phase 4 – Live-Zusammenarbeit

• Store auf Yjs (8.1), stabile Zeilen-/Spalten-IDs (8.4), Undo pro Person (8.2), Auswahl lösen (8.3), DocumentChannel, Kompaktierung, Awareness, Offline. Einmalige Umwandlung aller JSON-Dokumente in Yjs-Stände.
• Sperre aus Phase 3 entfällt.

Fertig, wenn: Zwei Browser bearbeiten gleichzeitig verschiedene und dieselben Zellen, fügen gleichzeitig Zeilen ein → beide sehen dasselbe Ergebnis, kein Wert landet in einer falschen Zeile; Undo betrifft nur eigene Änderungen; 10 Minuten offline arbeiten und wieder verbinden → alles übernommen.

Phase 5 – Feinschliff

• Papierkorb-Oberfläche, Suche, Konto löschen / Datenexport, Anzeige „zuletzt geändert von“, Monitoring, Aufräumjobs scharf schalten.

Aufwand grob: Phasen 1–3 sind überwiegend Standard-Rails-Arbeit plus überschaubare Frontend-Ergänzungen. Phase 4 ist der größte Brocken, weil fast jede Funktion in src/store/document.ts betroffen ist; sie sollte in kleinen, jeweils getesteten Schritten erfolgen.

---

12. Offene Fragen & Risiken

Entscheidungen

1. Link-Teilen ohne Konto? Konzept: Ja (Ablauf E). Alternative: Auch Link-Teilen erfordert ein Konto, damit jedes geteilte Dokument einen erreichbaren Besitzer hat. Vorteil: klare Verantwortung, bessere Missbrauchskontrolle. Nachteil: eine Hürde mehr.
2. Aufbewahrung von Gast-Dokumenten: 12 Monate ohne Öffnen, ok?
3. Server: bestehender Rails-Server (rails.wicom.li) oder eigene Instanz für numolus?
4. Mailanbieter: welcher SMTP-Dienst?
5. Editoren dürfen teilen? Konzept: Nein, nur Besitzer.
6. Ende-zu-Ende-Verschlüsselung als spätere Option? Würde serverseitige Kompaktierung, Suche und Export ausschließen.

Risiken

Risiko	Auswirkung	Gegenmaßnahme
y-rb / yrb-actioncable wenig gepflegt	Sync-Server ohne Updates	vor Phase 4 prüfen; Fallback: eigener Channel mit y-rb, oder Node-Sidecar mit Hocuspocus nur für /cable
Store-Umbau größer als erwartet	Phase 4 verzögert sich	Adapter-Schicht, schrittweise Umstellung, Phasen 1–3 bringen vorher schon Nutzen
Formelbezüge bei gleichzeitigem Einfügen	vereinzelt falsche Bezüge	akzeptiert (wie Google Sheets); langfristig ID-basierte Bezüge
Makros aus fremder Hand	Code einer anderen Person läuft im eigenen Browser	Ausführungsmodell prüfen, ggf. isolieren oder Bestätigung verlangen
Mail landet im Spam	Login unmöglich	SPF/DKIM/DMARC, seriöser Anbieter, Code als Alternative
Gast verliert Cookie	Liste leer	deutlicher Hinweis auf Konto; URL bleibt gültig
Große Dokumente	langsamer Sync	Größenlimit, Kompaktierung, Messung in Phase 4