- invoice_billing_periods (PK Vertrag+Periodenbeginn): jede Periode wird genau einmal abgerechnet, auch bei parallelen Läufen (INSERT IGNORE in der Transaktion). Gelöschter Entwurf gibt die Periode frei (CASCADE), Storno hält sie belegt bis zur ausdrücklichen Freigabe (POST /invoices/:id/release-periods, Knopf an der stornierten Rechnung). - Perioden nach Intervall des Preis-Snapshots (monatlich/jährlich, im Voraus), nicht über die wirksame Kündigung hinaus; Handrechnungen mit contract_id gelten bis zu ihrer Periode als abgerechnet; max. 12 je Lauf. - Es entstehen nur Entwürfe (je Kunde einer); ausgestellt wird nie automatisch. Vorschau + Knopf unter Rechnungen → Fällig; automatischer Lauf alle 6 h nur mit Schalter in Einstellungen → Firma (Standard aus). - Migration 041 (auch invoices.created_by NULL für den automatischen Lauf). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .forgejo/workflows | ||
| apps | ||
| bundles | ||
| data | ||
| docs | ||
| migrations | ||
| ops | ||
| packages | ||
| .env.example | ||
| .gitignore | ||
| LICENSE.md | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| tsconfig.base.json | ||
KC@FlessingLabs – Kundencenter
Selbst gehostetes Kundencenter für Hosting-Anbieter, Agenturen und Software-Hersteller: Kunden, Produkte, Bestellungen, Verträge, Rechnungen, Support-Tickets und Lizenzen in einer Oberfläche – mit Anbindung an KeyHelp und an das FlessingLabs-Lizenzsystem. Modularer Monolith in TypeScript (Fastify, Next.js, MariaDB).
| Prozess | Pfad | Port (nur 127.0.0.1) | Aufgabe |
|---|---|---|---|
kc-api |
apps/api |
4100 | Fastify-API (/v1/*), Module, Rechte, Audit |
kc-worker |
apps/worker |
4102 (Health) | Persistente Aufträge, Discord-Bot, E-Mail-Posteingang |
kc-web |
apps/web |
4101 | Next.js-Oberfläche, leitet /api/* an die API weiter |
Funktionen
- Konten und Sicherheit: Login mit Passwort + TOTP, Wiederherstellungscodes, Sitzungsverwaltung, Einladungen, Rollen für Personal und Kunden, Audit-Protokoll mit Hash-Kette.
- Kunden: Privat- und Geschäftskunden, Rechnungsanschrift, Übernahme aus KeyHelp, Kundenansicht („Als Kunde ansehen“).
- Produkte, Bestellungen, Verträge: versionierte Produkte, Bestellungen mit Freigabe und unveränderlichem Preis-Snapshot, Laufzeiten, Kündigung, automatische Verlängerung mit Erinnerung (
docs/produkte-bestellungen-vertraege.md). - Bereitstellung über Connectoren: KeyHelp (Hosting-Konten, Domains, Postfächer, Datenbanken) und Lizenzsystem (
docs/connector-vertrag.md,docs/connector-keyhelp.md). - Lizenzverwaltung: Übersicht, Vergabe mit Vertrag oder ohne Berechnung (Lizenz, Test, Add-on), Geräte freigeben, Sperren/Verlängern/Widerrufen, Limits und Funktionsumfang; Kunden sehen ihre Lizenzen und geben eigene Geräte frei.
- Rechnungen: Entwurf → Ausstellen (unveränderlich) → Bezahlt/Storno, PDF, DATEV-Export (
docs/rechnungen.md). - Support: Tickets je Kunde mit internen Notizen und Anhängen, E-Mail-Posteingang (IMAP), Discord-Bot mit eigenem Kanal je Ticket.
- Betrieb: verschlüsselte tägliche Backups mit automatischem Wiederherstellungstest (
docs/betrieb-backup-restore.md).
Testmodus und Lizenz
Ohne Lizenzschlüssel läuft das Kundencenter im Testmodus:
| Testmodus | Mit Lizenz | |
|---|---|---|
| Personal-Konten | 1 | laut Lizenz |
| Kunden | 2 | laut Lizenz |
| Discord-Bot, E-Mail-Posteingang (IMAP), DATEV-Export, Backups auf externe Ziele | – | ✓ |
Alles andere ist im Testmodus voll nutzbar. Eine Lizenz gibt es bei FlessingLabs (https://flessinglabs.com); den Schlüssel
unter Einstellungen → Lizenz eintragen, er wird regelmäßig bei licensing.flessinglabs.com geprüft (7 Tage offline
möglich). Läuft eine Lizenz ab, gilt wieder der Testmodus – bestehende Daten bleiben vollständig erhalten und nutzbar,
nur Neuanlagen über die Grenzen hinaus und die Zusatzfunktionen pausieren. Nutzungsbedingungen: LICENSE.md.
Installation (Debian/Ubuntu)
Voraussetzungen: Node.js ≥ 22, pnpm 10, MariaDB ≥ 10.6, ein Reverse-Proxy mit HTTPS (Apache, nginx, Caddy …),
für Backups gpg und rclone.
# 1. Benutzer und Code
useradd --system --home-dir /var/lib/kundencenter --shell /usr/sbin/nologin kundencenter
git clone https://forge.flessinghome.de/flessinglabs/kundencenter.git /srv/kundencenter
chown -R kundencenter: /srv/kundencenter
cd /srv/kundencenter && sudo -u kundencenter pnpm install --frozen-lockfile && sudo -u kundencenter pnpm build
# 2. Datenbank (Zeichensatz utf8mb4 / utf8mb4_unicode_ci ist wichtig)
mysql -e "CREATE DATABASE kundencenter CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kundencenter'@'localhost' IDENTIFIED BY '<passwort>';
GRANT ALL ON kundencenter.* TO 'kundencenter'@'localhost';
GRANT ALL ON kundencenter_restoretest.* TO 'kundencenter'@'localhost';"
# 3. Konfiguration (Vorlage: .env.example; Kommentare nie hinter einen Wert schreiben)
install -d -m 700 /etc/kundencenter
install -d -o kundencenter -m 755 /var/lib/kundencenter/requests
install -d -o kundencenter -m 750 /var/lib/kundencenter/ticket-attachments
install -d -m 700 /var/backups/kundencenter
# /etc/kundencenter/db.env und /etc/kundencenter/app.env anlegen, chmod 600
# 4. Schema und erster Superadmin (Passwort wird abgefragt)
cd /srv/kundencenter && pnpm migrate
pnpm cli create-superadmin --email=admin@example.de --name="Vorname Nachname"
# 5. Dienste
cp ops/systemd/kc-* /etc/systemd/system/ && systemctl daemon-reload
systemctl enable --now kc-api kc-web kc-worker kc-backup.timer kc-restore-test.timer kc-backup-request.path
Reverse-Proxy: alles auf http://127.0.0.1:4101 weiterleiten und X-Forwarded-Proto: https setzen. Beispiel Apache:
ProxyPass / http://127.0.0.1:4101/
ProxyPassReverse / http://127.0.0.1:4101/
RequestHeader set X-Forwarded-Proto "https"
Danach anmelden, 2FA einrichten, unter Einstellungen Firma, E-Mail (SMTP) und Backup-Passwort hinterlegen.
Update
cd /srv/kundencenter && systemctl start kc-backup # vorher sichern
sudo -u kundencenter git pull && sudo -u kundencenter pnpm install --frozen-lockfile && sudo -u kundencenter pnpm build
pnpm migrate && systemctl restart kc-api kc-web kc-worker
Betrieb
systemctl status kc-api kc-worker kc-web # Dienste (Autostart, Restart=always)
journalctl -u kc-api -f # Logs
pnpm cli reset-password --email=… # Passwort zurücksetzen
Health: GET :4100/v1/health, GET :4100/v1/ready, GET :4102/health.
Geheimnisse liegen nie im Repo, sondern in /etc/kundencenter/*.env (chmod 600). KC_BASE_URL muss exakt der Browser-Adresse entsprechen.
Discord-Bot
Unter Einstellungen → Discord Bot-Token, Server-ID und Kanäle eintragen (Anleitung auf der Seite). Mit einer Ticket-Kategorie bekommt jedes offene Ticket einen eigenen Kanal, sichtbar nur für die Support-Rollen und den Kunden. Kunden und Personal verknüpfen ihr Discord-Konto unter „Mein Konto“. Erfordert eine Lizenz.
Modularität
API-Module liegen in apps/api/src/modules/<name> und implementieren KcModule (core/module.ts). Sie werden in
modules/index.ts eingetragen, registrieren Routen und Rechte und sprechen nur über core/* und Jobs miteinander.
Neue Anbieter kommen als Connector unter packages/connector-* hinzu (docs/connector-vertrag.md).
Tests
Ein Befehl, nur Docker nötig (frischer Checkout, Dummy-Schlüssel, Wegwerf-MariaDB im RAM – nie die Produktivdatenbank):
ops/test/run.sh
Ablauf (ops/test/ci.sh, identisch in der CI unter .forgejo/workflows/ci.yml): pnpm install --frozen-lockfile →
pnpm build (vor den Tests, weil die Pakete über dist/ aufgelöst werden) → Plattform-, Connector- und API-Tests.
Die API-Integrationstests legen die Datenbank kundencenter_test bei jedem Lauf neu an und starten nur mit
KC_TEST_DB_RESET=1 (in der Testumgebung gesetzt) – auf einem Produktivhost brechen sie daher sofort ab.
Abgedeckt u. a.: Login, Sperre, CSRF, 2FA-Pflicht, Sitzungen, Kundenanlage, Mandantentrennung, Rechte, Audit-Kette,
Rechnungen (inkl. Nebenläufigkeit), Migrationen (Sperre/Wiederanlauf), Lizenzgrenzen und -signatur, IMAP-Zuordnung.
Browser-Abnahme (Playwright + axe, eigenes Image mit Chromium):
ops/test/run-e2e.sh
Startet API und Web gegen die Wegwerf-Datenbank kundencenter_e2e und prüft Login mit 2FA (inkl. Replay-Schutz),
Kundenanlage → Einladung → Kundenlogin, Mandantentrennung, Tastaturbedienung, Desktop und 360 px, Hell und Dunkel sowie
WCAG 2.2 AA per axe (schwere/kritische Verstöße lassen den Lauf scheitern). Noch offen: Worker-Tests mit echtem IMAP/Discord.