Architektur-Doku, ADR Job-Queue und automatische Modulgrenzen-Prüfung (#7)
- docs/architektur.md: Prozesse, Pakete und erlaubte Abhängigkeiten, API-Module, Mail-Plattform/IMAP, Jobs, Querschnitt, offene Punkte. - docs/adr/0003-job-queue-in-mariadb.md. - ops/test/check-boundaries.mjs (ohne neue Abhängigkeit): prüft alle Importe gegen die Schichtregeln, inkl. Selbsttest; läuft in ci.sh. Gegenprobe: verbotener Modul-Querimport lässt den Lauf scheitern. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
9f9c5c4b65
commit
a0dd7c3940
4 changed files with 171 additions and 0 deletions
14
docs/adr/0003-job-queue-in-mariadb.md
Normal file
14
docs/adr/0003-job-queue-in-mariadb.md
Normal file
|
|
@ -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.
|
||||
82
docs/architektur.md
Normal file
82
docs/architektur.md
Normal file
|
|
@ -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`.
|
||||
74
ops/test/check-boundaries.mjs
Normal file
74
ops/test/check-boundaries.mjs
Normal file
|
|
@ -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');
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue