Files
Dominik Schön e5261401fe feat(runbook): Notfall-Runbook + Inline-Hints an Alarm-Flaechen (CHO tower-notfall-runbook)
DATEI 1: public/runbook/runbook-tower-notfall.md (statisch, Anker #deadman/#spool/#deadletter/#health)
DATEI 2: /runbook-Route (Server Component, Mini-MD-Renderer, CSP-konform, force-static)
DATEI 3: runbookHints.ts (LAMP_HINTS/buildView/renderHintHtml 1:1 aus runbook_hints.py)
       + RunbookHint.tsx eingebunden an 4 Alarm-Flaechen:
         - EscalationHistory (Deadman, Szenario A)
         - TaskBrowser Spool-Tab (Szenario B) + Dead-Letter-Tab (B3)
         - TaskBrowser/OpsPanels Degraded/Error (Health, Szenario C)
Keine Ampelfarben/Deadman-Logik/Degraded-Banner/Datenpfade angefasst (CHO-NICHT ANFASSEN erfuellt).
Build verifiziert: tsc --noEmit clean, next build gruen (/runbook static).
2026-10-30 16:58:17 +00:00

162 lines
5.5 KiB
TypeScript

/**
* runbookHints.ts — 1:1-Portierung von /sandbox/fleet-change-orders/
* tower-notfall-runbook/runbook_hints.py (Karte tower-notfall-runbook, devops).
*
* Zweck: Kurzschritte + Eskalationskontakt fuer den Owner direkt an den
* Alarm-Ampeln des Towers (10.0.30.213, tcp/8099) als kontextueller
* Inline-Hint mit Deep-Link auf das Notfall-Runbook (/runbook#<anker>).
*
* Rein statisch — KEINE Datenquelle, KEIN Polling, KEIN Egress, KEINE
* Secrets. LAMP_HINTS + buildView() + renderHintHtml() entsprechen
* LAMP_HINTS + build_view() + render_hint_html() der Referenz 1:1.
*/
export const RUNBOOK_URL = "/runbook"
export type LampHint = {
key: "deadman" | "spool" | "health" | "deadletter"
component: string
badge_id: string | null
anchor: string
scenario: string
title: string
core: boolean
kurzschritte: string[]
eskalation: string
}
// Reihenfolge = Anzeige-Reihenfolge im Tower-Header/Panel.
// core=true -> Pflicht-Ampel laut Karte (Deadman-Blockade, Spool-Stau, Panel-Ausfall).
export const LAMP_HINTS: LampHint[] = [
{
key: "deadman",
component: "Deadman-Status",
badge_id: "dm-badge",
anchor: "#deadman",
scenario: "A",
title: "Deadman-Blockade",
core: true,
kurzschritte: [
"Owner-Queue oeffnen: blockierenden Task (ID, Typ, Alter) an der Deadman-Ampel ablesen.",
"Task in der Queue entscheiden (Abnahme/Review/NAR) oder mit reply_to + Kommentar zurueckgeben.",
"Deadman-Ampel auf 'progress' pruefen (Auto-Refresh 30 s).",
],
eskalation:
"Bleibt 'blocked' > 5400 s oder ist der Task unklar: Owner ueber die Owner-Queue informieren (Grund + Task-ID nennen).",
},
{
key: "spool",
component: "Spool-Aging (Reife)",
badge_id: "sp-badge",
anchor: "#spool",
scenario: "B",
title: "Spool-Stau",
core: true,
kurzschritte: [
"Spool-Aging: aeltesten roten Envelope (> 5400 s) + Empfaenger ablesen.",
"Empfaenger gruen: Task an denselben Empfaenger erneut submitten (reply_to setzen).",
"Empfaenger rot: zuerst Szenario A/C loesen; Failed-Tasks ueber die Dead-Letter-Ansicht (#deadletter) pruefen.",
],
eskalation:
"Envelope > 5400 s ohne roten Empfaenger (Ursache unklar): an tower-owner ueber den CISO-Kanal melden (Envelope-IDs); ab 2 betroffenen Agents zusaetzlich Owner informieren.",
},
{
key: "health",
component: "Health-Ampel / Panel",
badge_id: null,
anchor: "#health",
scenario: "C",
title: "Panel-Ausfall",
core: true,
kurzschritte: [
"/healthz pruefen: 200 = Server lebt, Problem liegt bei Datenquelle/UI.",
"/api/status + Degraded-Banner: Quelle down = Degraded (60 s-Cache laeuft weiter), KEIN Totalausfall.",
"Kein 200 / Verbindung abgelehnt = Totalausfall: Neustart/Deploy nur ueber Aenderungsauftrag, nicht selbst am Host.",
],
eskalation:
"healthz-Ausfall oder Deploy-Bedarf: sofort P1 an tower-owner ueber den CISO-Kanal; parallel Owner informieren (ohne Panel ist die Lage nur ueber die Agenten-Boards sichtbar).",
},
{
key: "deadletter",
component: "Dead-Letter-Ansicht",
badge_id: null,
anchor: "#deadletter",
scenario: "B3",
title: "Verlorene Tasks",
core: false,
kurzschritte: [
"Dead-Letter: failed-Tasks (7 Tage) mit from->to + Alter pruefen.",
"Wiederholbar: erneut submitten (reply_to); unloesbar: Task mit Grund neu aufsetzen, nicht still verwerfen.",
],
eskalation:
"Gehaeufte Failed-Tasks eines Empfaengers: Empfaenger-Health pruefen (#health), dann wie Szenario B eskalieren.",
},
]
/** Hint per key (statisch, wirft bei unbekanntem key). */
export function hintByKey(key: LampHint["key"]): LampHint {
const h = LAMP_HINTS.find((x) => x.key === key)
if (!h) throw new Error(`unknown runbook hint: ${key}`)
return h
}
export type HintView = {
key: string
component: string
badge_id: string | null
scenario: string
title: string
core: boolean
anchor: string
url: string
kurzschritte: string[]
eskalation: string
html: string
}
/** Statische Hint-Ansicht (JSON-faehig) — entspricht build_view(). */
export function buildView(now: string | null = null, source = "static") {
const hints: HintView[] = LAMP_HINTS.map((h) => ({
key: h.key,
component: h.component,
badge_id: h.badge_id,
scenario: h.scenario,
title: h.title,
core: h.core,
anchor: h.anchor,
url: RUNBOOK_URL + h.anchor,
kurzschritte: [...h.kurzschritte],
eskalation: h.eskalation,
html: renderHintHtml(h),
}))
return {
generated_at: now,
source,
runbook_url: RUNBOOK_URL,
refresh_seconds: 0, // statisch
hint_count: hints.length,
core_count: hints.filter((h) => h.core).length,
hints,
}
}
function escapeHtml(s: string): string {
return s
.replace(/&/g, "&amp;")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/"/g, "&quot;")
}
/** Kompakter Inline-Hint als HTML-String (rein Text + interner Link). */
export function renderHintHtml(h: LampHint): string {
const esc = escapeHtml
const stepLis = h.kurzschritte.map((s) => `<li>${esc(s)}</li>`).join("")
return `<div id="hint-${esc(h.key)}" class="lamp-hint" data-component="${esc(h.component)}">` +
`<span class="lh-title">Notfall ${esc(h.scenario)} &mdash; ${esc(h.title)}</span>` +
`<ol class="lh-steps">${stepLis}</ol>` +
`<div class="lh-esc"><strong>Eskalation:</strong> ${esc(h.eskalation)}</div>` +
`<a class="lh-link" href="${esc(RUNBOOK_URL + h.anchor)}">Vollstaendiges Runbook &rarr;</a>` +
`</div>`
}