breakpilot-compliance/docs-src/services/sdk-modules/iace.md

# IACE — Industrial AI Compliance Engine

**Modul:** CE-Risikobeurteilung fuer Maschinen mit Software / Firmware / KI
**Service:** `ai-compliance-sdk` (Go/Gin, Port 8093)
**Base-URL:** `GET|POST https://macmini:8093/sdk/v1/iace/...`

---

## Ueberblick

Das IACE-Modul unterstuetzt die vollstaendige CE-Konformitaetsbewertung von Maschinen und Systemen mit Software-, Firmware- und KI-Anteilen gemaess:

- **Maschinenverordnung (EU) 2023/1230** (loest Maschinenrichtlinie 2006/42/EG ab)
- **AI Act (EU) 2024/1689** (fuer KI-Systeme in Hochrisikoklassen)
- **CRA (Cyber Resilience Act)** (fuer vernetzte Produkte)
- **NIS2** (fuer kritische Infrastrukturen)

---

## Risikomodell (Dual-Modus)

IACE unterstuetzt zwei Betriebsmodi fuer die Risikobewertung:

### Legacy-Modus (S×E×P)

| Avoidance | Formel | Beschreibung |
|-----------|--------|--------------|
| `0` (Standard) | `R = S × E × P` | Backward-kompatibel, kein Avoidance-Faktor |

**Schwellwerte (Legacy):**

| Schwelle | Level |
|----------|-------|
| >= 75 | critical |
| >= 40 | high |
| >= 15 | medium |
| >= 5 | low |
| < 5 | negligible |

### ISO-Modus (S×F×P×A) — ab v2.0

Wenn `avoidance >= 1`, wird automatisch der ISO-Modus aktiviert:

| Formel | Beschreibung |
|--------|--------------|
| `R = S × F × P × A` | Direkte 4-Faktor-Multiplikation (KEIN /3.0) |

**Faktoren:**

| Faktor | Skala | Beschreibung |
|--------|-------|--------------|
| **S** (Severity) | 1–5 | Schwere des moeglichen Schadens |
| **F** (Frequency/Exposure) | 1–5 | Haeufigkeit/Dauer der Exposition |
| **P** (Probability) | 1–5 | Wahrscheinlichkeit des Eintretens |
| **A** (Avoidance) | 1–5 | Moeglichkeit der Vermeidung (1=leicht, 5=nicht vermeidbar) |

**Schwellwerte (ISO-Modus):**

| Schwelle | Level | Farbe |
|----------|-------|-------|
| > 300 | not_acceptable | Dunkelrot |
| 151–300 | very_high | Dunkelorange |
| 61–150 | high | Rot |
| 21–60 | medium | Gelb |
| 1–20 | low | Gruen |

### ALARP-Akzeptanz

- `residualRisk < 15` → akzeptabel
- `residualRisk < 40` + alle Minderungsschritte verifiziert + Begruendung → akzeptabel (ALARP)
- `residualRisk >= 40` → nicht akzeptabel (blockiert CE-Export)

### Schutzmassnahmen-Hierarchie (3-Stufen)

Die Risikobehandlung folgt einer verbindlichen Hierarchie:

| Stufe | Typ | Beschreibung |
|-------|-----|--------------|
| 1 | **Design** | Inhaerent sichere Konstruktion (z.B. Begrenzung von Kraeften, Geschwindigkeiten) |
| 2 | **Schutzeinrichtung** | Technische Schutzmassnahmen (z.B. Schutzgitter, Lichtvorhang, STO) |
| 3 | **Information** | Hinweise, Warnungen, Schulung (z.B. Sicherheitskennzeichnung, Betriebsanleitung) |

!!! warning "Hierarchie-Regel"
    Informationsmassnahmen (Stufe 3) duerfen **nicht** als alleinige Primaermassnahme akzeptiert werden, wenn Design- oder Schutzmassnahmen technisch moeglich sind. Das System prueft dies automatisch und gibt eine Warnung aus.

---

## Hazard-Library

Die eingebaute Hazard-Library enthaelt **150+ Eintraege** in 28 Kategorien. Alle Eintraege verwenden eigene Formulierungen und referenzieren Normen nur als Methodenquelle.

### KI/Cyber-Kategorien (12)

| Kategorie | Beschreibung |
|-----------|--------------|
| `false_classification` | Falsche KI-Klassifikation |
| `timing_error` | Echtzeit-Verletzungen |
| `data_poisoning` | Manipulierte Trainingsdaten |
| `model_drift` | Modell-Verschlechterung |
| `sensor_spoofing` | Sensor-Manipulation |
| `communication_failure` | Kommunikationsausfall |
| `unauthorized_access` | Unberechtigter Zugriff |
| `firmware_corruption` | Firmware-Beschaedigung |
| `safety_boundary_violation` | Sicherheitsgrenzwert-Verletzung |
| `mode_confusion` | Betriebsart-Verwechslung |
| `unintended_bias` | Unbeabsichtigte Diskriminierung |
| `update_failure` | Update-Fehler |

