85 lines
6.1 KiB
Markdown
85 lines
6.1 KiB
Markdown
# Project Insights
|
|
|
|
Stand: 2026-05-07
|
|
|
|
Diese Notizen halten die aktuellen Erkenntnisse aus einer kurzen Code- und Deployment-Sichtung fest. Sie sind als Arbeitsgrundlage fuer die naechsten Iterationen gedacht.
|
|
|
|
## Aktueller Eindruck
|
|
|
|
Paperless Contract Companion hat bereits eine solide Basis: Express-API, SQLite-Persistenz, React/MUI-Frontend, optionale Paperless-Anbindung, Kategorien, Settings, iCal-Feed sowie Mail- und ntfy-Benachrichtigungen sind vorhanden. Das Projekt ist klein genug, um gezielt zu haerten, bevor weitere Integrationen eingebaut werden.
|
|
|
|
Die naechsten wertvollsten Arbeiten liegen weniger in neuen UI-Seiten, sondern in Betriebssicherheit, Auth-Haertung, Testbarkeit und sauberer Fristenlogik.
|
|
|
|
## Wichtige Erkenntnisse
|
|
|
|
### 1. Kategorie-Endpunkte sind aktuell nicht authentifiziert
|
|
|
|
`/categories` wird in `src/index.ts` vor `app.use(authenticateRequest)` registriert. Dadurch sind Listen, Anlegen und Loeschen von Kategorien auch dann erreichbar, wenn Auth fuer den Rest der API aktiv ist. `healthz`, `auth/status`, `auth/login` und der token-geschuetzte iCal-Feed koennen oeffentlich bleiben; Kategorien sollten aber hinter Auth liegen.
|
|
|
|
Empfohlene naechste Arbeit: Auth-Middleware vor die Kategorie-Routen verschieben oder gezielt auf die Kategorie-Routen anwenden.
|
|
|
|
### 2. Secrets und Auth-Passwort werden im Settings-Store im Klartext gespeichert
|
|
|
|
`settingsStore` speichert Werte JSON-kodiert in SQLite. Das betrifft unter anderem `paperlessToken`, `mailPassword`, `ntfyToken`, `authPassword` und `icalSecret`. Fuer ein Homelab kann das kurzfristig akzeptabel sein, produktiv sollte mindestens das App-Login-Passwort gehasht werden. Tokens und Mail-Passwoerter sollten entweder in Portainer-Environment-Variablen bleiben oder verschluesselt abgelegt werden.
|
|
|
|
Empfohlene naechste Arbeit: Auth-Passwort mit bcrypt/argon2 speichern; optional Secrets nur ueber Environment erlauben oder mit einem Master-Key verschluesseln.
|
|
|
|
### 3. Benachrichtigungen koennen sich wiederholen
|
|
|
|
Der Scheduler ruft in jedem Intervall `listUpcomingDeadlines()` auf und sendet alle gefundenen Fristen erneut. Es gibt keine Tabelle oder Logik, die bereits versendete Alerts pro Vertrag, Deadline und Kanal merkt. Bei einem Intervall von 60 Minuten kann das zu sehr vielen identischen Mail- oder ntfy-Meldungen fuehren.
|
|
|
|
Empfohlene naechste Arbeit: Tabelle `notification_history` einfuehren und pro Deadline nur einmal oder nach definierter Eskalationslogik erinnern, z. B. bei 45, 14, 7, 1 und 0 Tagen.
|
|
|
|
### 4. Auto-Renewal wird noch nicht fachlich berechnet
|
|
|
|
Die Datenfelder `autoRenew` und `renewalPeriodMonths` sind vorhanden, aber `listUpcomingDeadlines()` berechnet nur `contractEndDate - terminationNoticeDays`. Bei automatisch verlaengernden Vertraegen sollte die naechste relevante Laufzeitperiode berechnet werden, sonst verschwinden wichtige Fristen nach dem urspruenglichen Enddatum aus dem Blick.
|
|
|
|
Empfohlene naechste Arbeit: Eine zentrale Fristenberechnung bauen, die Startdatum, Enddatum, Kuendigungsfrist, automatische Verlaengerung und Verlaengerungsperiode beruecksichtigt.
|
|
|
|
### 5. Tests und CI fehlen
|
|
|
|
Root- und Frontend-`package.json` enthalten TypeScript-Builds, aber keine Tests, keine Linting-Skripte und keine CI-Konfiguration. Das ist der groesste Hebel, um kuenftige Aenderungen an Fristen, Auth und Settings sicher zu machen.
|
|
|
|
Empfohlene naechste Arbeit: Backend-Tests fuer Contract CRUD, Settings, Auth, iCal und Scheduler-Fristenlogik ergaenzen; Frontend-Tests fuer Login, Contract-Form und Settings; CI mit `npm run check`, Frontend-Build und `docker compose config`.
|
|
|
|
### 6. Deployments sind jetzt Portainer-freundlicher, brauchen aber Secret-Rotation
|
|
|
|
Der Stack wurde auf Portainer-Environment-Variablen, Healthchecks und Compose-Namespacing umgestellt. Vorher lag ein Paperless-Token direkt im YAML und wurde bereits gepusht. Auch wenn er jetzt entfernt ist, bleibt er in der Git-Historie.
|
|
|
|
Empfohlene naechste Arbeit: Paperless-Token in paperless-ngx rotieren und produktive Secrets nur noch in Portainer pflegen.
|
|
|
|
### 7. Backup und Restore fehlen als Betriebsfunktion
|
|
|
|
Die SQLite-Datenbank liegt in einem Docker-Volume. Das ist einfach, aber Portainer-User brauchen einen klaren Backup- und Restore-Weg fuer `contracts.db` und die WAL-Dateien.
|
|
|
|
Empfohlene naechste Arbeit: Dokumentierten Backup-Job oder Admin-Export ergaenzen; mindestens eine Anleitung fuer Volume-Backup und Restore in Portainer.
|
|
|
|
### 8. Listen und Dashboard skalieren nur begrenzt
|
|
|
|
Das Frontend laedt aktuell groessere feste Ausschnitte, z. B. 500 Vertraege in der Liste und 200 im Dashboard, und filtert clientseitig. Fuer kleine Installationen reicht das. Bei wachsendem Bestand waeren serverseitige Suche, Filter, Sortierung und Rueckgabe von Gesamtzahlen stabiler.
|
|
|
|
Empfohlene naechste Arbeit: API um `query`, `category`, `sort`, `direction`, `skip`, `limit` und `total` erweitern; Frontend-Tabelle darauf umstellen.
|
|
|
|
### 9. Import, Export und Paperless-Onboarding waeren hoher Nutzwert
|
|
|
|
Die Paperless-Suche ist vorhanden, aber es gibt noch keinen Massenimport aus Paperless-Suchtreffern, CSV-Import oder CSV/JSON-Export. Gerade fuer bestehende Vertragsarchive waere das wahrscheinlich wertvoller als weitere Integrationen.
|
|
|
|
Empfohlene naechste Arbeit: CSV-Export und CSV-Import als erstes bauen; danach optional Paperless-Saved-Search-Import.
|
|
|
|
### 10. Aufraeumen kleiner Altlasten
|
|
|
|
Im Frontend liegt `frontend/src/routes/ContractForm.tsx.orig`. Solche Backup-Dateien im Repository machen Reviews und Suchen unnoetig lauter. Ausserdem gibt es ohne Lockfiles keine voll reproduzierbaren npm-Installationen.
|
|
|
|
Empfohlene naechste Arbeit: `.orig`-Datei entfernen, `package-lock.json` fuer Root und Frontend erzeugen und Dockerfiles mittelfristig auf `npm ci` umstellen.
|
|
|
|
## Priorisierte naechste Schritte
|
|
|
|
1. Kategorie-Routen authentifizieren.
|
|
2. Notification-Dedupe und Fristenhistorie einfuehren.
|
|
3. Zentrale Auto-Renewal-Fristenberechnung mit Tests bauen.
|
|
4. Testsuite und CI-Grundlage ergaenzen.
|
|
5. Secrets haerten und Paperless-Token rotieren.
|
|
6. Backup/Restore fuer Portainer-Betrieb dokumentieren oder automatisieren.
|
|
7. CSV-Import/Export und spaeter Paperless-Massenimport ergaenzen.
|
|
|