31 KiB
31 KiB
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:
- Man will seine Dokumente auf mehreren Geräten haben bzw. nicht verlieren.
- 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
- Person öffnet numolus. Kein Cookie vorhanden → Server legt einen Gast an und setzt ein langlebiges Cookie.
- „Neues Dokument“ → Server erzeugt ein Dokument mit UUID, Besitzer = Gast.
Die URL wird
/d/<uuid>. - 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.
- 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)
- Startseite zeigt „Meine Dokumente“: alles, was dem Gast gehört oder was er über einen Link geöffnet hat.
- Die Liste liegt serverseitig am Gast, hängt aber am Cookie. Anderer Browser oder gelöschte Cookies = leere Liste.
- Ohne Konto kein Restore wenn ein anderer Browser verwendet wird.
C – Konto anlegen, weil man es will
- „Anmelden“ → E-Mail eingeben → Mail mit Magic Link.
- Klick auf den Link (im selben oder einem anderen Browser) → angemeldet.
- War im Browser ein Gast aktiv, werden dessen Dokumente, Mitgliedschaften und Link-Zugänge ins Konto übernommen (Kapitel 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)
- „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.
- E-Mail der Empfängerin + Rolle (Lesen/Bearbeiten) eingeben → Einladung per Mail.
- 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)
- „Teilen“ → „Link kopieren“ mit Auswahl Lesen/Bearbeiten.
- Wer den Link öffnet, bekommt bei Bedarf eine Gast-Identität. Das Dokument erscheint danach in dessen Liste.
- 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
- Alle Beteiligten sehen Änderungen der anderen innerhalb von Sekundenbruchteilen.
- Die Auswahl der anderen erscheint als farbiger Rahmen mit Namen (Konto: Anzeigename; Gast: zufälliger Name wie „Anonymer Fuchs“).
- Oben rechts: Avatare der gerade Anwesenden.
- Undo macht nur die eigenen Änderungen rückgängig.
- 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 |
| 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
POST /api/auth/magic_linkmit E-Mail (+ optionalreturn_to).- Server erzeugt ein zufälliges Token (32 Byte), speichert nur dessen SHA-256-Hash, Gültigkeit 15 Minuten, einmal verwendbar.
- 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). - Aufruf des Links zeigt eine Bestätigungsseite mit Knopf „Anmelden“
(
POST). Grund: Mail-Scanner (Outlook Safe Links u. ä.) rufen Links automatisch perGETauf und würden das Token sonst verbrauchen. - Nach dem
POST: Token als verbraucht markieren, Konto anlegen falls neu, Gast übernehmen (4.4), neue Session, Weiterleitung zureturn_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-Generatorbin/rails generate authenticationals 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:
- Dokumente werden nach Rückfrage auf dem Server gespeichert.
- Alle
document_membershipsdes Gasts → auf das Konto umhängen; bei Konflikt (Konto hat schon eine Mitgliedschaft) gilt die höhere Rolle. - Gast-Datensatz löschen, Gast-Session durch Konto-Session ersetzen.
- 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 indocument_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
- Besitz: Wer anlegt, ist Besitzer.
- Einladung: Magic Link mit
purpose = invitation→ beim Einlösen entsteht eine Mitgliedschaft mitsource = invite. - Link: Aufruf von
/d/<uuid>#k=<token>→ Client schickt Token anPOST /api/documents/:id/join→ Mitgliedschaft mitsource = linkund 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(nicht403, damit die Existenz einer UUID nicht bestätigt wird). - WebSocket:
ApplicationCable::Connectionidentifiziert den User über das Session-Cookie.DocumentChannel#subscribedprü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_revokedund schließt sie. Rollenwechsel Editor → Viewer ebenso (Client lädt im Lesemodus neu).
6.4 Widerruf
- Link neu erzeugen: alter Link
revoked_atgesetzt, alle Mitgliedschaften mitshare_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:
- Beitritt: Client abonniert
DocumentChannelmitdocument_id. Server prüft die Rolle, schicktsync_step1(Server-State-Vector). - Client antwortet mit den Änderungen, die dem Server fehlen (Offline-Arbeit), und seinem State-Vector; Server schickt, was dem Client fehlt.
- Laufend: Jede lokale Änderung →
updatean den Server → Server speichert indocument_updatesund broadcastet an alle anderen Abonnenten dieses Dokuments. - Awareness: Cursor/Auswahl/Name →
awarenessan 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_updatesangehä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 neuenstatezusammen, schreibtstate,state_vector,size_bytes,titleund löscht die verarbeiteten Updates, alles in einer Transaktion.
- alle offenen Updates in
- 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 demY.Doc(ydoc.transact(() => …, origin)). - Lesen: Eine Vue-Spiegelung des
Y.Doc(perobserveDeep), 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 demY.Docliefert; dann Funktion für Funktion die Schreibpfade umstellen. Tests insrc/**/__tests__sichern jeden Schritt ab. localStorage-Speicherung entfällt; an ihre Stelle tritty-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/colOrderlegen die Reihenfolge fest. Einfügen = ID in die Liste einfügen; kein Verschieben von Zellen. - Zellen sind über
colId:rowIdadressiert. - 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 inA1ü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-indexeddbhä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_originsauf die eigene Domain. - Enumeration: UUIDs v4,
404statt403, 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).
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,documentsmit 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 stattlocalStorage. BestehendelocalStorage-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
- 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.
- Aufbewahrung von Gast-Dokumenten: 12 Monate ohne Öffnen, ok?
- Server: bestehender Rails-Server (
rails.wicom.li) oder eigene Instanz für numolus? - Mailanbieter: welcher SMTP-Dienst?
- Editoren dürfen teilen? Konzept: Nein, nur Besitzer.
- 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 |