No description
Find a file
Claude (KI) 441341ccef Soll-Ist-Abgleich Vertrag ↔ Anbieter sichtbar machen (#21)
findDrift (platform/drift.ts) vergleicht den Sollzustand aus dem Vertrag
(aktiv/gesperrt/beendet) mit dem zuletzt beobachteten Ressourcenzustand.
Unsichere Beobachtungen (Anbieter gestört, Daten veraltet, unbekannt)
werden als 'ungewiss' statt als Abweichung gemeldet. Nichts wird
automatisch zurückgeschrieben. GET /admin/drift, Dashboard-Karte.
Deterministischer Test mit sechs Fällen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 13:14:23 +02:00
.forgejo/workflows Browser-Abnahme mit Playwright und axe (#39, #15) 2026-10-06 11:57:20 +02:00
apps Soll-Ist-Abgleich Vertrag ↔ Anbieter sichtbar machen (#21) 2026-10-06 13:14:23 +02:00
bundles CI: Typecheck, Stilprüfung, Abhängigkeits-Audit; Worker-Tests (#96, #14) 2026-10-06 12:59:12 +02:00
data Stand vor Einführung des Nacht-Agenten 2026-09-27 00:51:32 +02:00
docs Kundenangaben an Lizenzen nachziehen und auf Wunsch leeren (#64) 2026-10-06 13:11:46 +02:00
migrations Abrechnungslauf: Entwürfe je Vertragsperiode, genau einmal (#50) 2026-10-06 12:04:01 +02:00
ops Ein-Befehl-Entwicklungsstack mit Mailpit (#14) 2026-10-06 13:00:57 +02:00
packages Soll-Ist-Abgleich Vertrag ↔ Anbieter sichtbar machen (#21) 2026-10-06 13:14:23 +02:00
.env.example KC@FlessingLabs 1.0.0: Testmodus ohne Lizenz, Installationsanleitung, Nutzungsbedingungen 2026-10-02 13:31:53 +02:00
.gitignore Browser-Abnahme mit Playwright und axe (#39, #15) 2026-10-06 11:57:20 +02:00
LICENSE.md KC@FlessingLabs 1.0.0: Testmodus ohne Lizenz, Installationsanleitung, Nutzungsbedingungen 2026-10-02 13:31:53 +02:00
package.json CI: Typecheck, Stilprüfung, Abhängigkeits-Audit; Worker-Tests (#96, #14) 2026-10-06 12:59:12 +02:00
pnpm-lock.yaml CI: Typecheck, Stilprüfung, Abhängigkeits-Audit; Worker-Tests (#96, #14) 2026-10-06 12:59:12 +02:00
pnpm-workspace.yaml Stand vor Einführung des Nacht-Agenten 2026-09-27 00:51:32 +02:00
README.md Ein-Befehl-Entwicklungsstack mit Mailpit (#14) 2026-10-06 13:00:57 +02:00
tsconfig.base.json Stand vor Einführung des Nacht-Agenten 2026-09-27 00:51:32 +02:00

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).

Lokale Entwicklung

Ein Befehl, nur Docker nötig:

ops/dev/run.sh

Startet MariaDB (eigenes Volume), Mailpit und API/Worker/Web im Watch-Modus mit Dummy-Konfiguration (ops/dev/dev.env). Kundencenter: http://127.0.0.1:4101 (Anmeldung dev@kundencenter.local / entwicklung-passwort-123, 2FA wird beim ersten Login eingerichtet), ausgehende Mails: http://127.0.0.1:8025. Zurücksetzen: docker compose -f ops/dev/compose.yml down -v. Vor dem Commit: pnpm check (Modulgrenzen + Stilprüfung).

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.