breakpilot-compliance/developer-portal/app/api/dsfa/page.tsx

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 (inkl. ai_use_case_modules)" />
      <ApiEndpoint method="DELETE" path="/dsfa/{id}" description="DSFA löschen (Art. 17 DSGVO)" />
      <ApiEndpoint method="PATCH"  path="/dsfa/{id}/status" description="Schnell-Statuswechsel" />

      {/* Section 8: AI Use Case Modules */}
      <h2>Section 8: KI-Anwendungsfälle</h2>
      <p>
        Section 8 ist ein optionaler modularer Anhang zur DSFA für KI-spezifische Verarbeitungen.
        Die Module werden im Feld <code>ai_use_case_modules</code> (JSONB-Array) gespeichert
        und über den normalen <code>PUT /dsfa/{'{id}'}</code> Endpoint aktualisiert.
      </p>

      <InfoBox type="info" title="KI-Modul-Typen">
        Unterstützte Typen: <code>chatbot_nlp</code>, <code>recommendation</code>,{' '}
        <code>adm_scoring</code>, <code>video_image</code>, <code>biometrics</code>,{' '}
        <code>iot_sensors</code>, <code>generative_ai</code>, <code>custom</code>
      </InfoBox>

      <h3>KI-Modul hinzufügen</h3>
      <CodeBlock language="bash">{`# KI-Modul zu bestehender DSFA hinzufügen
curl -sk -X PUT 'https://macmini:8002/api/v1/dsfa/{id}' \\
  -H 'Content-Type: application/json' \\
  -H 'X-Tenant-ID: default' \\
  -d '{
    "ai_use_case_modules": [
      {
        "id": "uuid-generated",
        "use_case_type": "generative_ai",
        "name": "GPT-Assistent Kundenservice",
        "model_description": "LLM-basierter Chatbot mit RAG für FAQ-Beantwortung",
        "model_type": "GPT-4o",
        "provider": "OpenAI",
        "third_country_transfer": true,
        "provider_country": "USA",
        "input_data_categories": ["Anfragetexte", "Kundennummer"],
        "output_data_categories": ["Antworttext"],
        "involves_special_categories": false,
        "data_subjects": ["Kunden"],
        "processing_purpose": "Automatisierte Beantwortung von Kundenanfragen",
        "legal_basis": "Art. 6 Abs. 1 lit. b DSGVO (Vertragserfüllung)",
        "art22_assessment": { "applies": false, "safeguards": [] },
        "risk_criteria": [
          { "id": "adm_profiling", "applies": false, "severity": "high" }
        ],
        "ai_act_risk_class": "limited",
        "ai_act_justification": "Chatbot mit Transparenzpflicht nach Art. 52 AI Act",
        "risks": [],
        "mitigations": [],
        "privacy_by_design_measures": [
          { "category": "data_minimisation", "description": "Nur notwendige Daten", "implemented": true }
        ],
        "review_triggers": [
          { "type": "model_update", "description": "Bei Modell-Wechsel", "monitoring_interval": "monatlich" }
        ]
      }
    ]
  }'`}</CodeBlock>

      <h3>TypeScript-Typen</h3>
      <CodeBlock language="typescript">{`import type { AIUseCaseModule, AIUseCaseType, AIActRiskClass } from '@breakpilot/compliance-sdk'

// Modul erstellen
const module: AIUseCaseModule = {
  id: crypto.randomUUID(),
  use_case_type: 'generative_ai',
  name: 'Mein KI-System',
  model_description: 'Beschreibung...',
  third_country_transfer: false,
  input_data_categories: ['Nutzertexte'],
  output_data_categories: ['Antwort'],
  involves_special_categories: false,
  data_subjects: ['Endnutzer'],
  processing_purpose: 'Kundensupport',
  legal_basis: 'Art. 6 Abs. 1 lit. b DSGVO',
  art22_assessment: { applies: false, safeguards: [] },
  risk_criteria: [],
  ai_act_risk_class: 'limited',
  wp248_criteria_met: ['K4', 'K8'],
  risks: [],
  mitigations: [],
  privacy_by_design_measures: [],
  review_triggers: [],
  created_at: new Date().toISOString(),
  updated_at: new Date().toISOString(),
}`}</CodeBlock>
    </DevPortalLayout>
  )
}