feat: status documentation

juliankoehn · juliankoehn · commit 72606e3b395d · 2025-09-18T13:48:06.000+02:00
diff --git a/content/docs/platform/compliance/controls/index.mdx b/content/docs/platform/compliance/controls/index.mdx
@@ -3,10 +3,24 @@ title: Controls
 description: "Controls als Kernbaustein: Von Framework-Anforderungen über Implementierungen bis hin zu Evidences"
 ---
 
+import { getPageTreePeers } from 'fumadocs-core/server';
+import { source } from '@/lib/source';
+
+<Cards>
+  <Card title="Status" href="/platform/compliance/controls/status">
+    Lerne mehr über den Control Status
+  </Card>
+  <Card title="Control Implementations" href="/platform/compliance/controls/control-implementations">
+    Erfahre, wie Controls praktisch umgesetzt werden
+  </Card>
+</Cards>
+
 ## Controls: Der strukturierte Ansatz für nachweisbare Compliance
 
 Controls bilden das strategische Fundament jeder effektiven Compliance-Strategie. Anders als bei traditionellen GRC-Tools, die sich auf das reine Hochladen von Policy-Dokumenten beschränken, implementiert Kopexa einen systematischen Control-basierten Ansatz, der messbare Sicherheitsziele mit konkreten Umsetzungsmaßnahmen verknüpft.
 
+
+
 ## Was sind Controls?
 
 Ein **Control** definiert ein spezifisches Sicherheits- oder Compliance-Ziel, das erreicht werden soll. Controls beschreiben nicht das "Wie", sondern das "Was" - sie geben vor, welcher Sicherheitsstandard erfüllt werden muss, ohne die konkrete Implementierung zu diktieren.
@@ -33,13 +47,13 @@ Ein **Control** definiert ein spezifisches Sicherheits- oder Compliance-Ziel, da
 
 ## Framework-Integration: Ein Control, mehrere Standards
 
-Ein Control in Kopexa kann mehrere Compliance-Frameworks gleichzeitig abdecken.  
+Ein Control in Kopexa kann mehrere Compliance-Frameworks gleichzeitig abdecken.
 
-**Beispiel-Control:** *„Regelmäßige Überprüfung von Zugangsrechten“*  
-- ISO 27001: A.9.2.5  
-- SOC 2: CC6.2  
-- NIST CSF: PR.AC-4  
-- TISAX: 3.1.1  
+**Beispiel-Control:** *„Regelmäßige Überprüfung von Zugangsrechten“*
+- ISO 27001: A.9.2.5
+- SOC 2: CC6.2
+- NIST CSF: PR.AC-4
+- TISAX: 3.1.1
 
 <Callout>
 So wird Doppelarbeit reduziert und ein einheitlicher Nachweis über mehrere Frameworks hinweg möglich.
@@ -59,7 +73,7 @@ graph TD
 - **Definition**: Was soll erreicht werden?
 - **Beispiel**: "Alle Benutzerkonten müssen eindeutig identifizierbar sein"
 
-### 2. Implementation (Umsetzungsmaßnahme)  
+### 2. Implementation (Umsetzungsmaßnahme)
 - **Definition**: Wie wird das Control umgesetzt?
 - **Beispiel**: "Active Directory-basierte Benutzerauthentifizierung mit eindeutigen Benutzernamen"
 
@@ -92,7 +106,7 @@ graph LR
 ### 2. Implementation-Flexibilität gewährleisten
 Controls sollten verschiedene Implementierungsansätze zulassen:
 
-**Control: "Sensible Daten werden gegen unbefugten Zugriff geschützt"**.  
+**Control: "Sensible Daten werden gegen unbefugten Zugriff geschützt"**.
 Mögliche Implementations:
 
 - Encryption-at-Rest via BitLocker
@@ -138,7 +152,7 @@ console.log(`Control ${controlStatus.name}: ${controlStatus.status}`);
 
 ### Traditionelle Policy-Uploads: Die Limitierungen
 - **Statischer Content**: Keine Verknüpfung zu aktuellen Implementierungen
-- **Audit-Ineffizienz**: Manuelle Prüfung jedes Dokuments erforderlich  
+- **Audit-Ineffizienz**: Manuelle Prüfung jedes Dokuments erforderlich
 - **Redundanzen**: Gleiche Inhalte in verschiedenen Framework-Dokumenten
 - **Versionsprobleme**: Inkonsistente Policy-Versionen across Frameworks
 
@@ -147,10 +161,10 @@ console.log(`Control ${controlStatus.name}: ${controlStatus.status}`);
 
 - **Dynamic Mapping**: Ein Control bedient multiple Frameworks
 - **Implementation-Tracking**: Direkte Verknüpfung zu Umsetzungsmaßnahmen
