docs: DSFA Modul — MkDocs + Developer Portal Dokumentation

- docs-src/services/sdk-modules/dsfa.md: vollständige DSFA-Dokumentation (Endpoints, Datenmodell, Status-Workflow, DB-Tabellen, Tests, Compliance-Kontext) - mkdocs.yml: DSFA in Navigation unter SDK Module eingefügt - docs-src/index.md: DSFA + Paket-Links in Services-Dokumentation - docs-src/services/sdk-modules/dokumentations-module.md: DSFA in Übersichtstabelle - developer-portal/app/api/dsfa/page.tsx: vollständige API-Referenz mit cURL-Beispielen - developer-portal/app/api/page.tsx: DSFA-Abschnitt mit allen 8 Endpoints Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-04 22:55:31 +01:00
parent a694b9d9ea
commit a9de7b4010
6 changed files with 570 additions and 0 deletions
--- a/developer-portal/app/api/dsfa/page.tsx
+++ b/developer-portal/app/api/dsfa/page.tsx
@@ -0,0 +1,282 @@
+import { DevPortalLayout, ApiEndpoint, CodeBlock, ParameterTable, InfoBox } from '@/components/DevPortalLayout'
+
+export default function DsfaApiPage() {
+  return (
+    <DevPortalLayout
+      title="DSFA API"
+      description="Datenschutz-Folgenabschätzung (Art. 35 DSGVO) verwalten"
+    >
+      <h2>Übersicht</h2>
+      <p>
+        Die DSFA API ermöglicht die vollständige Verwaltung von Datenschutz-Folgenabschätzungen
+        gemäß Art. 35 DSGVO. Alle DSFAs werden backend-persistent gespeichert und mit
+        vollständigem Audit-Trail protokolliert.
+      </p>
+
+      <InfoBox type="warning" title="Wann ist eine DSFA Pflicht?">
+        Eine DSFA ist zwingend erforderlich bei voraussichtlich hohem Risiko für Betroffene:
+        automatisierte Entscheidungen / Profiling, umfangreiche Verarbeitung sensibler Daten,
+        systematische Überwachung öffentlicher Bereiche oder KI-Hochrisiko-Systeme (EU AI Act).
+      </InfoBox>
+
+      <InfoBox type="info" title="Tenant-ID">
+        Alle Endpoints akzeptieren <code>tenant_id</code> als Query-Parameter.
+        Ohne Angabe wird <code>default</code> als Tenant-ID verwendet.
+      </InfoBox>
+
+      {/* ===================================================================== */}
+      {/* Liste */}
+      {/* ===================================================================== */}
+
+      <h2>GET /dsfa</h2>
+      <p>Gibt eine gefilterte Liste aller DSFAs für einen Tenant zurück.</p>
+
+      <h4>Query-Parameter</h4>
+      <ParameterTable
+        parameters={[
+          { name: 'tenant_id', type: 'string', required: false, description: 'Tenant-ID (Default: "default")' },
+          { name: 'status', type: 'string', required: false, description: 'Filter: draft | in-review | approved | needs-update' },
+          { name: 'risk_level', type: 'string', required: false, description: 'Filter: low | medium | high | critical' },
+          { name: 'skip', type: 'integer', required: false, description: 'Offset für Pagination (Default: 0)' },
+          { name: 'limit', type: 'integer', required: false, description: 'Max. Einträge (Default: 100, Max: 500)' },
+        ]}
+      />
+
+      <CodeBlock language="bash" filename="cURL">
+{`curl -X GET "https://api.breakpilot.io/sdk/v1/dsfa?tenant_id=mein-tenant&status=in-review" \\
+  -H "Authorization: Bearer YOUR_API_KEY"`}
+      </CodeBlock>
+
+      <CodeBlock language="json" filename="Response (200)">
+{`[
+  {
+    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "tenant_id": "mein-tenant",
+    "title": "DSFA - Bewerber-Management-System",
+    "description": "KI-gestütztes Bewerber-Screening",
+    "status": "in-review",
+    "risk_level": "high",
+    "processing_activity": "Automatisierte Bewertung von Bewerbungen",
+    "data_categories": ["Kontaktdaten", "Beruflicher Werdegang"],
+    "recipients": ["HR-Abteilung"],
+    "measures": ["Verschlüsselung", "Menschliche Prüfung"],
+    "approved_by": null,
+    "approved_at": null,
+    "created_by": "admin",
+    "created_at": "2026-03-04T10:00:00",
+    "updated_at": "2026-03-04T10:00:00"
+  }
+]`}
+      </CodeBlock>
+
+      {/* ===================================================================== */}
+      {/* Erstellen */}
+      {/* ===================================================================== */}
+
+      <h2>POST /dsfa</h2>
+      <p>Erstellt eine neue DSFA. Gibt HTTP 201 mit dem erstellten Datensatz zurück.</p>
+
+      <CodeBlock language="bash" filename="cURL">
+{`curl -X POST "https://api.breakpilot.io/sdk/v1/dsfa?tenant_id=mein-tenant" \\
+  -H "Authorization: Bearer YOUR_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "title": "DSFA - Video-Überwachung Büro",
+    "description": "Videoüberwachung zu Sicherheitszwecken",
+    "status": "draft",
+    "risk_level": "medium",
+    "processing_activity": "Videoüberwachung im Eingangsbereich",
+    "data_categories": ["Bilddaten", "Bewegungsdaten"],
+    "recipients": ["Sicherheitsdienst"],
+    "measures": ["Löschfristen 72h", "Hinweisschilder", "Zugangsbeschränkung"],
+    "created_by": "dsb@beispiel.de"
+  }'`}
+      </CodeBlock>
+
+      <CodeBlock language="json" filename="Response (201)">
+{`{
+  "id": "7b3a1c9d-4e2f-4a8b-9c1d-5f6a7b8c9d0e",
+  "tenant_id": "mein-tenant",
+  "title": "DSFA - Video-Überwachung Büro",
+  "status": "draft",
+  "risk_level": "medium",
+  "data_categories": ["Bilddaten", "Bewegungsdaten"],
+  "measures": ["Löschfristen 72h", "Hinweisschilder", "Zugangsbeschränkung"],
+  "created_at": "2026-03-04T12:00:00",
+  "updated_at": "2026-03-04T12:00:00"
+}`}
+      </CodeBlock>
+
+      <InfoBox type="info" title="Validierung">
+        <code>status</code> muss einer der Werte <code>draft</code>, <code>in-review</code>,{' '}
+        <code>approved</code>, <code>needs-update</code> sein.
+        <code>risk_level</code> muss <code>low</code>, <code>medium</code>, <code>high</code>{' '}
+        oder <code>critical</code> sein. Ungültige Werte → HTTP 422.
+      </InfoBox>
+
+      {/* ===================================================================== */}
+      {/* Einzeln abrufen */}
+      {/* ===================================================================== */}
+
+      <h2>GET /dsfa/{'{id}'}</h2>
+      <p>Gibt eine einzelne DSFA anhand ihrer UUID zurück.</p>
+
+      <CodeBlock language="bash" filename="cURL">
+{`curl -X GET "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d-4e2f-4a8b-9c1d-5f6a7b8c9d0e?tenant_id=mein-tenant" \\
+  -H "Authorization: Bearer YOUR_API_KEY"`}
+      </CodeBlock>
+
+      {/* ===================================================================== */}
+      {/* Aktualisieren */}
+      {/* ===================================================================== */}
+
+      <h2>PUT /dsfa/{'{id}'}</h2>
+      <p>
+        Aktualisiert eine DSFA. Alle Felder sind optional (Partial Update mit{' '}
+        <code>exclude_none</code>). Nur gesetzte Felder werden überschrieben.
+      </p>
+
+      <CodeBlock language="bash" filename="cURL">
+{`curl -X PUT "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d?tenant_id=mein-tenant" \\
+  -H "Authorization: Bearer YOUR_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "measures": ["Löschfristen 72h", "Hinweisschilder", "Biometrischer Zugang"],
+    "risk_level": "high"
+  }'`}
+      </CodeBlock>
+
+      {/* ===================================================================== */}
+      {/* Status-Wechsel */}
+      {/* ===================================================================== */}
+
+      <h2>PATCH /dsfa/{'{id}'}/status</h2>
+      <p>
+        Schnell-Statuswechsel ohne vollständiges Update. Bei Status{' '}
+        <code>approved</code> wird <code>approved_at</code> automatisch gesetzt.
+      </p>
+
+      <h4>Request Body</h4>
+      <ParameterTable
+        parameters={[
+          { name: 'status', type: 'string', required: true, description: 'Neuer Status: draft | in-review | approved | needs-update' },
+          { name: 'approved_by', type: 'string', required: false, description: 'Name/E-Mail des Genehmigers (empfohlen bei status=approved)' },
+        ]}
+      />
+
+      <CodeBlock language="bash" filename="cURL">
+{`curl -X PATCH "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d/status?tenant_id=mein-tenant" \\
+  -H "Authorization: Bearer YOUR_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "status": "approved",
+    "approved_by": "Max Mustermann (DSB)"
+  }'`}
+      </CodeBlock>
+
+      {/* ===================================================================== */}
+      {/* Löschen */}
+      {/* ===================================================================== */}
+
+      <h2>DELETE /dsfa/{'{id}'}</h2>
+      <p>
+        Löscht eine DSFA gemäß Art. 17 DSGVO. Die Löschung wird im Audit-Log protokolliert.
+      </p>
+
+      <CodeBlock language="bash" filename="cURL">
+{`curl -X DELETE "https://api.breakpilot.io/sdk/v1/dsfa/7b3a1c9d?tenant_id=mein-tenant" \\
+  -H "Authorization: Bearer YOUR_API_KEY"`}
+      </CodeBlock>
+
+      <CodeBlock language="json" filename="Response (200)">
+{`{
+  "success": true,
+  "message": "DSFA 7b3a1c9d gelöscht"
+}`}
+      </CodeBlock>
+
+      {/* ===================================================================== */}
+      {/* Statistiken */}
+      {/* ===================================================================== */}
+
+      <h2>GET /dsfa/stats</h2>
+      <p>Gibt Zähler nach Status und Risiko-Level zurück.</p>
+
+      <CodeBlock language="bash" filename="cURL">
+{`curl -X GET "https://api.breakpilot.io/sdk/v1/dsfa/stats?tenant_id=mein-tenant" \\
+  -H "Authorization: Bearer YOUR_API_KEY"`}
+      </CodeBlock>
+
+      <CodeBlock language="json" filename="Response (200)">
+{`{
+  "total": 5,
+  "by_status": {
+    "draft": 2,
+    "in-review": 1,
+    "approved": 2
+  },
+  "by_risk_level": {
+    "low": 1,
+    "medium": 2,
+    "high": 2
+  },
+  "draft_count": 2,
+  "in_review_count": 1,
+  "approved_count": 2,
+  "needs_update_count": 0
+}`}
+      </CodeBlock>
+
+      {/* ===================================================================== */}
+      {/* Audit-Log */}
+      {/* ===================================================================== */}
+
+      <h2>GET /dsfa/audit-log</h2>
+      <p>Gibt den vollständigen Audit-Trail aller DSFA-Aktionen zurück.</p>
+
+      <h4>Query-Parameter</h4>
+      <ParameterTable
+        parameters={[
+          { name: 'tenant_id', type: 'string', required: false, description: 'Tenant-ID' },
+          { name: 'limit', type: 'integer', required: false, description: 'Max. Einträge (Default: 50, Max: 500)' },
+          { name: 'offset', type: 'integer', required: false, description: 'Startposition' },
+        ]}
+      />
+
+      <CodeBlock language="json" filename="Response (200)">
+{`[
+  {
+    "id": "uuid",
+    "tenant_id": "mein-tenant",
+    "dsfa_id": "7b3a1c9d-...",
+    "action": "STATUS_CHANGE",
+    "changed_by": "system",
+    "old_values": { "status": "in-review" },
+    "new_values": { "status": "approved" },
+    "created_at": "2026-03-04T12:30:00"
+  }
+]`}
+      </CodeBlock>
+
+      <InfoBox type="info" title="Audit-Aktionen">
+        Folgende Aktionen werden protokolliert:{' '}
+        <code>CREATE</code>, <code>UPDATE</code>, <code>DELETE</code>, <code>STATUS_CHANGE</code>.
+      </InfoBox>
+
+      {/* ===================================================================== */}
+      {/* Alle Endpoints */}
+      {/* ===================================================================== */}
+
+      <h2>Alle Endpoints im Überblick</h2>
+
+      <ApiEndpoint method="GET"    path="/dsfa" description="Liste aller DSFAs (Filter: status, risk_level)" />
+      <ApiEndpoint method="POST"   path="/dsfa" description="Neue DSFA anlegen → 201" />
+      <ApiEndpoint method="GET"    path="/dsfa/stats" description="Statistiken nach Status und Risiko" />
+      <ApiEndpoint method="GET"    path="/dsfa/audit-log" description="Audit-Trail aller Aktionen" />
+      <ApiEndpoint method="GET"    path="/dsfa/{id}" description="Einzelne DSFA abrufen" />
+      <ApiEndpoint method="PUT"    path="/dsfa/{id}" description="DSFA aktualisieren (Partial Update)" />
+      <ApiEndpoint method="DELETE" path="/dsfa/{id}" description="DSFA löschen (Art. 17 DSGVO)" />
+      <ApiEndpoint method="PATCH"  path="/dsfa/{id}/status" description="Schnell-Statuswechsel" />
+    </DevPortalLayout>
+  )
+}
--- a/developer-portal/app/api/page.tsx
+++ b/developer-portal/app/api/page.tsx
@@ -142,6 +142,27 @@ export default function ApiReferencePage() {
        </Link>
      </p>

+      <h3>DSFA — Datenschutz-Folgenabschätzung</h3>
+      <p>
+        Verwalten Sie Datenschutz-Folgenabschätzungen gemäß Art. 35 DSGVO mit vollständigem
+        Audit-Trail, Status-Workflow und Risikobewertung.
+      </p>
+
+      <ApiEndpoint method="GET"    path="/dsfa" description="Liste aller DSFAs (Filter: status, risk_level)" />
+      <ApiEndpoint method="POST"   path="/dsfa" description="Neue DSFA anlegen → 201" />
+      <ApiEndpoint method="GET"    path="/dsfa/stats" description="Statistiken nach Status und Risiko" />
+      <ApiEndpoint method="GET"    path="/dsfa/audit-log" description="Audit-Trail aller Aktionen" />
+      <ApiEndpoint method="GET"    path="/dsfa/{id}" description="Einzelne DSFA abrufen" />
+      <ApiEndpoint method="PUT"    path="/dsfa/{id}" description="DSFA aktualisieren" />
+      <ApiEndpoint method="DELETE" path="/dsfa/{id}" description="DSFA löschen (Art. 17 DSGVO)" />
+      <ApiEndpoint method="PATCH"  path="/dsfa/{id}/status" description="Schnell-Statuswechsel" />
+
+      <p>
+        <Link href="/api/dsfa" className="text-blue-600 hover:underline">
+          → Vollständige DSFA API Dokumentation
+        </Link>
+      </p>
+
      <h2>Response Format</h2>
      <p>
        Alle Responses folgen einem einheitlichen Format: