195 lines
8.6 KiB
Markdown
195 lines
8.6 KiB
Markdown
# Paperless Contract Companion
|
||
|
||
Begleitdienst zur Verwaltung von Vertragsmetadaten (Laufzeiten, Kündigungsfristen, Kosten) mit moderner Weboberfläche, Terminüberwachung und Benachrichtigungen. Der Service ist in TypeScript geschrieben (Express + React) und kann eigenständig oder als Ergänzung zu [paperless-ngx](https://github.com/paperless-ngx/paperless-ngx) betrieben werden.
|
||
|
||
---
|
||
|
||
## Highlights
|
||
|
||
- ✅ **Eigenständige Vertragsdatenbank** auf SQLite (`better-sqlite3`) mit REST-API (Express).
|
||
- ✅ **Paperless-Integration (optional):** Verknüpft Verträge mit Dokumenten, zieht Metadaten per Token, durchsucht paperless direkt aus der UI.
|
||
- ✅ **Kategorie-Verwaltung:** Dropdown mit Vorschlägen, Inline-Neuanlage im Formular & Verwaltung unter Einstellungen.
|
||
- ✅ **Modernes React-Frontend** (Vite + MUI) mit Dashboard, Vertragsliste, Kalender, Detailansicht und umfangreichen Einstellungen.
|
||
- ✅ **Benachrichtigungen & Automatisierung:** Scheduler prüft Deadlines, optionaler Mailversand, ntfy-Push, iCal-Feed zum Abonnieren.
|
||
- ✅ **Konfigurierbare Authentifizierung:** Optionales Login mit JWT, Benutzername/Passwort verwaltbar in den Settings.
|
||
- ✅ **Mehrsprachigkeit:** UI derzeit auf Deutsch und Englisch lokalisiert.
|
||
- ✅ **Docker-ready:** Backend und Frontend als Container, Konfiguration via `docker-compose.yml`.
|
||
|
||
---
|
||
|
||
## Projektüberblick
|
||
|
||
```
|
||
backend/ (TypeScript)
|
||
src/
|
||
index.ts # Express-Server, Routing, Auth, Settings, Calendar, Paperless-Suche
|
||
contractsStore.ts # CRUD auf SQLite
|
||
scheduler.ts # Deadline-Monitor
|
||
paperlessClient.ts # Paperless-Proxy mit Korrespondenten/Tag-Anreicherung
|
||
notifications.ts # SMTP & ntfy-Tests, Benachrichtigungen
|
||
runtimeSettings.ts # Persistente Einstellungen (z.B. Mail, ntfy, Paperless)
|
||
validators.ts # Zod-Schemas
|
||
|
||
frontend/ (React + Vite)
|
||
src/
|
||
routes/ # Dashboard, Contracts, Calendar, Settings, Login
|
||
components/ # Listen, Dialoge, Layout, Snackbar etc.
|
||
api/ # REST-Client (fetch)
|
||
locales/ # de/en Übersetzungen
|
||
```
|
||
|
||
---
|
||
|
||
## Getting Started
|
||
|
||
### Voraussetzungen
|
||
|
||
- Node.js ≥ 20.x (Backend & Frontend)
|
||
- npm oder pnpm
|
||
- optional Docker / Docker Compose
|
||
|
||
### Lokale Entwicklung
|
||
|
||
```bash
|
||
# Backend
|
||
npm install
|
||
npm run dev # startet Express per tsx (Hot-Reload)
|
||
|
||
# Frontend
|
||
cd frontend
|
||
npm install
|
||
npm run dev # http://localhost:5173 (Proxy auf http://localhost:8000/api)
|
||
```
|
||
|
||
> **Hinweis:** Die `node_modules` Verzeichnisse sind aus dem Repository ausgenommen. Vor jedem Build/Start zunächst `npm install` im jeweiligen Ordner ausführen, damit TypeScript (`tsc`) verfügbar ist.
|
||
|
||
### Docker Compose
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
- API: `http://localhost:8112` (siehe Compose)
|
||
- Frontend: `http://localhost:8113`
|
||
- SQLite-Datenbank: Volume `contracts-data` → `/app/data/contracts.db`
|
||
|
||
---
|
||
|
||
## Konfiguration
|
||
|
||
| Variable | Standard | Beschreibung |
|
||
| --- | --- | --- |
|
||
| `PORT` | `8000` | Port des Express-Servers. |
|
||
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error`. |
|
||
| `DATABASE_PATH` | `/app/data/contracts.db` | Pfad zur SQLite-Datei (Volume mounten). |
|
||
| `SCHEDULER_INTERVAL_MINUTES` | `60` | Intervall für Deadline-Checks (5–1440). |
|
||
| `ALERT_DAYS_BEFORE` | `30` | Vorlauf in Tagen für Warnungen. |
|
||
| `AUTH_USERNAME` / `AUTH_PASSWORD` | *(leer)* | Aktiviert JWT-Login, wenn beide gesetzt sind. |
|
||
| `AUTH_JWT_SECRET` | *(leer)* | Signatur-Secret (Pflicht bei aktivem Login). |
|
||
| `AUTH_TOKEN_EXPIRES_IN_HOURS` | `12` | Lebensdauer der Tokens. |
|
||
| `PAPERLESS_BASE_URL` | *(leer)* | API-URL deiner paperless-ngx Instanz. |
|
||
| `PAPERLESS_EXTERNAL_URL` | *(leer)* | Optionale externe URL für Direktlinks im Browser. |
|
||
| `PAPERLESS_TOKEN` | *(leer)* | API-Token aus paperless-ngx. |
|
||
| `NTFY_SERVER_URL` / `NTFY_TOPIC` | *(leer)* | Aktiviert ntfy-Push-Benachrichtigungen. |
|
||
| `NTFY_TOKEN` / `NTFY_PRIORITY` | *(leer)* | Optionaler Bearer-Token & Priorität. |
|
||
| `MAIL_SERVER` / `MAIL_PORT` / `MAIL_USERNAME` / `MAIL_PASSWORD` | *(leer)* | SMTP-Settings (TLS optional über `MAIL_USE_TLS`). |
|
||
| `MAIL_FROM` / `MAIL_TO` | *(leer)* | Absender/Empfänger für Mail-Benachrichtigungen. |
|
||
| `ICAL_SECRET` | *(leer)* | Optional vorgegebenes Token für den iCal-Feed. |
|
||
|
||
### Paperless optional nutzen
|
||
|
||
Paperless ist **nicht verpflichtend**. Lässt du `PAPERLESS_*` leer, bleibt die Vertragsverwaltung voll funktionsfähig (Deadlines, Benachrichtigungen, iCal, ntfy, etc.). Die UI blendet paperless-spezifische Funktionen aus bzw. deaktiviert Buttons und zeigt Hinweise an. Sobald du später eine URL/Token hinterlegst, werden Suche und Direktlinks automatisch freigeschaltet.
|
||
|
||
---
|
||
|
||
## API-Übersicht
|
||
|
||
- `GET /contracts` – Liste aller Verträge (`skip` / `limit`).
|
||
- `POST /contracts` – Vertrag anlegen.
|
||
- `GET /contracts/:id` – Einzelvertrag abrufen.
|
||
- `PUT /contracts/:id` – Vertrag aktualisieren.
|
||
- `DELETE /contracts/:id` – Vertrag löschen.
|
||
- `GET /contracts/:id/paperless-document` – Verknüpftes Paperless-Dokument laden.
|
||
- `GET /categories` – Alle Kategorien.
|
||
- `POST /categories` – Neue Kategorie (legt an oder liefert vorhandene).
|
||
- `DELETE /categories/:id` – Kategorie entfernen.
|
||
- `GET /integrations/paperless/search?q=` – Paperless-Dokumente per Text oder ID finden.
|
||
- `GET /reports/upcoming?days=` – Deadlines innerhalb der nächsten `days` Tage.
|
||
- `GET /calendar/feed.ics?token=` – iCal-Feed für Kündigungsfristen.
|
||
|
||
---
|
||
|
||
## Integrationen
|
||
|
||
### Bereits vorhanden
|
||
|
||
- **paperless-ngx (optional):** Sucht Dokumente, verknüpft sie mit Verträgen, zeigt Metadaten und öffnet Direktlinks zur paperless-Oberfläche.
|
||
- **SMTP-Mail:** Verschickt Erinnerungen sowie Testmails aus den Einstellungen.
|
||
- **ntfy:** Sendet Push-Alerts (Test-Button in den Settings).
|
||
- **iCal-Feed:** Kündigungsfristen abonnierbar in gängigen Kalendern.
|
||
|
||
### Perspektivische Erweiterungen
|
||
|
||
Einige sinnvolle Ergänzungen, falls du die Plattform weiter denkst:
|
||
|
||
- **Nextcloud / ownCloud** – Dokumentenverknüpfung oder Dateiimporte via WebDAV/REST.
|
||
- **Seafile / S3 (MinIO, Wasabi)** – Ablage von Vertrags-PDFs in einem Objektspeicher.
|
||
- **Slack / Microsoft Teams / Mattermost** – Deadlines als Channel-Notifications.
|
||
- **Jira / Asana / Trello** – Automatische Tasks zur Kündigung bzw. Verlängerung.
|
||
- **Banking / Finance APIs** – Abgleich von Zahlungen oder Lastschriften mit Vertragskosten.
|
||
- **CRM-Integration (HubSpot, Salesforce, Pipedrive)** – Verträge direkt im Kundenkontext.
|
||
|
||
Diese Ideen sind in diesem Repository noch **nicht umgesetzt**, aber durch die REST-Architektur vergleichsweise leicht nachrüstbar.
|
||
|
||
---
|
||
|
||
## Status & Roadmap
|
||
|
||
### Erledigt
|
||
|
||
- Backend-API mit Contracts CRUD, Settings-Storage und optionaler Authentifizierung.
|
||
- Scheduler + Notification-Pipeline (Mail, ntfy).
|
||
- Paperless-Integration inkl. Suchdialog, Dokumentdetail, Metadaten-Anreicherung.
|
||
- React-UI mit Dashboard, Kalender, Vertragsliste/-details, Settings.
|
||
- Mehrsprachigkeit (Deutsch/Englisch) inkl. Language Switch.
|
||
- iCal-Feed mit granularen Einträgen und Direktlinks zu Verträgen.
|
||
- Docker-Setup für Backend und Frontend.
|
||
|
||
### In Arbeit / Offene Punkte
|
||
|
||
- Opt-in/Opt-out-Schalter für Paperless in der Oberfläche (UI zeigt bereits Hinweise).
|
||
- Additional Integrations (z. B. Nextcloud, Slack) – Konzept klar, Implementation offen.
|
||
- Weitere Automatisierungen (z. B. automatische Erstellung von Tasks/Kalendereinträgen).
|
||
- Testsuite / CI-Pipeline (derzeit keine automatisierten Tests).
|
||
- Mehrbenutzer-Unterstützung & Rechteverwaltung (derzeit Single-User + optionaler Login).
|
||
|
||
Fühle dich frei, Pull Requests oder Issues mit neuen Ideen zu eröffnen.
|
||
|
||
---
|
||
|
||
## Entwicklung & Beiträge
|
||
|
||
1. Repository klonen, `npm install` im Root und in `frontend/`.
|
||
2. Backend mit `npm run dev`, Frontend mit `npm run dev` starten.
|
||
3. Die jeweiligen `.env` Dateien (oder Docker-Compose Variablen) für deine Umgebung setzen.
|
||
4. Änderungen strukturieren, `npm run build` im Root und im Frontend ausführen, um Typfehler zu erkennen (TypeScript läuft nur mit installierten Modulen).
|
||
5. Pull Request eröffnen.
|
||
|
||
**Coding Guidelines**
|
||
|
||
- TypeScript überall (Backend & Frontend).
|
||
- Zod-Schemas für Request-Validierung.
|
||
- Lass `paperlessClient` die einzige Stelle sein, an der Paperless-HTTP-Aufrufe passieren.
|
||
- UI nutzt React Query + React Hook Form, MUI-Komponenten (Varianten/Theme konsistent halten).
|
||
- Lokalisierte Strings über `react-i18next`.
|
||
|
||
---
|
||
|
||
## Lizenz
|
||
|
||
Noch keine Lizenz festgelegt – bei Bedarf ergänzen (z. B. MIT). Bis dahin gelten die Standardrechte des Autoren.
|
||
|
||
---
|
||
|
||
Viel Spaß mit dem Paperless Contract Companion! Wenn du Feedback oder Integrationsideen hast, gerne melden.
|