### Software/Hardware-Kategorien (12)

| Kategorie | Beschreibung |
|-----------|--------------|
| `software_fault` | Race Condition, Stack Overflow, Integer Overflow, Deadlock |
| `hmi_error` | Falsche Einheit, fehlender Alarm, Quittierung ohne Ursache |
| `mechanical_hazard` | Quetschen, Scheren, Einziehen, Herabfallende Teile, Instabilitaet |
| `electrical_hazard` | Elektrischer Schlag, Lichtbogen, Ueberstrom, Erdungsfehler |
| `thermal_hazard` | Ueberhitzung, Brandgefahr, Einfrieren, Waermestrahlung |
| `emc_hazard` | EMV-Stoerabstrahlung, ESD, HF-Stoerung |
| `configuration_error` | Falscher Safety-Param, Hard-coded Credentials, Debug-Mode |
| `safety_function_failure` | Not-Halt, STO, Schutztuer, Zweihand-Taster |
| `logging_audit_failure` | Fehlende Protokollierung, Log-Manipulation, Overflow |
| `integration_error` | Datentyp-Mismatch, Endianness, Buffer Overflow, Heartbeat |
| `environmental_hazard` | Temperatur, Feuchtigkeit, Vibration, Kontamination |
| `maintenance_hazard` | LOTO fehlt, Wartung bei laufender Maschine, Wiederanlauf |

### Physikalische Kategorien (4, ab v2.0)

| Kategorie | Beschreibung |
|-----------|--------------|
| `pneumatic_hydraulic` | Druckverlust, Druckfreisetzung, Schlauchpeitschen, unerwartete Bewegung |
| `noise_vibration` | Gehoerschaedigung, Hand-Arm-Vibration, Ganzkoerpervibration |
| `ergonomic` | Fehlbedienung, Zwangshaltung, Ueberforderung, Repetitive Belastung |
| `material_environmental` | Staub, Rauch, Daempfe, chemische Exposition, Leckagen |

### Erweiterte Felder (ab v2.0)

Jeder Hazard-Library-Eintrag enthaelt zusaetzlich:

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `default_exposure` | int (1–5) | Standard-Expositionswert |
| `default_avoidance` | int (1–5) | Standard-Vermeidbarkeit |
| `typical_causes` | string[] | Typische Ursachen |
| `typical_harm` | string | Typische Schadensfolge |
| `relevant_lifecycle_phases` | string[] | Relevante Lebensphasen |
| `recommended_measures_design` | string[] | Empfohlene Design-Massnahmen |
| `recommended_measures_technical` | string[] | Empfohlene technische Massnahmen |
| `recommended_measures_information` | string[] | Empfohlene Informationsmassnahmen |
| `suggested_evidence` | string[] | Vorgeschlagene Nachweisdokumente |
| `related_keywords` | string[] | Suchbegriffe |

**Filter:** `GET /sdk/v1/iace/hazard-library?category=mechanical_hazard&componentType=mechanical`

---

## Controls-Library

Die Controls-Library enthaelt **200 Eintraege** in 6 Domaenen:

### Domaenen-Uebersicht

| Domain | Eintraege | Beschreibung | ReductionType |
|--------|-----------|--------------|---------------|
| `REQ` | 30 | Safety Requirements — HARA, SIL/PL, Traceability | design |
| `ARCH` | 30 | Architektur & Design — Redundanz, Fail-Safe, Watchdog | design |
| `SWDEV` | 40 | Software-Entwicklung — MISRA-C, Statische Analyse, WCET | design/protective |
| `VER` | 30 | Verifikation & Validation — Fault Injection, HIL, SIL-Nachweis | design/protective |
| `CYBER` | 40 | OT-Cybersecurity — Netzwerksegmentierung, Signed Updates, SBOM | design/protective |
| `DOC` | 30 | Dokumentation & CE-Akte — Technical File, DoC, Betriebsanleitung | information |

**Filter:** `GET /sdk/v1/iace/controls-library?domain=CYBER&category=unauthorized_access`

---

## Schutzmassnahmen-Bibliothek (ab v2.0)

Zusaetzlich zur Controls-Library bietet IACE eine **Schutzmassnahmen-Bibliothek** mit **160 Eintraegen**, kategorisiert nach der 3-Stufen-Hierarchie:

| ReductionType | Eintraege | Beispiele |
|---------------|-----------|-----------|
| `design` | ~55 | Kraftbegrenzung, Formschluessige Sicherung, Redundante Sensorik |
| `protective` | ~60 | Schutzgitter, Lichtvorhang, STO, Druckbegrenzungsventil |
| `information` | ~45 | Sicherheitskennzeichnung, Betriebsanleitung, Schulungsprogramm |

**Filter:** `GET /sdk/v1/iace/protective-measures-library?category=mechanical_hazard`

---

## Lebensphasen (25)

