No description
Find a file
Claude (KI) 9f9c5c4b65 Abrechnungslauf: Entwürfe je Vertragsperiode, genau einmal (#50)
- 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>
2026-10-06 12:04:01 +02:00
.forgejo/workflows Browser-Abnahme mit Playwright und axe (#39, #15) 2026-10-06 11:57:20 +02:00
apps Abrechnungslauf: Entwürfe je Vertragsperiode, genau einmal (#50) 2026-10-06 12:04:01 +02:00
bundles Stand vor Einführung des Nacht-Agenten 2026-09-27 00:51:32 +02:00
data Stand vor Einführung des Nacht-Agenten 2026-09-27 00:51:32 +02:00
docs Betriebsalarme mit Entwarnung: Lizenzserver, Warteschlange, Worker-Ausfall (#20, #38) 2026-10-06 11:35:02 +02:00
migrations Abrechnungslauf: Entwürfe je Vertragsperiode, genau einmal (#50) 2026-10-06 12:04:01 +02:00
ops Browser-Abnahme mit Playwright und axe (#39, #15) 2026-10-06 11:57:20 +02:00
packages Abrechnungslauf: Entwürfe je Vertragsperiode, genau einmal (#50) 2026-10-06 12:04:01 +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 Version 0.0.1 (Vorabversion) 2026-10-02 13:46:01 +02:00
pnpm-lock.yaml Browser-Abnahme mit Playwright und axe (#39, #15) 2026-10-06 11:57:20 +02:00
pnpm-workspace.yaml Stand vor Einführung des Nacht-Agenten 2026-09-27 00:51:32 +02:00
README.md Browser-Abnahme mit Playwright und axe (#39, #15) 2026-10-06 11:57:20 +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).

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.