From bad90753d026a559d96f58b7bcab9acd60a2384e Mon Sep 17 00:00:00 2001 From: Florian Wilde Date: Sat, 25 Jul 2026 23:38:19 +0200 Subject: [PATCH] docs: Abgleich dokumentieren und Roadmap anlegen README und FEATURES beschreiben den automatischen Abgleich samt Zurueckhalten nach Fehlschlaegen und dem Weg ueber einen externen Zeitgeber. Neu ist ROADMAP.md: die bisherige Liste "Ideen fuer spaeter" war eine lose Aufzaehlung ohne Reihenfolge und ohne Aufwandsabschaetzung. Jetzt nach Prioritaet gegliedert, jeder Punkt mit Aufwand und - wo es welche gibt - offenen Fragen. Ganz oben steht Export und Import in vier Stufen, inklusive der Frage, ob Git-Tokens mitgehen sollen (Vorschlag: nein). Am Ende steht bewusst auch, was nicht kommt und warum - das erspart spaetere Diskussionen. Co-Authored-By: Claude Opus 5 (1M context) --- FEATURES.md | 45 +++++++++---- README.md | 21 ++++++- ROADMAP.md | 178 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 231 insertions(+), 13 deletions(-) create mode 100644 ROADMAP.md diff --git a/FEATURES.md b/FEATURES.md index bbb268c..008625e 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -172,6 +172,38 @@ Firmen-Gitea nebeneinander. - **Snapshot-Prinzip**: Alle Daten werden in der Datenbank abgelegt. Das Dashboard bleibt ohne Netzverbindung oder bei erreichtem Rate-Limit vollständig nutzbar. + +### 4.4 Automatischer Abgleich + +Standardmäßig **aus** — jeder Durchlauf verbraucht fremde API-Kontingente, das soll eine +bewusste Entscheidung sein. Einschalten in den Admin-Einstellungen. + +| Einstellung | Bedeutung | +| --- | --- | +| Abstand | 15 Minuten bis täglich | +| Projekte je Durchlauf | 1–100, Voreinstellung 25 | +| Fertige und archivierte auslassen | Dort ändert sich selten noch etwas | + +Wie der Durchlauf arbeitet: + +- Der Zeitgeber läuft im Serverprozess selbst (`instrumentation.ts`), prüft minütlich, ob + ein Durchlauf fällig ist, und startet ihn. Kein zusätzlicher Container, kein externer + Cron. Zwei Durchläufe überschneiden sich nie. +- **Am längsten nicht abgeglichene zuerst.** Was nicht in den Durchlauf passt, kommt beim + nächsten Mal. +- **Zurückhalten nach Fehlschlägen:** Nach jedem Fehlversuch verdoppelt sich der Abstand + bis zum nächsten Versuch (gedeckelt beim 16-fachen). Ein Repository mit abgelaufenem + Token blockiert damit nicht dauerhaft das Kontingent. +- Kurze Pause zwischen zwei Projekten, damit kein Schwall entsteht. +- **Pro Projekt abschaltbar** über einen Schalter im Projektdialog. Manuell + synchronisieren geht unabhängig davon immer. +- Der Adminbereich zeigt letzten und nächsten Durchlauf sowie einen Kurzbericht + (aktualisiert / fehlgeschlagen / zurückgestellt) und hat einen Knopf **Jetzt abgleichen**. +- Wer lieber von außen taktet, lässt den Automatismus aus und ruft + `POST /api/admin/sync/run` per eigenem Cron auf. + +Der Abgleich läuft über alle Konten hinweg — er ist ein Serverauftrag, keine +Dateneinsicht. Ein Administrator sieht dadurch weiterhin keine fremden Projekte. - **URL-Erkennung** für `https://…`, `git@host:owner/repo.git` und GitLab-Weboberflächen-URLs mit `/-/tree/…`; verschachtelte Gruppenpfade bleiben erhalten. - **Ohne Token** funktionieren öffentliche Repositories, mit deutlich strengerem Rate-Limit. @@ -270,14 +302,5 @@ Alles, was die Oberfläche kann, ist damit auch scriptbar. Übersicht in der ## 7. Ideen für später -Bewusst nicht umgesetzt, aber vorgemerkt: - -- Kanban-Board mit Drag & Drop zwischen den Statusspalten -- Webhooks, damit Pushes den Snapshot ohne Knopfdruck aktualisieren -- Markdown-Rendering in Beschreibung und Notizen -- Volltextsuche über Notizen hinweg -- Export eines Projekts als Markdown -- Automatischer Sync im Hintergrund (Intervall pro Verbindung) -- Passwort-Zurücksetzen per E-Mail (aktuell setzt ein Administrator das Passwort neu) -- Zwei-Faktor per TOTP als Alternative zum Passkey -- Geteilte Projekte zwischen Konten (heute ist die Trennung absichtlich hart) +Was als Nächstes kommen könnte, steht mit Aufwandsschätzung und offenen Fragen in +**[ROADMAP.md](ROADMAP.md)** — gedacht zum Durchsprechen und schrittweisen Abarbeiten. diff --git a/README.md b/README.md index c9704c7..2007bf2 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,8 @@ den Admin-Einstellungen. Alle Daten liegen in **deiner lokalen PostgreSQL**. Es gibt keinen Cloud-Dienst dahinter, Access Tokens werden verschlüsselt abgelegt. -Eine vollständige Auflistung aller Funktionen steht in **[FEATURES.md](FEATURES.md)**. +Eine vollständige Auflistung aller Funktionen steht in **[FEATURES.md](FEATURES.md)**, +geplante Erweiterungen in **[ROADMAP.md](ROADMAP.md)**. --- @@ -181,6 +182,21 @@ Nebula auffindbare Credentials nutzt. Der Snapshot bleibt in der Datenbank, das Dashboard funktioniert also auch offline. Ohne Token gehen nur öffentliche Repositories, mit strengem Rate-Limit. +### Automatisch statt auf Knopfdruck + +Unter **Admin-Einstellungen → Automatischer Abgleich** lässt sich der Sync in den +Hintergrund verlegen: Abstand von 15 Minuten bis täglich, Anzahl Projekte je Durchlauf, +und wahlweise ohne fertige und archivierte Projekte. Standardmäßig ist er **aus**, weil +jeder Durchlauf API-Kontingent verbraucht. + +Der Zeitgeber läuft im Serverprozess — kein zusätzlicher Container, kein externer Cron. +Nach Fehlschlägen wird ein Repository mit wachsendem Abstand zurückgehalten, damit ein +abgelaufener Token nicht dauerhaft Kontingent verbrennt. Einzelne Projekte lassen sich im +Projektdialog ausnehmen; manuell synchronisieren geht immer. + +Wer lieber von außen taktet, lässt den Automatismus aus und ruft +`POST /api/admin/sync/run` per eigenem Cron auf. + --- ## Projektstruktur @@ -250,7 +266,8 @@ ausschließlich Daten des angemeldeten Kontos. | `POST` | `/api/account/password` | Eigenes Passwort setzen | | `GET` `DELETE` | `/api/account/sessions` | Eigene Sitzungen / überall abmelden | | `PATCH` `DELETE` | `/api/account/passkeys/:id` | Passkey umbenennen / entfernen | -| `GET` `PATCH` | `/api/admin/settings` | Betriebsart und Registrierung (Admin) | +| `GET` `PATCH` | `/api/admin/settings` | Betriebsart, Registrierung, Abgleich (Admin) | +| `POST` | `/api/admin/sync/run` | Abgleich sofort anstoßen (Admin) | | `GET` `POST` | `/api/admin/users` | Konten auflisten / anlegen (Admin) | | `PATCH` `DELETE` | `/api/admin/users/:id` | Konto ändern / löschen (Admin) | | `GET` `POST` | `/api/projects` | Projekte auflisten / anlegen | diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..485e7b2 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,178 @@ +# Roadmap + +Sammlung dessen, was als Nächstes kommen könnte — zum Durchsprechen und +Stück für Stück abarbeiten. Reihenfolge ist ein Vorschlag, keine Festlegung. + +**Aufwand:** `S` = überschaubar · `M` = halber Tag · `L` = größerer Brocken + +Was bereits steht, listet [FEATURES.md](FEATURES.md). + +--- + +## 1 · Als Nächstes empfohlen + +### 1.1 Export und Import `M` + +Dein Vorschlag, in vier Stufen — jede für sich nutzbar: + +| Stufe | Inhalt | +| --- | --- | +| **Projekt-Export** | Ein Projekt oder alle als JSON: Stammdaten, Notizen, Repo-Verknüpfung. Ein Klick auf der Projektseite, einer im Dashboard für alles. | +| **Projekt-Import** | JSON hochladen, Vorschau, dann übernehmen. Konfliktstrategie wählbar: überspringen · umbenennen · überschreiben. | +| **Markdown-Export** | Ein Projekt als lesbares `.md` — Beschreibung, Notizen, aktueller Git-Stand. Gut zum Archivieren oder für ein README. | +| **Voll-Backup** | `pg_dump` aus dem Container heraus, per Knopf im Adminbereich als Datei. Plus dokumentierter Rückweg. | + +**Offene Fragen, die wir klären sollten:** +- **Git-Tokens mitexportieren?** Mein Vorschlag: **nein**. Die Verbindung wird + mitexportiert (Name, System, Basis-URL), das Token muss beim Import neu + hinterlegt werden. Ein Export-JSON landet sonst schnell irgendwo, wo es + nicht hingehört. +- **Reichweite:** Export der eigenen Daten für jeden — Voll-Backup nur für + Administratoren? +- **Snapshots mitnehmen?** Ich würde sie weglassen: sie sind reproduzierbar + und blähen die Datei auf. Ein Sync nach dem Import holt sie zurück. + +### 1.2 Markdown in Beschreibung und Notizen `S` + +Heute wird alles als reiner Text dargestellt. Mit Markdown werden aus +`- [ ] Aufgabe` echte Checklisten, Codeblöcke bekommen Hervorhebung, Links +werden klickbar. + +Zu beachten: HTML muss beim Rendern entfernt werden, sonst reißt es ein +XSS-Loch. Mit `react-markdown` plus `rehype-sanitize` ist das sauber lösbar. + +### 1.3 Volltextsuche über Notizen `S` + +Die Suche im Board deckt Namen, Kurzbeschreibung und Tags ab — Notizen nicht. +Postgres kann das nativ (`tsvector` mit deutscher Konfiguration), also ohne +zusätzlichen Dienst. + +### 1.4 Kanban-Board mit Drag & Drop `M` + +Die gruppierte Ansicht gibt es schon, aber Statuswechsel geht nur über das +Menü. Spalten mit Ziehen und Ablegen wären der natürlichere Weg. + +Bibliothek: `@dnd-kit` — leichtgewichtig, tastaturbedienbar. Auf Mobilgeräten +bleibt die Listenansicht. + +--- + +## 2 · Danach + +### 2.1 Offene Pull Requests und Issues als Liste `S` + +Aktuell werden sie nur gezählt. Titel, Autor, Alter und Link wären deutlich +nützlicher — die Daten holen wir ohnehin schon ab. + +### 2.2 CI-Status je Branch `M` + +Grün oder rot direkt an der Projektkarte, gespeist aus GitHub Actions, +GitLab Pipelines und Gitea Actions. Erfordert je Provider einen weiteren +Endpunkt und einen zusätzlichen Token-Scope. + +### 2.3 Webhooks statt Polling `M` + +Ein Push aktualisiert den Snapshot sofort, statt bis zum nächsten Durchlauf +zu warten. Braucht einen öffentlich erreichbaren Endpunkt mit +Signaturprüfung je Provider — sinnvoll erst, wenn die Instanz von außen +erreichbar ist. Der Zeitplan bleibt als Rückfalllösung. + +### 2.4 Commit-Aktivität als Verlauf `S` + +Kleine Sparkline auf der Karte, Heatmap auf der Projektseite. Datenbasis ist +da, es fehlt nur die Darstellung. + +### 2.5 Aufgaben und Checklisten `M` + +Eigene Entität statt Freitext-Notiz, mit Häkchen und automatisch +berechnetem Fortschritt. Ersetzt das manuelle Schieben des Reglers. + +### 2.6 Benachrichtigungen `M` + +Bei Sync-Fehlern, neuen Releases oder Projekten, die lange stillstehen. +Kanäle: E-Mail (SMTP), ntfy, generischer Webhook. Zusammen mit dem +automatischen Abgleich ergibt das ein brauchbares Frühwarnsystem. + +--- + +## 3 · Größere Brocken + +### 3.1 Automatisierte Tests und CI `L` + +Aktuell prüfe ich jede Änderung von Hand — Typecheck, Build, API-Durchläufe, +Browser-Screenshots. Das gehört in eine Pipeline: + +- **Vitest** für die Logik: URL-Parsing, SSRF-Regeln, Passwort-Hashing, + Backoff-Berechnung +- **Playwright** für die Wege durch die App: Einrichtung, Anmeldung, + Datentrennung +- **GitHub Actions** oder Gitea Actions, je nachdem wohin du das Repo legst + +Aus meiner Sicht der wertvollste Punkt der ganzen Liste, sobald das Projekt +länger lebt: er macht alles Weitere billiger und sicherer. + +### 3.2 Mehrere Repositories je Projekt `M` + +Frontend und Backend getrennt, aber ein Projekt. Erfordert eine Zwischen­tabelle +und Anpassungen in der Anzeige. + +### 3.3 Zwei-Faktor per TOTP `M` + +Als Alternative zum Passkey — nützlich, wenn die Instanz aus dem Internet +erreichbar ist und nicht jedes Gerät Passkeys kann. + +### 3.4 Passwort-Zurücksetzen per E-Mail `M` + +Heute setzt ein Administrator das Passwort neu. Selbstbedienung braucht SMTP +und damit eine weitere Konfiguration — lohnt erst im Mehrbenutzerbetrieb. + +### 3.5 Mehrsprachigkeit `L` + +Die Oberfläche ist durchgängig deutsch verdrahtet. Englisch dazu wäre eine +Voraussetzung, falls du das Projekt veröffentlichen willst. + +--- + +## 4 · Kleinigkeiten + +| Idee | Aufwand | Nutzen | +| --- | --- | --- | +| Schnellsuche per `Strg+K` | `S` | Springt direkt zu Projekt oder Aktion | +| Mehrfachauswahl im Board | `S` | Status oder Tags für mehrere auf einmal | +| Aktivitätsverlauf je Projekt | `S` | Wer hat wann was geändert | +| Projektvorlagen | `S` | Neues Projekt mit vorgefüllten Tags und Notizen | +| Hell/Dunkel umschaltbar | `M` | Aktuell nur dunkel | +| Eigenes Logo und Farbe | `S` | Ergänzt `APP_NAME` | +| PWA-Manifest | `S` | Auf dem Handy als App installierbar | +| Barrierefreiheits-Durchsicht | `M` | Fokusreihenfolge, Screenreader, Kontraste | +| `prisma.config.ts` | `S` | Beseitigt die Deprecation-Warnung vor Prisma 7 | +| Audit-Log für Adminaktionen | `M` | Nachvollziehbar, wer Konten geändert hat | + +--- + +## 5 · Bewusst nicht + +Damit klar ist, was **nicht** kommt und warum: + +- **Geteilte Projekte zwischen Konten.** Die Trennung ist derzeit hart und + einfach zu prüfen. Freigaben bringen eine Rechteverwaltung mit sich — nur + sinnvoll, wenn wirklich mehrere Leute zusammenarbeiten. +- **Eigene Git-Operationen** (klonen, committen, pushen). Nebula ist eine + Übersicht, keine Entwicklungsumgebung. +- **Zeiterfassung, Rechnungen, Kundenverwaltung.** Andere Baustelle. +- **Cloud-Synchronisation.** Die Daten bleiben in deiner Datenbank; das ist + der Punkt. + +--- + +## Erledigt + +| | | +| --- | --- | +| Dashboard mit Status, Notizen, Git-Anbindung | ✓ | +| GitHub, GitLab und Gitea | ✓ | +| Benutzerverwaltung, Passwort und Passkeys | ✓ | +| Einzel- und Mehrbenutzerbetrieb | ✓ | +| Härtung: CSRF, CSP, SSRF, Ratenbegrenzung, Datentrennung | ✓ | +| Docker- und Standalone-Betrieb | ✓ | +| Automatischer Abgleich mit Zeitplan | ✓ |