Die Risikobeurteilung beruecksichtigt **25 Lebensphasen** einer Maschine:

| Phase | DE | EN |
|-------|----|----|
| `transport` | Transport | Transport |
| `storage` | Lagerung | Storage |
| `assembly` | Montage | Assembly |
| `installation` | Aufstellung | Installation |
| `commissioning` | Inbetriebnahme | Commissioning |
| `parameterization` | Parametrierung | Parameterization |
| `setup` | Einrichten | Setup |
| `normal_operation` | Normalbetrieb | Normal Operation |
| `auto_operation` | Automatikbetrieb | Automatic Operation |
| `manual_operation` | Handbetrieb | Manual Operation |
| `teach_mode` | Teach-Modus | Teach Mode |
| `production_start` | Produktionsstart | Production Start |
| `production_stop` | Produktionsstopp | Production Stop |
| `process_monitoring` | Prozessueberwachung | Process Monitoring |
| `cleaning` | Reinigung | Cleaning |
| `inspection` | Inspektion | Inspection |
| `maintenance` | Wartung | Maintenance |
| `calibration` | Kalibrierung | Calibration |
| `repair` | Reparatur | Repair |
| `software_update` | Software-Update | Software Update |
| `remote_maintenance` | Fernwartung | Remote Maintenance |
| `fault_clearing` | Stoerungsbeseitigung | Fault Clearing |
| `changeover` | Umruestung | Changeover |
| `decommissioning` | Ausserbetriebnahme | Decommissioning |
| `disposal` | Demontage/Entsorgung | Dismantling/Disposal |

**API:** `GET /sdk/v1/iace/lifecycle-phases`

---

## Betroffene Personen (20 Rollen)

Jede Gefaehrdung kann einer oder mehreren betroffenen Personengruppen zugeordnet werden:

| Rolle | DE | EN |
|-------|----|----|
| `operator` | Bediener | Operator |
| `setup_personnel` | Einrichter | Setup Personnel |
| `maintenance_tech` | Wartungstechniker | Maintenance Technician |
| `cleaning_staff` | Reinigungspersonal | Cleaning Staff |
| `supervisor` | Aufsichtsperson | Supervisor |
| `programmer` | Programmierer/Integrator | Programmer/Integrator |
| `trainee` | Auszubildender | Trainee |
| `temp_worker` | Leiharbeiter | Temporary Worker |
| `visitor` | Besucher | Visitor |
| `third_party` | Dritte/Passanten | Third Party/Bystander |
| `transport_personnel` | Transportpersonal | Transport Personnel |
| `commissioning_eng` | Inbetriebnahme-Ingenieur | Commissioning Engineer |
| `quality_inspector` | Qualitaetspruefer | Quality Inspector |
| `safety_officer` | Sicherheitsbeauftragter | Safety Officer |
| `electrical_tech` | Elektrofachkraft | Electrical Technician |
| `it_admin` | IT-Administrator | IT Administrator |
| `remote_operator` | Fernbediener | Remote Operator |
| `emergency_responder` | Ersthelfer/Rettungskraft | Emergency Responder |
| `contractor` | Fremdfirma-Mitarbeiter | Contractor |
| `disabled_person` | Person mit Einschraenkung | Person with Disability |

**API:** `GET /sdk/v1/iace/roles`

---

## Nachweistypen (50 in 7 Kategorien)

Fuer die Verifikation stehen **50 Nachweistypen** zur Auswahl:

| Kategorie | Beispiele |
|-----------|-----------|
| **Konstruktion** | Risikobeurteilung, Sicherheitskonzept, Schaltplan, Pneumatikplan |
| **Berechnung** | Festigkeitsberechnung, Thermische Simulation, FMEA |
| **Pruefung** | Funktionspruefung, Druckpruefung, EMV-Messung, Isolationspruefung |
| **Zertifizierung** | Baumuster-Pruefbescheinigung, SIL/PL-Zertifikat, CE-Konformitaetserklaerung |
| **Software** | Code-Review-Protokoll, Statische Analyse, Unit-Test-Report, Penetrationstest |
| **Betrieb** | Betriebsanleitung, Wartungsplan, Schulungsnachweis, Notfallplan |
| **Ueberwachung** | Inspektionsbericht, Kalibrierprotokoll, Audit-Report, Maengelprotokoll |

**API:** `GET /sdk/v1/iace/evidence-types?category=pruefung`

---

## Verifikationsmethoden (10)

| Methode | Beschreibung |
|---------|--------------|
| `design_review` | Systematische Pruefung von Konstruktionsunterlagen |
| `calculation` | Rechnerischer Nachweis (Festigkeit, Thermik, SIL) |
| `test_report` | Pruefbericht aus Labor- oder Feldversuchen |
| `validation` | Nachweis der Gebrauchstauglichkeit unter realen Bedingungen |
| `electrical_test` | Isolationsmessung, Schutzleiter, Spannungspruefung |
| `software_test` | Unit-Test, Integrationstest, statische Analyse |
| `penetration_test` | Sicherheitstest der IT/OT-Infrastruktur |
| `acceptance_protocol` | Formales Abnahmeprotokoll mit Checkliste |
| `user_test` | Anwendertest unter realistischen Einsatzbedingungen |
| `documentation_release` | Formale Freigabe von Dokumenten und Anleitungen |

