diff --git a/docs/adr/0003-job-queue-in-mariadb.md b/docs/adr/0003-job-queue-in-mariadb.md new file mode 100644 index 0000000..db49679 --- /dev/null +++ b/docs/adr/0003-job-queue-in-mariadb.md @@ -0,0 +1,14 @@ +# ADR 0003: Job-Queue in MariaDB +Status: angenommen (beschreibt den umgesetzten Stand, 06.10.2026) + +**Kontext:** API und Worker sind getrennte Prozesse. Asynchrone Arbeit (Provider-Aktionen, Mails, Discord, Abgleich) muss einen Neustart überstehen, darf nicht doppelt ausgeführt werden und muss nachvollziehbar sein. Eine zusätzliche Infrastruktur (Redis/RabbitMQ) soll vermieden werden. + +**Entscheidung:** Tabelle `jobs` in MariaDB. +- **Einplanen:** `enqueue(type, payload, { idempotencyKey, correlationId, runAt }, connection?)` – `INSERT IGNORE` auf den Idempotenzschlüssel; mit `connection` in derselben Transaktion wie die fachliche Änderung (kein Auftrag ohne Datensatz und umgekehrt). +- **Abholen:** `SELECT … FOR UPDATE SKIP LOCKED` (ältester fälliger Job), dann `status='running'` mit zufälliger `lease_id`. Mehrere Worker sind möglich. +- **Herzschlag/Lease:** während der Ausführung alle 60 s `locked_at` aktualisieren. Ergebnis wird nur geschrieben, wenn die `lease_id` noch passt – ein inzwischen übernommener Job wird nicht überschrieben. +- **Wiederanlauf:** `recoverStale` gibt Jobs ohne Herzschlag (> 5 min) wieder frei; **destruktive** Aufträge (`payload.destructive` bzw. `terminate`) gehen stattdessen auf `needs_review`, weil ihr Ergebnis beim Anbieter geprüft werden muss. +- **Fehler:** Wiederholung mit Backoff bis `max_attempts`; `JobFailure(retry=false)` beendet sofort mit `failed` oder `needs_review`. +- **Überwachung:** Stau (fällige Jobs > 10 min) und `needs_review` lösen Betriebsalarme aus (`platform/monitor.ts`, siehe `docs/betrieb-backup-restore.md`). + +**Folgen:** Kein zusätzlicher Dienst; Transaktionen über Job und Fachdaten möglich. Durchsatz ist für die erwartete Last (Dutzende Jobs pro Minute) ausreichend; bei deutlich mehr Last wäre eine eigene Queue zu prüfen. diff --git a/docs/architektur.md b/docs/architektur.md new file mode 100644 index 0000000..26f0903 --- /dev/null +++ b/docs/architektur.md @@ -0,0 +1,82 @@ +# Architektur + +Stand: 06.10.2026 (Code-Stand nach den Plane-Tickets #95–#119). Entscheidungen im Detail: `docs/adr/`. + +## Überblick + +Modularer Monolith in einem pnpm-Monorepo mit drei Prozessen und einer Datenbank: + +| Prozess | Paket | Aufgabe | systemd | +|---|---|---|---| +| API | `apps/api` (Fastify) | HTTP-API unter `/v1`, Rechte, Validierung, Audit, Jobs einplanen, Worker-Watchdog | `kc-api` (:4100, nur 127.0.0.1) | +| Worker | `apps/worker` | Job-Queue abarbeiten, Connector-Abgleich, Vertragslauf, Abrechnungslauf, IMAP-Abruf, Discord-Bot, Lizenzprüfung, Betriebsalarme | `kc-worker` | +| Web | `apps/web` (Next.js) | Oberfläche; spricht ausschließlich über den Proxy `/api/*` → API | `kc-web` (:4101, nur 127.0.0.1) | + +Datenbank: MariaDB (`utf8mb4_unicode_ci`), Schema über nummerierte Migrationen in `migrations/` (`pnpm migrate`, Sperre + Wiederanlauf siehe `docs/betrieb-backup-restore.md`). Kein Redis, keine Message-Queue – die Job-Queue liegt in MariaDB (ADR 0003). + +## Pakete und erlaubte Abhängigkeiten + +``` +apps/web ──HTTP──▶ apps/api ─┐ + ├─▶ packages/connectors ─▶ packages/connector-{keyhelp,plesk,licensing,mock} ─▶ packages/connector-sdk + apps/worker ─────┤ │ + └─▶ packages/platform ◀──┘ +``` + +| Paket | Darf importieren | Inhalt | +|---|---|---| +| `packages/connector-sdk` | nichts Internes | Connector-Vertrag (`Connector`, Capabilities, `NormalizedResource`, Fehlerklassen, `httpJson`) | +| `packages/connector-*` | nur `@kc/connector-sdk` | Anbieter-Anbindungen; kennen weder Datenbank noch Apps | +| `packages/platform` | keine `@kc`-Pakete | gemeinsame Schicht für API und Worker: DB, Konfiguration, Krypto, Audit-Kette, Jobs, Mail, Lizenz/Edition, Preise, Statusautomaten, Abrechnungslauf, Betriebsalarme, Ticket-Policy, CSV, Nummernkreise | +| `packages/connectors` | `platform`, `connector-sdk`, `connector-*` | Registry der Connectoren, Abgleich, Provisionierung, Lifecycle-Aktionen, Vertragslauf | +| `apps/api` | `platform`, `connectors`, `connector-sdk` | Module (s. u.), `core/` (Auth, Policy, Fehler, Re-Exporte der Plattform), `ops/` (Backup, Watchdog) | +| `apps/worker` | `platform`, `connectors`, `connector-sdk` | Job-Handler, Discord, IMAP; **kein** Import von API-Code | +| `apps/web` | keine `@kc`-Pakete, nichts außerhalb `apps/web` | UI; Rechte kommen aus `/auth/me`, durchgesetzt wird nur in der API | + +Innerhalb der API importieren Module einander **nicht**; sie kommunizieren über `core/`, `packages/platform` und Jobs. + +**Automatische Prüfung:** `node ops/test/check-boundaries.mjs` (läuft in `ops/test/ci.sh` und damit in der CI; `--selftest` prüft die Regeln selbst). Ein verbotener Import – z. B. `apps/api/src/modules/tickets/*` → `../invoices/index.js` oder `packages/connector-plesk` → `@kc/platform` – lässt den Lauf scheitern. Tests (`test/`, `*.test.ts`) sind ausgenommen (API-Tests treiben den Worker-Job-Runner direkt an). + +## API-Module + +Jedes Modul ist ein `KcModule` (`apps/api/src/core/module.ts`): Name, zusätzliche Rechte je Personal-/Organisationsrolle, `register(app)` mit den Routen. Eingetragen in `apps/api/src/modules/index.ts`. + +| Modul | Zuständigkeit | +|---|---| +| system | `/health`, `/ready`, Betriebsübersicht (`/admin/system`: Jobs, Backup, Worker-Herzschlag, Betriebsalarme) | +| identity | Login, 2FA (TOTP, Wiederherstellungscodes), Sitzungen, Einladungen, Passwort-Reset, Personalverwaltung, Impersonation | +| customers | Kunden/Organisationen, Rechnungsprofil, Mitglieder, Übernahme aus Anbietern, Kundengrenze | +| audit | Audit-Protokoll (Hash-Kette), Export | +| connectors | Verbindungen (verschlüsselte Zugangsdaten), Capabilities, Abgleich | +| resources | Hosting-Konten/Lizenzen/Unterobjekte, Aktionen, Panel-Login, Auftragsliste | +| catalog | Produkte, Versionen, Laufzeitpreise | +| domains | Domain-Aufstellung, EK/VK, CSV, Verfügbarkeit | +| orders | Bestellungen, Freigabe, Verträge, Kündigung | +| tickets | Tickets, Nachrichten, Anhänge, **Posteingang** (IMAP-Mails, Zuordnung) | +| invoices | Rechnungen (Entwurf/Ausstellen/Storno), PDF, DATEV/CSV, Firmenstammdaten, Mahnüberblick, **Abrechnungslauf** | +| backup | Backup-Ziele, Passwort, Status | +| mail | SMTP, Vorlagen, Protokoll, **IMAP-Einstellungen** | +| discord | Bot-Einstellungen, OAuth-Verknüpfung | +| license | eigene Lizenz der Installation (Edition, Testmodus) | +| licensing | Lizenzverwaltung für weiterverkaufte Lizenzen (Licensing-Connector) | + +### Mail-Plattform (#106/#107) + +Versand: `packages/platform/src/mail.ts` (SMTP-Konfiguration aus `mail`-Modul, DB-Vorlagen, Absender je Bereich, Protokoll). Ticket-Mails tragen eine signierte Message-ID (`platform/ticketmail.ts`). Empfang: der Worker ruft IMAP ab (`apps/worker/src/mailbox.ts`) und schreibt in `inbox_messages`/Tickets; die Bedienung (Zuordnen/Anhängen/Ignorieren) liegt im Tickets-Modul. Zuordnung nur mit signiertem Antwort-Bezug, sonst Posteingang. + +## Kommunikation über Jobs + +API und Worker teilen sich keine Prozessdaten. Alles Asynchrone läuft über die Tabelle `jobs` (`platform/jobs.ts: enqueue`, in derselben Transaktion wie die fachliche Änderung möglich, Idempotenzschlüssel). Beispiele: `discord.notify`, `mail.template`, Connector-Aktionen, `discord.ticket_sync`. Details ADR 0003. + +## Querschnitt + +- **Rechte:** `core/policy.ts` (RBAC + Objektprüfung `canInOrg`); Module registrieren ihre Rechte. Ticket-Rechte zusätzlich in `platform/ticketPolicy.ts`, damit der Worker (Discord) dieselben Regeln nutzt. Rollenmatrix: `docs/sicherheit-und-bedrohungsmodell.md`. +- **Audit:** unveränderliche Hash-Kette (`platform/audit.ts`, Trigger verhindern UPDATE/DELETE). +- **Geheimnisse:** AES-GCM mit `KC_SECRET_KEY` (`platform/crypto.ts`); Konfiguration in `/etc/kundencenter/*.env`, nie im Repo. +- **Edition/Lizenz:** `platform/license.ts` (signierte Antworten, Grenzen transaktional). +- **Zeit:** alles in UTC (DB-Sitzung `time_zone = '+00:00'`). + +## Bekannte Abweichungen / offene Punkte + +- Die Modulmatrix der eigenen Lizenz (billing/domains/provisioning/automation) ist noch nicht entschieden (#113); bis dahin gelten discord/imap/datev/backup_remote. +- Der frühere doppelte Config-Lader (ADR 0002) ist aufgelöst: `apps/api/src/core/config.ts` re-exportiert `@kc/platform/config`. diff --git a/ops/test/check-boundaries.mjs b/ops/test/check-boundaries.mjs new file mode 100644 index 0000000..c88b8f2 --- /dev/null +++ b/ops/test/check-boundaries.mjs @@ -0,0 +1,74 @@ +#!/usr/bin/env node +// Modulgrenzen des modularen Monolithen (#7, docs/architektur.md) – prüft alle Importe im Quellcode (ohne Tests). +// Aufruf: node ops/test/check-boundaries.mjs (Selbsttest: --selftest). Exit 1 bei Verstoß. +import { readdirSync, readFileSync, statSync } from 'node:fs'; +import { join, relative, resolve, dirname, sep } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); +const CONNECTORS = ['connector-keyhelp', 'connector-licensing', 'connector-mock', 'connector-plesk']; + +/** Liefert eine Fehlermeldung, wenn `from` (Datei, relativ zum Repo) `spec` nicht importieren darf. */ +export function violation(from, spec, target /* aufgelöster relativer Pfad oder null */) { + const kc = spec.startsWith('@kc/') ? spec.split('/')[1] : null; + const inDir = (d) => from.startsWith(d + '/'); + if (inDir('packages/connector-sdk')) { if (kc) return 'connector-sdk ist die Basis und importiert keine @kc-Pakete'; } + for (const c of CONNECTORS) if (inDir(`packages/${c}`)) { if (kc && kc !== 'connector-sdk') return `${c} darf nur @kc/connector-sdk nutzen (Connectoren kennen Plattform und Apps nicht)`; } + if (inDir('packages/platform')) { if (kc) return 'platform ist die unterste Schicht und importiert keine @kc-Pakete'; } + if (inDir('packages/connectors')) { if (kc && !['platform', 'connector-sdk', ...CONNECTORS].includes(kc)) return `connectors darf ${spec} nicht importieren`; } + if (inDir('apps/web')) { if (kc) return 'Web spricht nur über die HTTP-API (/api), keine @kc-Pakete'; if (target && !target.startsWith('apps/web/')) return 'Web darf keine Dateien außerhalb von apps/web importieren'; } + if (inDir('apps/worker')) { if (kc && !['platform', 'connectors', 'connector-sdk'].includes(kc)) return `worker darf ${spec} nicht importieren`; if (target && !target.startsWith('apps/worker/')) return 'worker darf keinen API-/Web-Code importieren (gemeinsames gehört nach packages/platform)'; } + if (inDir('apps/api')) { + if (kc && !['platform', 'connectors', 'connector-sdk'].includes(kc)) return `api darf ${spec} nicht importieren`; + if (target && !target.startsWith('apps/api/')) return 'api darf keinen Worker-/Web-Code importieren'; + const m = /^apps\/api\/src\/modules\/([^/]+)\//.exec(from); const t = target && /^apps\/api\/src\/modules\/([^/]+)\//.exec(target); + if (m && t && m[1] !== t[1]) return `Modul ${m[1]} importiert Interna von Modul ${t[1]} – Kommunikation über core/, platform oder Jobs/Ereignisse`; + } + return null; +} + +function* files(dir) { + for (const n of readdirSync(dir)) { + if (['node_modules', 'dist', '.next', 'test', 'tests', 'test-results'].includes(n)) continue; + const p = join(dir, n); const s = statSync(p); + if (s.isDirectory()) yield* files(p); else if (/\.(ts|tsx|mjs|js)$/.test(n) && !/\.(test|spec)\./.test(n) && !n.endsWith('.d.ts')) yield p; + } +} +const IMPORT = /(?:import|export)\s[^'"]*?from\s*['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)/g; + +export function scan() { + const out = []; + for (const base of ['packages', 'apps']) for (const pkg of readdirSync(join(ROOT, base))) { + const src = join(ROOT, base, pkg, 'src'); try { statSync(src); } catch { continue; } + for (const f of files(src)) { + const rel = relative(ROOT, f).split(sep).join('/'); const text = readFileSync(f, 'utf8'); + for (const m of text.matchAll(IMPORT)) { + const spec = m[1] ?? m[2]; + const target = spec.startsWith('.') ? relative(ROOT, resolve(dirname(f), spec)).split(sep).join('/') : null; + const v = violation(rel, spec, target); + if (v) out.push(`${rel}: '${spec}' – ${v}`); + } + } + } + return out; +} + +if (process.argv.includes('--selftest')) { + const cases = [ + ['packages/connector-plesk/src/index.ts', '@kc/platform/db', null, true], + ['packages/connector-plesk/src/index.ts', '@kc/connector-sdk', null, false], + ['packages/platform/src/db.ts', '@kc/connectors', null, true], + ['apps/web/src/app/x.tsx', '@kc/platform/db', null, true], + ['apps/web/src/app/x.tsx', '../../../api/src/x', 'apps/api/src/x', true], + ['apps/worker/src/x.ts', '../../api/src/core/db.js', 'apps/api/src/core/db.js', true], + ['apps/api/src/modules/tickets/index.ts', '../invoices/index.js', 'apps/api/src/modules/invoices/index.js', true], + ['apps/api/src/modules/tickets/index.ts', './files.js', 'apps/api/src/modules/tickets/files.js', false], + ['apps/api/src/modules/tickets/index.ts', '../../core/db.js', 'apps/api/src/core/db.js', false], + ]; + const bad = cases.filter(([f, s, t, exp]) => !!violation(f, s, t) !== exp); + if (bad.length) { console.error('Selbsttest fehlgeschlagen:', bad); process.exit(1); } + console.log(`Selbsttest Modulgrenzen: ${cases.length} Fälle ok`); +} +const v = scan(); +if (v.length) { console.error(`Modulgrenzen verletzt (${v.length}):\n` + v.join('\n')); process.exit(1); } +console.log('Modulgrenzen: keine Verstöße'); diff --git a/ops/test/ci.sh b/ops/test/ci.sh index e96474c..1d4f358 100755 --- a/ops/test/ci.sh +++ b/ops/test/ci.sh @@ -2,6 +2,7 @@ # Kompletter Prüflauf wie in der CI: Installation aus dem Lockfile, Build (vor Tests – Pakete werden über dist/ # aufgelöst), dann alle Testsuiten. Bricht beim ersten Fehler ab. set -euo pipefail +node ops/test/check-boundaries.mjs --selftest pnpm install --frozen-lockfile pnpm build pnpm --filter @kc/platform test