diff --git a/apps/api/src/modules/system/index.ts b/apps/api/src/modules/system/index.ts index 9336775..ae3ba70 100644 --- a/apps/api/src/modules/system/index.ts +++ b/apps/api/src/modules/system/index.ts @@ -4,6 +4,7 @@ import { requirePermission } from '../../core/auth.js'; import { query } from '../../core/db.js'; import { readFile } from 'node:fs/promises'; import type { KcModule } from '../../core/module.js'; +import { activeAlerts, ALERT_LABEL, heartbeatAgeMs } from '@kc/platform/monitor'; /** Backup-Zustand aus der Statusdatei des Backup-Laufs (siehe docs/betrieb-backup-restore.md). Ohne Datei: nicht eingerichtet. */ async function backupState() { @@ -29,7 +30,10 @@ export const systemModule: KcModule = { requirePermission(req, 'jobs.read'); const jobs = await query('SELECT status, COUNT(*) AS n FROM jobs GROUP BY status'); const oldest = await one('SELECT MIN(run_at) AS t FROM jobs WHERE status IN (\'scheduled\',\'retrying\')'); - return { jobs: Object.fromEntries(jobs.map((j) => [j.status, Number(j.n)])), oldestPendingJob: oldest?.t ?? null, serverTime: new Date().toISOString(), backup: await backupState() }; + const workerAge = await heartbeatAgeMs('worker'); + const alerts = (await activeAlerts()).map((a) => ({ ...a, label: ALERT_LABEL[a.key] ?? a.key })); + return { jobs: Object.fromEntries(jobs.map((j) => [j.status, Number(j.n)])), oldestPendingJob: oldest?.t ?? null, serverTime: new Date().toISOString(), backup: await backupState(), + worker: { lastHeartbeatSecondsAgo: workerAge === null ? null : Math.round(workerAge / 1000) }, alerts }; }); }, }; diff --git a/apps/api/src/ops/watchdog.ts b/apps/api/src/ops/watchdog.ts new file mode 100644 index 0000000..c425381 --- /dev/null +++ b/apps/api/src/ops/watchdog.ts @@ -0,0 +1,27 @@ +import { query } from '../core/db.js'; +import { sendMail } from '@kc/platform/mail'; +import { alertText, applyConditions, heartbeatAgeMs, type Condition } from '@kc/platform/monitor'; + +/** Ab dieser Herzschlag-Lücke gilt der Worker als ausgefallen (er schreibt jede Minute). */ +const STALE_MS = 3 * 60_000; + +/** Zustand „Worker arbeitet nicht“ aus dem Herzschlag. Noch nie geschrieben (frische Installation/alter Worker): kein Alarm. */ +export async function workerDownCondition(): Promise { + const age = await heartbeatAgeMs('worker'); + const down = age !== null && age > STALE_MS; + return { key: 'worker.down', active: down, detail: down ? `letzter Herzschlag vor ${Math.round(age! / 60_000)} Minuten` : null, graceMs: 2 * 60_000 }; +} + +/** + * Den Ausfall des Workers kann der Worker nicht selbst melden – und Discord läuft im Worker. Die API prüft deshalb + * minütlich den Herzschlag und schreibt bei Ausfall/Entwarnung direkt per SMTP an alle aktiven Superadmins (#20/#38). + */ +export function startWorkerWatchdog(): void { + const notify = async (key: string, kind: 'alarm' | 'recovery', detail: string | null) => { + const text = alertText(key, kind, detail); + const admins = await query("SELECT email FROM users WHERE kind = 'staff' AND staff_role = 'superadmin' AND status = 'active'"); + for (const a of admins) await sendMail(a.email, 'system_alert', `Kundencenter: ${text}`, `${text}\n\nPrüfen: systemctl status kc-worker; journalctl -u kc-worker -n 100`); + }; + const tick = () => workerDownCondition().then((c) => applyConditions([c], notify)).catch(() => undefined); + setInterval(tick, 60_000).unref(); +} diff --git a/apps/api/src/server.ts b/apps/api/src/server.ts index 1bd7274..300d721 100644 --- a/apps/api/src/server.ts +++ b/apps/api/src/server.ts @@ -9,6 +9,7 @@ import { registerPermissions } from './core/policy.js'; import { AppError } from './core/errors.js'; import { InvalidTransition } from '@kc/platform/statemachine'; import { modules } from './modules/index.js'; +import { startWorkerWatchdog } from './ops/watchdog.js'; export async function buildApp() { const app = Fastify({ @@ -40,4 +41,5 @@ export async function buildApp() { if (import.meta.url === `file://${process.argv[1]}`) { const app = await buildApp(); await app.listen({ port: config.port, host: '127.0.0.1' }); + startWorkerWatchdog(); } diff --git a/apps/api/test/monitor.test.ts b/apps/api/test/monitor.test.ts new file mode 100644 index 0000000..2c1a674 --- /dev/null +++ b/apps/api/test/monitor.test.ts @@ -0,0 +1,48 @@ +import { describe, expect, it } from 'vitest'; +import { run } from '../src/core/db.js'; +import { applyConditions, heartbeat, workerConditions } from '@kc/platform/monitor'; +import { workerDownCondition } from '../src/ops/watchdog.js'; + +describe('Betriebsalarme mit Entwarnung (#20/#38)', () => { + it('meldet erst nach der Karenzzeit, genau einmal, und entwarnt danach einmal', async () => { + const sent: string[] = []; const notify = async (k: string, kind: string) => { sent.push(`${k}:${kind}`); }; + const t0 = new Date('2026-10-06T10:00:00Z'); const at = (min: number) => new Date(t0.getTime() + min * 60_000); + const c = (active: boolean) => [{ key: 'test.queue', active, detail: active ? 'Stau' : null, graceMs: 5 * 60_000 }]; + await applyConditions(c(true), notify, at(0)); await applyConditions(c(true), notify, at(3)); + expect(sent).toEqual([]); // kurzer Aussetzer: noch nichts + await applyConditions(c(true), notify, at(6)); await applyConditions(c(true), notify, at(7)); + expect(sent).toEqual(['test.queue:alarm']); // dedupliziert + await applyConditions(c(false), notify, at(8)); await applyConditions(c(false), notify, at(9)); + expect(sent).toEqual(['test.queue:alarm', 'test.queue:recovery']); + }); + it('kurzer Vorfall unterhalb der Karenz: weder Alarm noch Entwarnung', async () => { + const sent: string[] = []; const notify = async (k: string, kind: string) => { sent.push(`${k}:${kind}`); }; + const t = new Date('2026-10-06T11:00:00Z'); + await applyConditions([{ key: 'test.blip', active: true, graceMs: 60_000 }], notify, t); + await applyConditions([{ key: 'test.blip', active: false }], notify, new Date(t.getTime() + 30_000)); + expect(sent).toEqual([]); + }); + it('unterscheidet Lizenzserver-Ausfall von Konfigurationsproblemen; ohne Schlüssel (Testmodus) kein Alarm', async () => { + await run("UPDATE license_state SET license_key_enc = 'x', last_error = 'Netzwerkfehler: timeout', last_error_kind = 'outage', valid = 1, checked_at = UTC_TIMESTAMP(3) WHERE id = 1"); + let c = Object.fromEntries((await workerConditions()).map((x) => [x.key, x.active])); + expect(c['license.unreachable']).toBe(true); expect(c['license.problem']).toBe(false); + await run("UPDATE license_state SET last_error = 'Program-Key ungültig', last_error_kind = 'config' WHERE id = 1"); + c = Object.fromEntries((await workerConditions()).map((x) => [x.key, x.active])); + expect(c['license.unreachable']).toBe(false); expect(c['license.problem']).toBe(true); + await run('UPDATE license_state SET license_key_enc = NULL WHERE id = 1'); + c = Object.fromEntries((await workerConditions()).map((x) => [x.key, x.active])); + expect(c['license.unreachable']).toBe(false); expect(c['license.problem']).toBe(false); + await run('UPDATE license_state SET last_error = NULL, last_error_kind = NULL WHERE id = 1'); + }); + it('Warteschlangen-Stau und Aufträge zur Prüfung werden erkannt', async () => { + await run("INSERT INTO jobs (id, type, payload, status, run_at) VALUES (UUID(), 'x.test', '{}', 'scheduled', DATE_SUB(UTC_TIMESTAMP(3), INTERVAL 30 MINUTE)), (UUID(), 'x.test', '{}', 'needs_review', UTC_TIMESTAMP(3))"); + const c = Object.fromEntries((await workerConditions()).map((x) => [x.key, x.active])); + expect(c['jobs.backlog']).toBe(true); expect(c['jobs.needs_review']).toBe(true); + await run("DELETE FROM jobs WHERE type = 'x.test'"); + }); + it('Worker-Herzschlag: frisch = in Ordnung, veraltet = ausgefallen', async () => { + await heartbeat('worker'); expect((await workerDownCondition()).active).toBe(false); + await run("UPDATE system_heartbeats SET at = DATE_SUB(UTC_TIMESTAMP(3), INTERVAL 10 MINUTE) WHERE name = 'worker'"); + expect((await workerDownCondition()).active).toBe(true); + }); +}); diff --git a/apps/web/src/app/(app)/dashboard/page.tsx b/apps/web/src/app/(app)/dashboard/page.tsx index e7f584d..0c8397c 100644 --- a/apps/web/src/app/(app)/dashboard/page.tsx +++ b/apps/web/src/app/(app)/dashboard/page.tsx @@ -5,7 +5,7 @@ import { api, errMsg } from '@/lib/api'; import { useSession } from '@/lib/session'; import { Alert, Empty, InvoiceStatusBadge, TicketStatusBadge, eur, fmt, fmtDay } from '@/components/ui'; -interface Sys { jobs: Record; oldestPendingJob: string | null; backup?: { configured: boolean; lastRunAt?: string | null; ok?: boolean; ageHours?: number | null; stale?: boolean; error?: string | null; sizeBytes?: number | null; targets?: { name: string; ok: boolean }[]; lastRestoreTestAt?: string | null; restoreOk?: boolean | null; restoreStale?: boolean } } +interface Sys { jobs: Record; oldestPendingJob: string | null; alerts?: { key: string; label: string; since: string; detail: string | null }[]; worker?: { lastHeartbeatSecondsAgo: number | null }; backup?: { configured: boolean; lastRunAt?: string | null; ok?: boolean; ageHours?: number | null; stale?: boolean; error?: string | null; sizeBytes?: number | null; targets?: { name: string; ok: boolean }[]; lastRestoreTestAt?: string | null; restoreOk?: boolean | null; restoreStale?: boolean } } interface RecentTicket { id: string; number: string; orgName: string; subject: string; status: string; lastMessageAt: string } interface OpenInvoice { id: string; number: string | null; orgName: string; status: string; overdue: boolean; dueDate: string | null; totalGrossCents: number } @@ -64,6 +64,8 @@ export default function Dashboard() { {customers !== null &&
{customers}

Kunden

Kunden verwalten
} {licenses &&
{licenses.active}

Aktive Lizenzen

{licenses.expiring > 0 &&

{licenses.expiring} laufen in 30 Tagen ab

}{licenses.unassigned > 0 &&

{licenses.unassigned} ohne Kunde

}Lizenzen verwalten
} {sys &&
{sys.jobs.scheduled ?? 0}

Wartende Aufträge

} + {sys?.alerts && sys.alerts.length > 0 &&

Betriebsalarme

+
    {sys.alerts.map((a) =>
  • {a.label}{a.detail ? ` – ${a.detail}` : ''} (seit {new Date(a.since).toLocaleString('de-DE', { dateStyle: 'short', timeStyle: 'short' })})
  • )}
} {sys?.backup &&

Backup

Details und Einstellungen

{!sys.backup.configured ? <>

Nicht eingerichtet.

Kein Backup : <>

{sys.backup.stale ? {sys.backup.ok ? 'Veraltet' : 'Fehlgeschlagen'} : Aktuell}

diff --git a/apps/worker/src/index.ts b/apps/worker/src/index.ts index b74eba8..9c397b1 100644 --- a/apps/worker/src/index.ts +++ b/apps/worker/src/index.ts @@ -49,11 +49,30 @@ setInterval(() => void checkBackup(), 3600_000); // Fehlschlag, solange kein Programm-Key/Lizenzschlüssel hinterlegt ist (siehe LicenseCheckError) - dann // einfach weiter versuchen, keine Alarmierung (Betreiber hat die Lizenzierung schlicht noch nicht eingerichtet). import { checkLicenseNow, LicenseCheckError } from '@kc/platform/license'; +// Ausfall des Lizenzservers (outage) wird alle 10 Minuten erneut versucht und nach 30 Minuten gemeldet (siehe +// Betriebsalarme unten); Konfigurationsfehler/Ablehnungen werden ebenfalls gemeldet, aber nicht im Takt wiederholt. +let licenseOutage = false; const checkLicense = async () => { - try { await checkLicenseNow(); } - catch (e) { if (!(e instanceof LicenseCheckError)) log(`Lizenzprüfung fehlgeschlagen: ${(e as Error).message}`); } + try { await checkLicenseNow(); licenseOutage = false; } + catch (e) { + licenseOutage = e instanceof LicenseCheckError && e.kind === 'outage'; + const quiet = e instanceof LicenseCheckError && e.kind === 'config'; // z. B. noch kein Schlüssel hinterlegt (Testmodus) + if (!quiet) log(`Lizenzprüfung fehlgeschlagen: ${(e as Error).message}`); + } }; setInterval(() => void checkLicense(), 12 * 3600_000); void checkLicense(); +setInterval(() => { if (licenseOutage) void checkLicense(); }, 10 * 60_000); + +// Betriebsalarme mit Entwarnung (#20/#38): Lizenzserver, Warteschlangen-Stau, Aufträge zur Prüfung → Discord-Meldung. +// Der Zustand ist zusätzlich im Dashboard sichtbar. Den Ausfall dieses Workers selbst meldet die API (Herzschlag). +import { applyConditions, heartbeat, workerConditions } from '@kc/platform/monitor'; +const monitor = async () => { + try { + await heartbeat('worker'); + await applyConditions(await workerConditions(), (key, kind, detail) => enqueue('discord.notify', { event: 'system.alert', key, kind, detail }, { idempotencyKey: `system.alert:${key}:${kind}:${Date.now()}` })); + } catch (e) { log(`Betriebsalarme: Prüfung fehlgeschlagen: ${(e as Error).message}`); } +}; +setInterval(() => void monitor(), 60_000); void monitor(); // Vertrags-Erinnerung: ~30 Tage vor Laufzeitende Mail mit "Behalten"/"Kündigen"-Link (einmal je Vertrag, // markiert über renewal_reminder_sent_at). Unabhängig von processContractLifecycle oben, die nur zum diff --git a/apps/worker/src/jobs.ts b/apps/worker/src/jobs.ts index 505a518..955a5f5 100644 --- a/apps/worker/src/jobs.ts +++ b/apps/worker/src/jobs.ts @@ -4,6 +4,7 @@ import { pool } from '@kc/platform/db'; import { notifyAdmin, postTicketMessage } from './discord.js'; import { JobFailure } from '@kc/platform/jobs'; import { sendTemplateMail } from '@kc/platform/mail'; +import { alertText } from '@kc/platform/monitor'; import { executeAction, executeChild, provisionOrder, syncInstance, type ChildPayload, type ExecutePayload } from '@kc/connectors'; // Kennung dieses Worker-Prozesses (nur zur Diagnose in locked_by, kein Sicherheitsmerkmal). @@ -21,6 +22,7 @@ const handlers: Record = { : p.event === 'restoretest.failed' ? `⚠ Wiederherstellungstest fehlgeschlagen: ${p.detail ?? ''}`.trim() : p.event === 'ticket.created' ? `🎫 Neues Ticket ${p.number}: ${p.subject ?? ''}`.trim() : p.event === 'ticket.message' ? `🎫 Neue Nachricht zu Ticket ${p.number}` + : p.event === 'system.alert' ? alertText(String(p.key), p.kind === 'recovery' ? 'recovery' : 'alarm', p.detail ?? null) : p.event === 'invoice.issued' ? `🧾 Rechnung ${p.number} ausgestellt (${(Number(p.gross ?? 0) / 100).toLocaleString('de-DE', { style: 'currency', currency: 'EUR' })})` : null; // keine personenbezogenen Daten if (!text) throw new Error(`Unbekanntes Ereignis: ${p.event}`); const r = await notifyAdmin(text, String(p.event).startsWith('ticket.') ? 'tickets' : 'admin'); diff --git a/docs/betrieb-backup-restore.md b/docs/betrieb-backup-restore.md index 4ffb436..715ecc2 100644 --- a/docs/betrieb-backup-restore.md +++ b/docs/betrieb-backup-restore.md @@ -83,3 +83,16 @@ DDL ist in MariaDB nicht transaktional. Bricht eine Migration mitten drin ab, st 1. Fehlermeldung lesen, Datenbankzustand prüfen (`SELECT * FROM schema_migrations_dirty`), Ursache beheben (z. B. Datenkonflikt bereinigen). Die Migrationsdatei dabei **nicht** ändern – sonst ist Fortsetzen nicht mehr sicher und wird abgelehnt. 2. `pnpm migrate --resume` setzt bei der fehlgeschlagenen Anweisung fort; die bereits angewendeten werden nicht wiederholt. 3. Lässt sich der Zustand nicht sauber herstellen: Sicherung von vor dem Deploy in eine Wegwerf-Datenbank prüfen und einspielen (siehe oben). + +## Betriebsalarme und Entwarnung +Zustände werden minütlich geprüft und in `system_alerts` geführt; aktive Alarme stehen im Dashboard (Karte „Betriebsalarme“), auch wenn Discord/Mail nicht eingerichtet sind. Gemeldet wird je Vorfall einmal nach der Karenzzeit, die Entwarnung folgt, sobald der Zustand behoben ist. + +| Zustand | Prüft | Karenz | Meldung | +|---|---|---|---| +| Lizenzserver nicht erreichbar (Netzwerk, HTTP 5xx/429) | Worker, Wiederholung alle 10 min | 30 min | Discord (Ticket-/Admin-Kanal) | +| Problem mit der eigenen Lizenz (Program-Key falsch, Antwort abgelehnt, Lizenz ungültig/abgelaufen) | Worker | sofort | Discord | +| Warteschlange staut sich (fällige Aufträge > 10 min unbearbeitet) | Worker | 5 min | Discord | +| Aufträge warten auf Prüfung (`needs_review`) | Worker | sofort | Discord | +| kc-worker arbeitet nicht (Herzschlag > 3 min alt) | API | 2 min | Mail an alle aktiven Superadmins (Discord läuft im Worker) | + +Ohne hinterlegten Lizenzschlüssel (Testmodus) gibt es keine Lizenzalarme. diff --git a/migrations/040_system_alerts.sql b/migrations/040_system_alerts.sql new file mode 100644 index 0000000..ed93882 --- /dev/null +++ b/migrations/040_system_alerts.sql @@ -0,0 +1,16 @@ +-- Betriebsalarme mit Entwarnung (#20/#38): je Zustand eine Zeile, Meldung erst nach einer Karenzzeit, Entwarnung nur, +-- wenn vorher gemeldet wurde. Herzschlag der Dienste, damit ein ausgefallener Worker erkannt wird. +CREATE TABLE system_alerts ( + alert_key VARCHAR(100) PRIMARY KEY, + active TINYINT(1) NOT NULL DEFAULT 0, + since DATETIME(3) NULL, + detail VARCHAR(500) NULL, + notified_at DATETIME(3) NULL, + resolved_at DATETIME(3) NULL, + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) +); +CREATE TABLE system_heartbeats ( + name VARCHAR(50) PRIMARY KEY, + at DATETIME(3) NOT NULL +); +ALTER TABLE license_state ADD COLUMN last_error_kind ENUM('config','outage','rejected') NULL AFTER last_error; diff --git a/packages/platform/src/license.ts b/packages/platform/src/license.ts index 1896c19..c5e17e9 100644 --- a/packages/platform/src/license.ts +++ b/packages/platform/src/license.ts @@ -55,7 +55,11 @@ async function refreshSigningKeys(): Promise { for (const k of data.keys) await run('INSERT INTO license_signing_keys (kid, alg, n_hex, e_hex, status) VALUES (?,?,?,?,?) ON DUPLICATE KEY UPDATE alg=VALUES(alg), n_hex=VALUES(n_hex), e_hex=VALUES(e_hex), status=VALUES(status)', [k.kid, k.alg, k.n, k.e, k.status]); } -export class LicenseCheckError extends Error {} +/** kind: config = Einrichtung fehlt/falsch (kein Ausfall), outage = Lizenzserver nicht erreichbar/Serverfehler, + * rejected = Antwort abgelehnt (Signatur, Replay, fremde Installation). Steuert die Alarmierung (#20). */ +export class LicenseCheckError extends Error { + constructor(message: string, readonly kind: 'config' | 'outage' | 'rejected' = 'config') { super(message); } +} /** Fragt /license/verify live ab, prüft die Signatur und schreibt das Ergebnis in license_state. * Wirft bei fehlender Konfiguration oder Netzwerkfehler (ruft NICHT selbst den gecachten Zustand ab - @@ -75,13 +79,16 @@ export async function checkLicenseNow(): Promise { body: JSON.stringify({ licenseKey, instanceId: row.instance_id }), signal: AbortSignal.timeout(15000), }); } catch (e) { - await run('UPDATE license_state SET last_error = ? WHERE id = 1', [`Netzwerkfehler: ${(e as Error).message}`.slice(0, 500)]); - throw new LicenseCheckError(`Lizenzserver nicht erreichbar: ${(e as Error).message}`); + await run("UPDATE license_state SET last_error = ?, last_error_kind = 'outage' WHERE id = 1", [`Netzwerkfehler: ${(e as Error).message}`.slice(0, 500)]); + throw new LicenseCheckError(`Lizenzserver nicht erreichbar: ${(e as Error).message}`, 'outage'); + } + if (res.status === 401) { await run("UPDATE license_state SET last_error = ?, last_error_kind = 'config' WHERE id = 1", ['Program-Key ungültig (LICENSE_PROGRAM_KEY)']); throw new LicenseCheckError('Program-Key ungültig', 'config'); } + if (!res.ok) { + const msg = `Lizenzserver: HTTP ${res.status}`; const kind = res.status >= 500 || res.status === 429 ? 'outage' as const : 'rejected' as const; + await run('UPDATE license_state SET last_error = ?, last_error_kind = ? WHERE id = 1', [msg, kind]); throw new LicenseCheckError(msg, kind); } - if (res.status === 401) { await run('UPDATE license_state SET last_error = ? WHERE id = 1', ['Program-Key ungültig (LICENSE_PROGRAM_KEY)']); throw new LicenseCheckError('Program-Key ungültig'); } - if (!res.ok) { const msg = `Lizenzserver: HTTP ${res.status}`; await run('UPDATE license_state SET last_error = ? WHERE id = 1', [msg]); throw new LicenseCheckError(msg); } const data = await res.json() as VerifyResult; - const fail = async (msg: string): Promise => { await run('UPDATE license_state SET last_error = ? WHERE id = 1', [msg]); throw new LicenseCheckError(msg); }; + const fail = async (msg: string): Promise => { await run("UPDATE license_state SET last_error = ?, last_error_kind = 'rejected' WHERE id = 1", [msg]); throw new LicenseCheckError(msg, 'rejected'); }; // Signatur ist Pflicht: übernommen werden NUR Werte aus dem geprüften Payload, nie die äußeren JSON-Felder // (die könnte ein Mann-in-der-Mitte oder ein vorgetäuschter Server beliebig setzen). @@ -111,7 +118,7 @@ export async function checkLicenseNow(): Promise { await run( `UPDATE license_state SET valid=?, message=?, plan=?, modules_json=?, expires_at=?, user_limit=?, customer_limit=?, - entitlement_version=?, is_trial=?, addons_json=?, server_time=?, checked_at=UTC_TIMESTAMP(3), last_error=NULL WHERE id=1`, + entitlement_version=?, is_trial=?, addons_json=?, server_time=?, checked_at=UTC_TIMESTAMP(3), last_error=NULL, last_error_kind=NULL WHERE id=1`, [signed.valid, signed.message, signed.plan, JSON.stringify(signed.modules), signed.expiresAt ? new Date(signed.expiresAt) : null, signed.userLimit, signed.customerLimit, signed.entitlementVersion, signed.trial, JSON.stringify(signed.addons), serverTime], ); diff --git a/packages/platform/src/monitor.ts b/packages/platform/src/monitor.ts new file mode 100644 index 0000000..9c28382 --- /dev/null +++ b/packages/platform/src/monitor.ts @@ -0,0 +1,76 @@ +import { one, query, run, tx } from './db.js'; + +/** + * Betriebsalarme mit Entwarnung (#20/#38). Ein Zustand (z. B. „Lizenzserver nicht erreichbar“) wird bei jeder Prüfung + * als aktiv/inaktiv gemeldet. Gemeldet wird erst, wenn er die Karenzzeit überdauert (kurze Aussetzer lösen nichts + * aus), und je Vorfall genau einmal; die Entwarnung folgt nur, wenn vorher gemeldet wurde. Der Zustand ist in der + * Oberfläche auch ohne Discord/Mail sichtbar (GET /admin/system → alerts). + */ +export interface Condition { key: string; active: boolean; detail?: string | null; graceMs?: number } +export type AlertNotify = (key: string, kind: 'alarm' | 'recovery', detail: string | null) => Promise; + +export async function applyConditions(conditions: Condition[], notify: AlertNotify, now = new Date()): Promise { + for (const c of conditions) { + const action = await tx(async (cn) => { + await run('INSERT IGNORE INTO system_alerts (alert_key, active) VALUES (?, 0)', [c.key], cn); + const row = (await one('SELECT * FROM system_alerts WHERE alert_key = ? FOR UPDATE', [c.key], cn))!; + const detail = c.detail?.slice(0, 500) ?? null; + if (c.active) { + const since = row.active ? new Date(row.since as Date) : now; + if (!row.active) await run('UPDATE system_alerts SET active = 1, since = ?, notified_at = NULL, resolved_at = NULL, detail = ? WHERE alert_key = ?', [now, detail, c.key], cn); + else await run('UPDATE system_alerts SET detail = ? WHERE alert_key = ?', [detail, c.key], cn); + if (!row.notified_at && now.getTime() - since.getTime() >= (c.graceMs ?? 0)) { + await run('UPDATE system_alerts SET notified_at = ? WHERE alert_key = ?', [now, c.key], cn); + return { kind: 'alarm' as const, detail }; + } + return null; + } + if (!row.active) return null; + await run('UPDATE system_alerts SET active = 0, resolved_at = ? WHERE alert_key = ?', [now, c.key], cn); + return row.notified_at ? { kind: 'recovery' as const, detail: row.detail as string | null } : null; + }); + if (action) await notify(c.key, action.kind, action.detail); + } +} + +export async function heartbeat(name: string): Promise { + await run('INSERT INTO system_heartbeats (name, at) VALUES (?, UTC_TIMESTAMP(3)) ON DUPLICATE KEY UPDATE at = VALUES(at)', [name]); +} +export async function heartbeatAgeMs(name: string): Promise { + const r = await one('SELECT TIMESTAMPDIFF(MICROSECOND, at, UTC_TIMESTAMP(3)) AS us FROM system_heartbeats WHERE name = ?', [name]); + return r ? Number(r.us) / 1000 : null; +} +export async function activeAlerts(): Promise<{ key: string; since: Date; detail: string | null; notified: boolean }[]> { + const rows = await query('SELECT alert_key, since, detail, notified_at FROM system_alerts WHERE active = 1 ORDER BY since'); + return rows.map((r) => ({ key: r.alert_key, since: r.since, detail: r.detail, notified: !!r.notified_at })); +} + +/** Texte der Meldungen (ohne personenbezogene Daten). */ +export const ALERT_LABEL: Record = { + 'license.unreachable': 'Lizenzserver nicht erreichbar', + 'license.problem': 'Problem mit der eigenen Lizenz (Konfiguration oder Ablehnung)', + 'jobs.backlog': 'Auftragswarteschlange staut sich', + 'jobs.needs_review': 'Aufträge warten auf Prüfung', + 'worker.down': 'Hintergrunddienst (kc-worker) arbeitet nicht', +}; +export const alertText = (key: string, kind: 'alarm' | 'recovery', detail: string | null): string => + kind === 'alarm' ? `⚠ ${ALERT_LABEL[key] ?? key}${detail ? `: ${detail}` : ''}` : `✅ Entwarnung: ${ALERT_LABEL[key] ?? key} – wieder in Ordnung`; + +/** Zustände, die der Worker selbst prüft (Lizenz, Warteschlange). */ +export async function workerConditions(): Promise { + const ls = await one('SELECT license_key_enc, last_error, last_error_kind, valid, message, checked_at FROM license_state WHERE id = 1'); + const due = await one("SELECT COUNT(*) AS n, MIN(run_at) AS oldest FROM jobs WHERE status IN ('scheduled','retrying') AND run_at < DATE_SUB(UTC_TIMESTAMP(3), INTERVAL 10 MINUTE)"); + const review = await one("SELECT COUNT(*) AS n FROM jobs WHERE status = 'needs_review'"); + const kind = ls?.license_key_enc ? ls.last_error_kind as string | null : null; // ohne Schlüssel: Testmodus, kein Alarm + return [ + { key: 'license.unreachable', active: kind === 'outage', detail: kind === 'outage' ? ls!.last_error : null, graceMs: 30 * 60_000 }, + // Konfigurationsfehler/Ablehnung ODER Lizenzserver meldet die Lizenz als ungültig (abgelaufen, gesperrt) + (() => { + const bad = kind === 'config' || kind === 'rejected'; + const invalid = !!ls?.license_key_enc && !!ls.checked_at && !ls.valid; + return { key: 'license.problem', active: bad || invalid, detail: bad ? ls!.last_error : invalid ? (ls!.message ?? 'Lizenz ungültig') : null, graceMs: 0 }; + })(), + { key: 'jobs.backlog', active: Number(due?.n ?? 0) > 0, detail: Number(due?.n ?? 0) > 0 ? `${due!.n} fällige Aufträge seit über 10 Minuten nicht bearbeitet` : null, graceMs: 5 * 60_000 }, + { key: 'jobs.needs_review', active: Number(review?.n ?? 0) > 0, detail: Number(review?.n ?? 0) > 0 ? `${review!.n} Auftrag/Aufträge mit unklarem Ergebnis (Verwaltung → Aufträge)` : null, graceMs: 0 }, + ]; +}