---

## API-Endpunkte (30+)

### Libraries & Referenzdaten (projektunabhaengig)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| GET | `/sdk/v1/iace/hazard-library` | Alle Gefaehrdungen (150+) |
| GET | `/sdk/v1/iace/controls-library` | Alle Controls (200) |
| GET | `/sdk/v1/iace/protective-measures-library` | Schutzmassnahmen-Bibliothek (160) |
| GET | `/sdk/v1/iace/component-library` | Komponenten-Bibliothek (C001-C120) |
| GET | `/sdk/v1/iace/energy-sources` | Energiequellen (EN01-EN20) |
| GET | `/sdk/v1/iace/hazard-patterns` | Gefaehrdungs-Patterns (102) |
| GET | `/sdk/v1/iace/tags` | Tag-Taxonomie |
| GET | `/sdk/v1/iace/lifecycle-phases` | 25 Lebensphasen (DE/EN) |
| GET | `/sdk/v1/iace/roles` | 20 betroffene Personengruppen (DE/EN) |
| GET | `/sdk/v1/iace/evidence-types` | 50 Nachweistypen in 7 Kategorien |
| POST | `/sdk/v1/iace/library-search` | RAG-Bibliothekssuche |

### Projektmanagement

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects` | Neues Projekt erstellen |
| GET | `/sdk/v1/iace/projects` | Alle Projekte auflisten |
| GET | `/sdk/v1/iace/projects/:id` | Projekt-Details |
| PUT | `/sdk/v1/iace/projects/:id` | Projekt aktualisieren |
| DELETE | `/sdk/v1/iace/projects/:id` | Projekt archivieren |

### Onboarding & Profil-Import

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/init-from-profile` | Projekt aus Company-Profile initialisieren |
| POST | `/sdk/v1/iace/projects/:id/completeness-check` | 22-Gates-Pruefung |

Der `init-from-profile` Endpoint uebernimmt Daten aus dem Company-Profile und Compliance-Scope:

- **company_profile** → Hersteller-Name, Kontaktdaten
- **compliance_scope** → Maschinenname, Typ, Zweckbeschreibung, Software/Firmware/KI-Flags
- Erstellt automatisch initiale Komponenten (Software, Firmware, KI-Modell, Netzwerk)
- Triggert initiale regulatorische Klassifizierungen fuer anwendbare Verordnungen

### Komponenten

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/components` | Komponente hinzufuegen |
| GET | `/sdk/v1/iace/projects/:id/components` | Alle Komponenten |
| PUT | `/sdk/v1/iace/projects/:id/components/:cid` | Komponente aktualisieren |
| DELETE | `/sdk/v1/iace/projects/:id/components/:cid` | Komponente loeschen |

### Klassifizierung

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/classify` | Alle Regulierungen klassifizieren |
| GET | `/sdk/v1/iace/projects/:id/classifications` | Klassifizierungen abrufen |
| POST | `/sdk/v1/iace/projects/:id/classify/:regulation` | Einzelne Regulierung |

### Gefaehrdungen & Risikobewertung

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/hazards` | Gefaehrdung anlegen |
| GET | `/sdk/v1/iace/projects/:id/hazards` | Alle Gefaehrdungen |
| PUT | `/sdk/v1/iace/projects/:id/hazards/:hid` | Gefaehrdung aktualisieren |
| POST | `/sdk/v1/iace/projects/:id/hazards/suggest` | KI-gestuetzte Vorschlaege |
| POST | `/sdk/v1/iace/projects/:id/hazards/:hid/assess` | Risikobewertung (SEPA) |
| POST | `/sdk/v1/iace/projects/:id/hazards/:hid/reassess` | Neubewertung nach Minderung |
| GET | `/sdk/v1/iace/projects/:id/risk-summary` | Aggregierte Risikouebersicht |
| POST | `/sdk/v1/iace/projects/:id/validate-mitigation-hierarchy` | Hierarchie-Pruefung (3-Stufen) |

### Minderung & Verifikation

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/hazards/:hid/mitigations` | Massnahme anlegen |
| GET | `/sdk/v1/iace/projects/:id/hazards/:hid/mitigations` | Alle Massnahmen |
| PUT | `/sdk/v1/iace/projects/:id/hazards/:hid/mitigations/:mid` | Massnahme aktualisieren |
| POST | `/sdk/v1/iace/projects/:id/verification-plans` | Verifikationsplan erstellen |
| GET | `/sdk/v1/iace/projects/:id/verification-plans` | Alle Plaene |
| PUT | `/sdk/v1/iace/projects/:id/verification-plans/:vid` | Plan aktualisieren |

### CE-Technische Akte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| GET | `/sdk/v1/iace/projects/:id/tech-file` | Technische Akte abrufen |
| POST | `/sdk/v1/iace/projects/:id/tech-file/generate` | Alle Sektionen generieren (LLM-basiert) |
| POST | `/sdk/v1/iace/projects/:id/tech-file/:section/generate` | Einzelne Sektion (re-)generieren (LLM) |
| PUT | `/sdk/v1/iace/projects/:id/tech-file/:section` | Abschnitt manuell aktualisieren |
| POST | `/sdk/v1/iace/projects/:id/tech-file/:section/approve` | Abschnitt freigeben |
| POST | `/sdk/v1/iace/projects/:id/tech-file/:section/enrich` | Abschnitt mit RAG-Kontext anreichern |
| GET | `/sdk/v1/iace/projects/:id/tech-file/export?format=` | Akte exportieren (pdf/xlsx/docx/md/json) |

#### Export-Formate

| Format | MIME-Type | Inhalt |
|--------|-----------|--------|
| `pdf` | application/pdf | Vollstaendige CE-Akte mit Deckblatt, Inhaltsverzeichnis, Risikomatrix, Gefaehrdungsprotokoll |
| `xlsx` | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | 5 Worksheets: Uebersicht, Gefaehrdungsprotokoll, Massnahmen, Risikomatrix, Sektionen |
| `docx` | application/vnd.openxmlformats-officedocument.wordprocessingml.document | Word-Dokument mit allen Sektionen als formatierte Absaetze |
| `md` | text/markdown | Markdown-Dokument mit Projekt-Metadaten und allen Sektionen |
| `json` | application/json | JSON-Export mit Projekt, Sektionen, Klassifizierungen, Risikouebersicht |

#### LLM-basierte Sektionsgenerierung (19 Sektionstypen)

Die Tech-File-Generierung nutzt LLM (Ollama/Anthropic) mit RAG-Kontext aus dem CE-Corpus:

| Sektion | Beschreibung |
|---------|--------------|
| `general_description` | Allgemeine Maschinenbeschreibung |
| `risk_assessment_report` | Zusammenfassung der Risikobeurteilung |
| `hazard_log_combined` | Tabellarisches Gefaehrdungsprotokoll |
| `essential_requirements` | Grundlegende Anforderungen (MVO Anhang III) |
| `design_specifications` | Konstruktionsdaten und Zeichnungen |
| `test_reports` | Pruefberichte und Verifikationsergebnisse |
| `standards_applied` | Angewandte harmonisierte Normen |
| `declaration_of_conformity` | EU-Konformitaetserklaerung (MVO Anhang IV) |
| `component_list` | Komponentenverzeichnis |
| `classification_report` | Regulatorische Klassifikation |
| `mitigation_report` | Massnahmen nach 3-Stufen-Hierarchie |
| `verification_report` | Verifikationsplan und Ergebnisse |
| `evidence_index` | Nachweisdokumenten-Index |
| `instructions_for_use` | Sicherheitshinweise / Betriebsanleitung |
| `monitoring_plan` | Post-Market Surveillance Plan |
| `ai_intended_purpose` | KI: Bestimmungsgemaesser Zweck |
| `ai_model_description` | KI: Modellbeschreibung und Trainingsdaten |
| `ai_risk_management` | KI: Risikomanagementsystem |
| `ai_human_oversight` | KI: Menschliche Aufsicht |

#### TipTap Rich-Text-Editor (Frontend)

Die Tech-File-Sektionen werden im Frontend mit einem TipTap WYSIWYG-Editor bearbeitet (`components/sdk/iace/TechFileEditor.tsx`):

| Feature | Beschreibung |
|---------|--------------|
| Toolbar | Bold, Italic, Headings (H2-H4), Bullet/Ordered Lists, Tabelle, Blockquote, Code, Undo/Redo |
| Auto-Save | Debounced (3 Sekunden nach letzter Aenderung), ruft `PUT /tech-file/:section` auf |
| Read-Only | Fuer freigegebene Sektionen (`status: approved`) |
| Markdown-Import | LLM-generierter Markdown-Content wird automatisch in TipTap-Nodes konvertiert |
| HTML-Speicherung | `editor.getHTML()` → Backend speichert HTML in `iace_tech_file_sections.content` |

**Pakete (alle MIT-Lizenz):**
`@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extension-table`, `@tiptap/extension-table-row`,
`@tiptap/extension-table-header`, `@tiptap/extension-table-cell`, `@tiptap/extension-image`, `@tiptap/pm`

**Workflow:**
1. Sektion generieren → LLM liefert Markdown
2. TipTap konvertiert Markdown → ProseMirror-Nodes
3. Benutzer bearbeitet im WYSIWYG-Editor
4. Auto-Save speichert HTML im Backend
5. Export rendert HTML → PDF/DOCX/Excel/Markdown