-- **Automated Evidence**: Continuous Compliance-Monitoring  
+- **Automated Evidence**: Continuous Compliance-Monitoring
 - **Audit-Readiness**: Jederzeit prüfbare Compliance-Status
 
 
 <Callout>
 Kopexa transformiert Compliance von einem dokumentenlastigen, reaktiven Prozess zu einem strukturierten, kontinuierlich überwachten System.
-</Callout>
+</Callout>
diff --git a/content/docs/platform/compliance/controls/status.mdx b/content/docs/platform/compliance/controls/status.mdx
@@ -0,0 +1,141 @@
+---
+title: Status Models
+description: Einheitliche Status-Logik für Controls, Control Implementations und Evidences
+---
+
+## Warum Status-Modelle?
+
+In klassischen GRC-Tools muss der Status oft **manuell gepflegt** werden: Excel-Spalten, Notizen oder Kommentare.
+Das führt zu **Inkonsistenzen**, widersprüchlichen Bewertungen und viel Nacharbeit in Audits.
+
+Kopexa geht einen anderen Weg:
+Der Status wird **automatisch** berechnet – immer auf Basis der Verknüpfungen zwischen Controls, Implementations und Evidences.
+So entsteht eine **lebendige Compliance-Landkarte**, die ohne manuelles Pflegen konsistent bleibt und für Auditor:innen jederzeit nachvollziehbar ist.
+
+<Callout>
+**Dein Vorteil:** Weniger Verwaltungsarbeit, weniger Diskussionen im Audit, mehr Zeit für die tatsächliche Verbesserung deiner Sicherheitsmaßnahmen.
+</Callout>
+
+## Control Status
+
+Controls sind die „oberste Ebene“ – sie definieren, **was** erreicht werden soll.
+Ihr Status ergibt sich automatisch aus den zugeordneten Implementations.
+
+| Status | Bedeutung | Typische Ursache |
+|--------|-----------|------------------|
+| **PREPARING** | Control ist angelegt, aber noch nicht weiter bearbeitet | Neu erstellt |
+| **OUT_OF_SCOPE** | Control ist für den Scope nicht relevant | z. B. Technologie nicht im Einsatz |
+| **IN_PROGRESS** | Erste Arbeiten laufen, Implementations werden zugeordnet | Work in progress |
+| **NEEDS_APPROVAL** | Mindestens eine Implementation ist nicht genehmigt oder unvollständig | Review offen |
+| **FULFILLED** | Alle Implementations sind *PUBLISHED* | Erfolgreiche Umsetzung |
+
+<Mermaid chart={`
+graph LR
+  A[PREPARING] --> B[IN_PROGRESS]
+  B --> C[NEEDS_APPROVAL]
+  C -->|approved| D[FULFILLED]
+  A --> E[OUT_OF_SCOPE]
+`} />
+
+**Warum hilfreich?**
+- Du erkennst sofort, welche Controls noch offen oder blockiert sind.
+- Auditor:innen sehen eine klare Story: von Planung (PREPARING) bis Nachweis (FULFILLED).
+- OUT_OF_SCOPE verhindert, dass irrelevante Anforderungen dein Reporting aufblähen.
+
+## Control Implementation Status
+
+Implementations sind die konkreten **Maßnahmen (TOMs)**, die ein Control umsetzen.
+Ihr Status hängt ausschließlich von den hinterlegten Evidences ab.
+
+| Status | Bedeutung | Typische Ursache |
+|--------|-----------|------------------|
+| **MISSING_EVIDENCE** | Keine oder zu wenige Evidences vorhanden | Maßnahme dokumentiert, aber nicht belegt |
+| **NEEDS_APPROVAL** | Mindestens eine Evidence ist noch nicht bestätigt oder unvollständig | Review offen |
+| **PUBLISHED** | Alle Evidences sind vorhanden und gültig | Vollständig umgesetzt |
+| **ARCHIVED** | Implementation ist nicht mehr aktiv gültig | Maßnahme ersetzt oder außer Betrieb |
+
+<Mermaid chart={`
+graph LR
+  A[MISSING_EVIDENCE] --> B[NEEDS_APPROVAL]
+  B -->|approved| C[PUBLISHED]
+  C --> D[ARCHIVED]
+`} />
+
+**Warum hilfreich?**
+- Du siehst nicht nur, ob eine Maßnahme existiert, sondern ob sie **wirksam nachgewiesen** ist.
+- Das schützt vor „Papier-Controls“, die zwar dokumentiert, aber nicht überprüfbar sind.
+- ARCHIVED sorgt dafür, dass alte Maßnahmen nicht fälschlich als aktiv gewertet werden.
+
+## Evidence Lifecycle
+
+Evidences sind der **Beweis**, dass eine Implementation tatsächlich umgesetzt ist.
+Sie verknüpfen Maßnahmen mit Nachweisen – wie Policies, Audit-Logs, Screenshots oder Prozessdokumente.
+
+In Kopexa hängen Evidences oft an **Dokumenten**, die selbst einen Lifecycle haben (Status, Review, Versionierung).
+Dieser Dokument-Lifecycle beeinflusst den Status der Evidence **automatisch**.
+
+### Evidence Status
+
+| Status | Bedeutung | Typische Ursache |
+|--------|-----------|------------------|
+| **PENDING** | Evidence ist angelegt, aber noch nicht geprüft | Neu erstellt |
+| **ACTION REQUIRED** | Unterliegendes Dokument oder Nachweis ist abgelaufen oder im Review | Dokument expired / Review fällig |
+| **PASSED** | Evidence ist gültig und überprüft | Dokument freigegeben |
+| **FAILED** | Evidence ist ungültig (z. B. Dokument gelöscht oder zurückgezogen) | Policy widerrufen / Fehlerhafte Evidence |
+
+<Mermaid chart={`
+graph LR
+  A[Document Lifecycle] --> B[Evidence Status]
+  B --> C[Implementation Status]
+  C --> D[Control Status]
+`} />
+
+### Beispiel
+
+- Eine Richtlinie (*Document*) läuft in den jährlichen Review-Zyklus.
+- Das Dokument springt auf den Status **"Review required"**.
+- Alle Evidences, die auf dieser Richtlinie basieren, wechseln automatisch auf **"ACTION REQUIRED"**.
+- Die betroffenen Implementations und Controls werden dadurch ebenfalls abgewertet.
+
+So entsteht eine **durchgehende Kette**: Dokument → Evidence → Implementation → Control.
+
+### Warum wichtig?
+
+- **Realistische Nachweise:** Evidences spiegeln nicht nur einen Upload wider, sondern den echten Gültigkeitsstatus.
+- **Früherkennung:** Sobald ein Dokument im Review ist, erkennt Kopexa automatisch, dass Handlungsbedarf besteht.
+- **Audit-Sicherheit:** Auditor:innen sehen, dass Nachweise nicht nur einmalig hochgeladen, sondern kontinuierlich überwacht werden.
+
+<Callout>
+**Benefit für dich:** Keine Excel-Reminder mehr nötig. Kopexa erkennt automatisch, wann Evidences „stale“ werden und markiert deine Controls entsprechend.
+</Callout>
+
+## Best Practices
+
+- **Automatisiert statt manuell:** Kein Status-Klicken mehr – Kopexa übernimmt das.
+- **Transparente Logik:** Jeder Status ist klar dokumentiert und nachvollziehbar.
+- **Audit-Ready:** Ein Prüfer kann jederzeit vom Control bis zur einzelnen Evidence zurückverfolgen, wie ein Status zustande kam.
+- **Fokus auf Wirksamkeit:** Dein Team investiert Zeit in echte Verbesserungen statt in Status-Pflege.
+
+<Callout>
+Mit Kopexa siehst du nicht nur, **was geplant** ist, sondern auch **was nachweislich funktioniert**.
+</Callout>
+
+## FAQ
+
+<Accordions type="single">
+  <Accordion title="Warum setzt Kopexa auf automatische Status?">
+      Damit Compliance **konsistent und auditierbar** bleibt – unabhängig davon, wer im Team pflegt oder reviewt.
+  </Accordion>
+  <Accordion title="Kann ich den Status manuell überschreiben?">
+    Nein. Status sind **immer systemisch berechnet**, um Manipulation und Fehler auszuschließen.
+    Du steuerst einen Status indirekt, indem du **Implementations** pflegst und **Evidences** bereitstellst.
+  </Accordion>
+  <Accordion title="Was unterscheidet Evidence von einem Dokument?">
+      Ein Dokument ist eine **Quelle** (z. B. Policy-PDF, Screenshot).
+      Eine Evidence ist der **Nachweis**, dass dieses Dokument zur Umsetzung einer Implementation genutzt wird.
+  </Accordion>
+  <Accordion title='Warum gibt es "Out of Scope"?'>
+      Damit du klar zeigen kannst, dass ein Control im **Audit-Scope irrelevant** ist – ohne es zu löschen.
+      Das reduziert Rückfragen und zeigt Professionalität im Compliance-Management.
+  </Accordion>
+</Accordions>
diff --git a/package.json b/package.json
@@ -11,6 +11,7 @@
 		"postinstall": "fumadocs-mdx"
 	},
 	"dependencies": {
+		"@radix-ui/react-accordion": "^1.2.12",
 		"@radix-ui/react-collapsible": "^1.1.12",
 		"@radix-ui/react-popover": "^1.1.15",
 		"@radix-ui/react-presence": "^1.1.5",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/components/accordion.tsx b/src/components/accordion.tsx
@@ -0,0 +1,136 @@
+'use client';
+
+import type {
+  AccordionMultipleProps,
+  AccordionSingleProps,
+} from '@radix-ui/react-accordion';
+import * as AccordionPrimitive from '@radix-ui/react-accordion';
+import { Check, ChevronRight, Link as LinkIcon } from 'lucide-react';
+import {
+  type ComponentPropsWithoutRef,
+  forwardRef,
+  type ReactNode,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { cn } from '../lib/cn';
+import { useCopyButton } from 'fumadocs-ui/utils/use-copy-button';
+import { buttonVariants } from './ui/button';
+import { mergeRefs } from '../lib/merge-refs';
+
+export const Accordions = forwardRef<
+  HTMLDivElement,
+  | Omit<AccordionSingleProps, 'value' | 'onValueChange'>
+  | Omit<AccordionMultipleProps, 'value' | 'onValueChange'>
+>(({ type = 'single', className, defaultValue, ...props }, ref) => {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const composedRef = mergeRefs(ref, rootRef);
+  const [value, setValue] = useState<string | string[]>(() =>
+    type === 'single' ? (defaultValue ?? '') : (defaultValue ?? []),
+  );
+
+  useEffect(() => {
+    const id = window.location.hash.substring(1);
+    const element = rootRef.current;
+    if (!element || id.length === 0) return;
+
+    const selected = document.getElementById(id);
+    if (!selected || !element.contains(selected)) return;
+    const value = selected.getAttribute('data-accordion-value');
+
+    if (value)
+      setValue((prev) => (typeof prev === 'string' ? value : [value, ...prev]));
+  }, []);
+
+  return (
+    // @ts-expect-error -- Multiple types
+    <AccordionPrimitive.Root
+      type={type}
+      ref={composedRef}
+      value={value}
+      onValueChange={setValue}
+      collapsible={type === 'single' ? true : undefined}
+      className={cn(
+        'divide-y divide-fd-border overflow-hidden rounded-lg border bg-fd-card',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+Accordions.displayName = 'Accordions';
+
+export const Accordion = forwardRef<
+  HTMLDivElement,
+  Omit<
+    ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>,
+    'value' | 'title'
+  > & {
+    title: string | ReactNode;
+    value?: string;
+  }
+>(
+  (
+    { title, className, id, value = String(title), children, ...props },
+    ref,
+  ) => {
+    return (
+      <AccordionPrimitive.Item
+        ref={ref}
+        value={value}
+        className={cn('scroll-m-24', className)}
+        {...props}
+      >
+        <AccordionPrimitive.Header
+          id={id}
+          data-accordion-value={value}
+          className="not-prose flex flex-row items-center text-fd-card-foreground font-medium has-focus-visible:bg-fd-accent"
+        >
+          <AccordionPrimitive.Trigger className="group flex flex-1 items-center gap-2 px-3 py-2.5 text-start focus-visible:outline-none">
+            <ChevronRight className="size-4 shrink-0 text-fd-muted-foreground transition-transform duration-200 group-data-[state=open]:rotate-90" />
+            {title}
+          </AccordionPrimitive.Trigger>
+          {id ? <CopyButton id={id} /> : null}
+        </AccordionPrimitive.Header>
+        <AccordionPrimitive.Content className="overflow-hidden data-[state=closed]:animate-fd-accordion-up data-[state=open]:animate-fd-accordion-down">
+          <div className="px-4 pb-2 text-[15px] prose-no-margin">
+            {children}
+          </div>
+        </AccordionPrimitive.Content>
+      </AccordionPrimitive.Item>
+    );
+  },
+);
+
+function CopyButton({ id }: { id: string }) {
+  const [checked, onClick] = useCopyButton(() => {
+    const url = new URL(window.location.href);
+    url.hash = id;
+
+    return navigator.clipboard.writeText(url.toString());
+  });
+
+  return (
+    <button
+      type="button"
+      aria-label="Copy Link"
+      className={cn(
+        buttonVariants({
+          color: 'ghost',
+          className: 'text-fd-muted-foreground me-2',
+        }),
+      )}
+      onClick={onClick}
+    >
+      {checked ? (
+        <Check className="size-3.5" />
+      ) : (
+        <LinkIcon className="size-3.5" />
+      )}
+    </button>
+  );
+}
+
+Accordion.displayName = 'Accordion';
diff --git a/src/mdx-components.tsx b/src/mdx-components.tsx