### Post-Market Monitoring

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| POST | `/sdk/v1/iace/projects/:id/monitoring-events` | Ereignis protokollieren |
| GET | `/sdk/v1/iace/projects/:id/monitoring-events` | Alle Ereignisse |

### Audit-Trail

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| GET | `/sdk/v1/iace/projects/:id/audit-trail` | Unveraenderliches Audit-Log |

---

## Completeness Gates (22)

Das Modul prueft 22 Vollstaendigkeitstore (20 Required, 2 Recommended) vor dem CE-Export:

### Onboarding (G01-G09)

| Gate | Label | Pflicht |
|------|-------|---------|
| G01 | Machine identity set | ✅ Required |
| G02 | Intended use described | ✅ Required |
| G03 | Operating limits defined | ✅ Required |
| G04 | Foreseeable misuse documented | ✅ Required |
| G05 | Component tree exists | ✅ Required |
| G06 | AI classification done (if applicable) | ✅ Required |
| G07 | Safety relevance marked | ✅ Required |
| G08 | Manufacturer info present | ✅ Required |
| G09 | Pattern matching performed | Recommended |

### Klassifizierung (G10-G13)

| Gate | Label | Pflicht |
|------|-------|---------|
| G10 | AI Act classification complete | ✅ Required |
| G11 | Machinery Regulation check done | ✅ Required |
| G12 | NIS2 check done | ✅ Required |
| G13 | CRA check done | ✅ Required |

### Gefaehrdungen & Risiko (G20-G24)

| Gate | Label | Pflicht |
|------|-------|---------|
| G20 | Hazards identified | ✅ Required |
| G21 | All hazards assessed | ✅ Required |
| G22 | Critical/High risks mitigated | ✅ Required |
| G23 | **Mitigations verified** | ✅ Required |
| G24 | Residual risk accepted | ✅ Required |

!!! warning "G23 — Strenge Verifikationspflicht"
    Alle Mitigations muessen den Status `verified` oder `rejected` haben. Mitigations im Status `planned` oder `implemented` blockieren den Export. Dies stellt sicher, dass keine Massnahme unueberprueft bleibt.

### Evidence & Tech File (G30, G40-G42)

| Gate | Label | Pflicht |
|------|-------|---------|
| G30 | Test evidence linked | Recommended |
| G40 | Risk assessment report generated | ✅ Required |
| G41 | Hazard log generated | ✅ Required |
| G42 | AI documents present (if applicable) | ✅ Required |

**Completeness Score:** `(passed_required/total_required)*80 + (passed_recommended/total_recommended)*15 + (passed_optional/total_optional)*5`

**CanExport** ist nur `true`, wenn alle Required-Gates bestanden sind.

---

## CE RAG-Corpus

Die folgenden 15 Dokumente werden via `scripts/ingest-ce-corpus.sh` ingestiert:

### Collection: bp_compliance_ce

| # | Dokument | Kategorie | Lizenz |
|---|----------|-----------|--------|
| 1 | Machinery Regulation (EU) 2023/1230 | ce_machinery | EU Public Law |
| 2 | Machinery Directive 2006/42/EC | ce_machinery | EU Public Law |
| 3 | Low Voltage Directive 2014/35/EU | ce_electrical | EU Public Law |
| 4 | EMC Directive 2014/30/EU | ce_emc | EU Public Law |
| 5 | Radio Equipment Directive 2014/53/EU | ce_radio | EU Public Law |
| 6 | AI Act (EU) 2024/1689 | ce_ai | EU Public Law |
| 7 | EC Guide to the Machinery Directive | ce_machinery_guidance | EU Public |
| 8 | NIST SP 800-218 (SSDF) | ce_software_safety | US Gov Public Domain |
| 9 | NIST AI RMF 1.0 | ce_ai_safety | US Gov Public Domain |
| 10 | ENISA Guidelines for Securing the IoT | ce_ot_cybersecurity | EU Public |
| 12 | NASA Software Safety Guidebook | ce_software_safety | US Gov Public Domain |
| 13 | OWASP Top 10 (2021) | ce_software_security | CC BY-SA 4.0 |
| 15 | MITRE CWE Top 25 (2023) | ce_software_weaknesses | MIT |

### Collection: bp_compliance_datenschutz

| # | Dokument | Kategorie | Lizenz |
|---|----------|-----------|--------|
| 11 | ENISA Securing Machine Learning Algorithms | ai_cybersecurity | EU Public |
| 14 | OECD AI Principles | ai_governance | OECD Public |

### Ingest-Script ausfuehren

```bash
# Auf dem Mac Mini:
bash ~/Projekte/breakpilot-compliance/scripts/ingest-ce-corpus.sh

# Nur bestimmte Phase:
bash .../ingest-ce-corpus.sh --only ce
bash .../ingest-ce-corpus.sh --only datenschutz
bash .../ingest-ce-corpus.sh --skip-download --only verify

# Ergebnis pruefen:
curl -sk https://macmini:8093/sdk/v1/iace/hazard-library | python3 -c "import sys,json; print(json.load(sys.stdin)['total'])"
curl -sk https://macmini:8093/sdk/v1/iace/controls-library | python3 -c "import sys,json; print(json.load(sys.stdin)['total'])"
```

---

## Beispiel: Risikobewertung

### Legacy-Modus (A=0)

```bash
curl -sk -X POST https://macmini:8093/sdk/v1/iace/projects/{id}/hazards/{hid}/assess \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: <tenant-uuid>" \
  -d '{"severity": 5, "exposure": 3, "probability": 3, "avoidance": 0}'
```

Ergebnis: `R = 5 × 3 × 3 = 45` → **high**

### ISO-Modus (A >= 1)

```bash
curl -sk -X POST https://macmini:8093/sdk/v1/iace/projects/{id}/hazards/{hid}/assess \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: <tenant-uuid>" \
  -d '{
    "severity": 5,
    "exposure": 3,
    "probability": 3,
    "avoidance": 4,
    "control_maturity": 2,
    "control_coverage": 0.6,
    "test_evidence_strength": 0.5,
    "acceptance_justification": "ALARP: STO implementiert und verifiziert"
  }'
```

Ergebnis: `R = 5 × 3 × 3 × 4 = 180` → **very_high** (ISO-Schwellwerte)

---

## Beispiel: Controls-Library abfragen

```bash
# Alle CYBER-Controls
curl -sk "https://macmini:8093/sdk/v1/iace/controls-library?domain=CYBER" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'{d[\"total\"]} Controls')"

# Controls fuer software_fault-Kategorie
curl -sk "https://macmini:8093/sdk/v1/iace/controls-library?category=software_fault" \
  | python3 -m json.tool | head -40
```

---

## Hazard-Matching-Engine

Die Pattern Engine automatisiert die Ableitung von Gefaehrdungen, Schutzmassnahmen und Nachweisen aus der Maschinenkonfiguration.

### Komponentenbibliothek (120 Eintraege)

```bash
# Alle Komponenten abrufen
curl -sk "https://macmini:8093/sdk/v1/iace/component-library" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(f'{d[\"total\"]} Komponenten in {len(set(c[\"category\"] for c in d[\"components\"]))} Kategorien')"

# Nach Kategorie filtern
curl -sk "https://macmini:8093/sdk/v1/iace/component-library?category=mechanical"
```

| Kategorie | IDs | Anzahl | Beispiele |
|-----------|-----|--------|-----------|
| mechanical | C001-C020 | 20 | Roboterarm, Greifer, Foerderband |
| structural | C021-C030 | 10 | Maschinenrahmen, Schutzgehaeuse |
| drive | C031-C040 | 10 | Elektromotor, Servomotor |
| hydraulic | C041-C050 | 10 | Hydraulikpumpe, -zylinder |
| pneumatic | C051-C060 | 10 | Pneumatikzylinder, Kompressor |
| electrical | C061-C070 | 10 | Schaltschrank, Stromversorgung |
| control | C071-C080 | 10 | SPS, Sicherheits-SPS, HMI |
| sensor | C081-C090 | 10 | Positionssensor, Kamerasystem |
| actuator | C091-C100 | 10 | Magnetventil, Linearantrieb |
| safety | C101-C110 | 10 | Not-Halt, Lichtgitter |
| it_network | C111-C120 | 10 | Switch, Router, Firewall |

### Energiequellen (20 Eintraege)

```bash
curl -sk "https://macmini:8093/sdk/v1/iace/energy-sources"
```

### Tag-Taxonomie (~85 Tags)

| Domaene | Anzahl | Beispiele |
|---------|--------|-----------|
| component | ~30 | moving_part, rotating_part, high_voltage, networked, has_ai |
| energy | ~15 | kinetic, rotational, electrical_energy, hydraulic_pressure |
| hazard | ~20 | crush_risk, shear_risk, electric_shock_risk, cyber_risk |
| measure | ~10 | guard_measure, interlock_measure, software_safety_measure |
| evidence | ~10 | design_evidence, test_evidence, cyber_evidence |

```bash
# Alle Tags einer Domaene
curl -sk "https://macmini:8093/sdk/v1/iace/tags?domain=component"
```

### Hazard Patterns (102 Regeln: 44 builtin + 58 extended)

Jedes Pattern definiert required_component_tags (AND), required_energy_tags (AND) und excluded_component_tags (NOT). Die Engine prueft alle Patterns gegen die aufgeloesten Tags der Projektkomponenten.

**Builtin (HP001-HP044):** Abstrakte Tag-basierte Patterns fuer 9 Domaenen (mechanisch, elektrisch, thermisch, hydraulik/pneumatik, laerm, ergonomie, software, cyber, KI).

**Extended (HP045-HP102):** 58 zusaetzliche Patterns aus der Rule Library (R051-R1550). Diese ergaenzen die Builtin-Patterns um komponentenspezifische Regeln mit Lebensphase-Einschraenkung.

```bash
# Patterns auflisten
curl -sk "https://macmini:8093/sdk/v1/iace/hazard-patterns" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(f'{d[\"total\"]} Patterns')"
```

### Pattern-Matching Workflow

```bash
# 1. Pattern-Matching ausfuehren
curl -sk -X POST "https://macmini:8093/sdk/v1/iace/projects/{id}/match-patterns" \
  -H "Content-Type: application/json" \
  -d '{"component_library_ids": ["C001","C071"], "energy_source_ids": ["EN01","EN07"]}'

# 2. Ergebnisse uebernehmen
curl -sk -X POST "https://macmini:8093/sdk/v1/iace/projects/{id}/apply-patterns" \
  -H "Content-Type: application/json" \
  -d '{"accepted_hazards": [...], "accepted_measures": [...], "accepted_evidence": [...]}'

# 3. Pro-Hazard Massnahmen vorschlagen
curl -sk -X POST "https://macmini:8093/sdk/v1/iace/projects/{id}/hazards/{hid}/suggest-measures"

# 4. Pro-Massnahme Nachweise vorschlagen
curl -sk -X POST "https://macmini:8093/sdk/v1/iace/projects/{id}/mitigations/{mid}/suggest-evidence"
```

### RAG-Anreicherung (Phase 6)

IACE-Bibliotheken (Hazards, Komponenten, Energiequellen, Massnahmen, Nachweise) sind als RAG-Corpus in Qdrant verfuegbar (`bp_iace_libraries`).

```bash
# Semantische Suche in der IACE-Bibliothek
curl -sk -X POST "https://macmini:8093/sdk/v1/iace/library-search" \
  -H "Content-Type: application/json" \
  -d '{"query": "Quetschgefahr Roboterarm", "top_k": 5}'

# Tech-File-Abschnitt mit RAG-Kontext anreichern
curl -sk -X POST "https://macmini:8093/sdk/v1/iace/projects/{id}/tech-file/risk_assessment_report/enrich"
```

**Ingestion:**
```bash
# IACE-Bibliotheken in Qdrant ingestieren (auf Mac Mini)
bash ~/Projekte/breakpilot-compliance/scripts/ingest-iace-libraries.sh
```

---

## Datenbank-Tabellen

| Tabelle | Beschreibung |
|---------|--------------|
| `iace_projects` | CE-Projekte |
| `iace_components` | System-Komponenten |
| `iace_regulatory_classifications` | Regulierungsklassifizierungen |
| `iace_hazard_library` | Benutzerdefinierte Hazard-Templates |
| `iace_hazards` | Projektspezifische Gefaehrdungen (inkl. lifecycle_phase, affected_person, trigger_event) |
| `iace_risk_assessments` | Risikobewertungen (Legacy S×E×P + ISO S×F×P×A) |
| `iace_mitigations` | Minderungsmassnahmen |
| `iace_verification_plans` | Verifikationsplaene |
| `iace_evidence` | Nachweise (Uploads) |
| `iace_tech_file_sections` | CE-Akte-Abschnitte |
| `iace_monitoring_events` | Post-Market-Ereignisse |
| `iace_audit_trail` | Unveraenderbares Audit-Log |
| `iace_lifecycle_phases` | 25 Lebensphasen (DE/EN) |
| `iace_roles` | 20 betroffene Personengruppen (DE/EN) |
| `iace_evidence_types` | 50 Nachweistypen in 7 Kategorien |
| `iace_component_library` | 120 Maschinenkomponenten (C001-C120) |
| `iace_energy_sources` | 20 Energiequellen (EN01-EN20) |
| `iace_pattern_results` | Audit-Trail fuer Pattern-Matching |

---

## Rechtlicher Hinweis — Normenreferenz

!!! warning "Urheberrecht bei Normen"
    Saemtliche Inhalte des IACE-Moduls (Gefaehrdungsbibliothek, Schutzmassnahmen-Katalog,
    Risikomodell, Lebensphasen, Rollen) sind **eigenstaendig formuliert**. Normen wie
    ISO 12100, DIN EN 62443, IEC 61508 etc. werden ausschliesslich als **Methodenreferenz**
    in den Metadaten gefuehrt (z.B. `"methodology_reference": "ISO 12100"`).

    Es wird **kein normativer Text** reproduziert — keine Tabellen, Risikoklassifikationen,
    Prozesstexte oder Checklisten aus Normen. Dies ist konform mit §51 UrhG (Zitatrecht).

    Fuer die Anwendung der vollstaendigen Normen muss die jeweilige Norm separat
    ueber DIN Media (beuth.de) oder ISO erworben werden.

**Beispiel fuer konforme Normenreferenz in generierten Dokumenten:**

> Die Risikobeurteilung wurde unter Beruecksichtigung allgemein anerkannter Methoden
> der Maschinensicherheit durchgefuehrt (u.a. angelehnt an ISO 12100).