feat(iace): integrate ISO 12100 machine risk model with 4-factor assessment
All checks were successful
CI/CD / go-lint (push) Has been skipped
CI/CD / python-lint (push) Has been skipped
CI/CD / nodejs-lint (push) Has been skipped
CI/CD / test-go-ai-compliance (push) Successful in 36s
CI/CD / test-python-backend-compliance (push) Successful in 36s
CI/CD / test-python-document-crawler (push) Successful in 22s
CI/CD / test-python-dsms-gateway (push) Successful in 18s
CI/CD / validate-canonical-controls (push) Successful in 12s
CI/CD / Deploy (push) Successful in 2s

Add dual-mode risk engine: legacy S×E×P (avoidance=0) and ISO mode S×F×P×A
(avoidance>=1) with new thresholds (low/medium/high/very_high/not_acceptable).

- 150+ hazard library entries across 28 categories incl. physical hazards
  (mechanical, electrical, thermal, pneumatic/hydraulic, noise/vibration,
  ergonomic, material/environmental)
- 160-entry protective measures library with 3-step hierarchy validation
  (design → protective → information)
- 25 lifecycle phases, 20 affected person roles, 50 evidence types
- 10 verification methods (expanded from 7)
- New API endpoints: lifecycle-phases, roles, evidence-types,
  protective-measures-library, validate-mitigation-hierarchy
- DB migrations 018+019 for extended schema
- Frontend: 4-slider risk assessment, hierarchy warnings, measures library modal
- MkDocs wiki updated with ISO mode docs and legal notice (no norm text)

All content uses original wording — norms referenced as methodology only.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
2026-03-15 23:13:41 +01:00
parent c8fd9cc780
commit c7651796c9
15 changed files with 3708 additions and 479 deletions

View File

@@ -17,84 +17,139 @@ Das IACE-Modul unterstuetzt die vollstaendige CE-Konformitaetsbewertung von Masc
---
## SEPA Risikomodell
## Risikomodell (Dual-Modus)
IACE verwendet das **SEPA-Modell** (Severity × Exposure × Probability × Avoidance):
IACE unterstuetzt zwei Betriebsmodi fuer die Risikobewertung:
### Formel
### Legacy-Modus (S×E×P)
| Avoidance | Formel | Beschreibung |
|-----------|--------|--------------|
| `0` (Standard) | `S × E × P` | Backward-kompatibel, kein Avoidance-Faktor |
| `15` | `S × E × P × (A / 3.0)` | Avoidance-faktor aktiv (3 = neutral) |
| `0` (Standard) | `R = S × E × P` | Backward-kompatibel, kein Avoidance-Faktor |
### Avoidance-Skala
| Wert | Bedeutung |
|------|-----------|
| 1 | Leicht vermeidbar (klare Warnung, langsame Bewegung) |
| 2 | Eher vermeidbar |
| 3 | Neutral (kein Einfluss) |
| 4 | Schwer vermeidbar |
| 5 | Nicht vermeidbar (sofortige Auswirkung) |
### Schwellwerte (Residualrisiko)
**Schwellwerte (Legacy):**
| Schwelle | Level |
|----------|-------|
| 75 | critical |
| 40 | high |
| 15 | medium |
| 5 | low |
| >= 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) | 15 | Schwere des moeglichen Schadens |
| **F** (Frequency/Exposure) | 15 | Haeufigkeit/Dauer der Exposition |
| **P** (Probability) | 15 | Wahrscheinlichkeit des Eintretens |
| **A** (Avoidance) | 15 | Moeglichkeit der Vermeidung (1=leicht, 5=nicht vermeidbar) |
**Schwellwerte (ISO-Modus):**
| Schwelle | Level | Farbe |
|----------|-------|-------|
| > 300 | not_acceptable | Dunkelrot |
| 151300 | very_high | Dunkelorange |
| 61150 | high | Rot |
| 2160 | medium | Gelb |
| 120 | low | Gruen |
### ALARP-Akzeptanz
- `residualRisk < 15` → akzeptabel
- `residualRisk < 40` + alle Minderungsschritte verifiziert + Begruendung → akzeptabel (ALARP)
- `residualRisk 40` → nicht akzeptabel (blockiert CE-Export)
- `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 **~140 Eintraege** in 24 Kategorien:
Die eingebaute Hazard-Library enthaelt **150+ Eintraege** in 28 Kategorien. Alle Eintraege verwenden eigene Formulierungen und referenzieren Normen nur als Methodenquelle.
### Urspruengliche Kategorien (12)
### KI/Cyber-Kategorien (12)
| Kategorie | Eintraege | Beschreibung |
|-----------|-----------|--------------|
| `false_classification` | 4 | Falsche KI-Klassifikation |
| `timing_error` | 3 | Echtzeit-Verletzungen |
| `data_poisoning` | 2 | Manipulierte Trainingsdaten |
| `model_drift` | 3 | Modell-Verschlechterung |
| `sensor_spoofing` | 3 | Sensor-Manipulation |
| `communication_failure` | 3 | Kommunikationsausfall |
| `unauthorized_access` | 4 | Unberechtigter Zugriff |
| `firmware_corruption` | 3 | Firmware-Beschaedigung |
| `safety_boundary_violation` | 4 | Sicherheitsgrenzwert-Verletzung |
| `mode_confusion` | 3 | Betriebsart-Verwechslung |
| `unintended_bias` | 2 | Unbeabsichtigte Diskriminierung |
| `update_failure` | 3 | Update-Fehler |
| 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 |
### Neue Kategorien (12, v2.0)
### Software/Hardware-Kategorien (12)
| Kategorie | Eintraege | Beschreibung |
|-----------|-----------|--------------|
| `software_fault` | 10 | Race Condition, Stack Overflow, Integer Overflow, Deadlock... |
| `hmi_error` | 8 | Falsche Einheit, fehlender Alarm, Quittierung ohne Ursache... |
| `mechanical_hazard` | 6 | Unerwarteter Anlauf, Restenergie, Teileauswurf... |
| `electrical_hazard` | 6 | Elektrischer Schlag, Lichtbogen, gespeicherte Energie... |
| `thermal_hazard` | 4 | Ueberhitzung, Brandgefahr, Einfrieren... |
| `emc_hazard` | 5 | EMV-Stoerabstrahlung, ESD, HF-Stoerung... |
| `configuration_error` | 8 | Falscher Safety-Param, Hard-coded Credentials, Debug-Mode... |
| `safety_function_failure` | 8 | Not-Halt, STO, Schutztuer, Zweihand-Taster... |
| `logging_audit_failure` | 5 | Fehlende Protokollierung, Log-Manipulation, Overflow... |
| `integration_error` | 8 | Datentyp-Mismatch, Endianness, Buffer Overflow, Heartbeat... |
| `environmental_hazard` | 5 | Temperatur, Feuchtigkeit, Vibration, Kontamination... |
| `maintenance_hazard` | 6 | LOTO fehlt, Wartung bei laufender Maschine, Wiederanlauf... |
| 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 |
**Filter:** `GET /sdk/v1/iace/hazard-library?category=software_fault&componentType=sw`
### 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 (15) | Standard-Expositionswert |
| `default_avoidance` | int (15) | 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`
---
@@ -117,14 +172,134 @@ Die Controls-Library enthaelt **200 Eintraege** in 6 Domaenen:
---
## 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 (projektunabhaengig)
### Libraries & Referenzdaten (projektunabhaengig)
| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| GET | `/sdk/v1/iace/hazard-library` | Alle Gefaehrdungen (~140) |
| 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/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 |
### Projektmanagement
@@ -170,7 +345,8 @@ Die Controls-Library enthaelt **200 Eintraege** in 6 Domaenen:
| 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 Risikoübersicht |
| 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
@@ -290,19 +466,30 @@ curl -sk https://macmini:8093/sdk/v1/iace/controls-library | python3 -c "import
---
## Beispiel: Risikobewertung mit Avoidance
## 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
# Risikobewertung mit Avoidance-Faktor (A=5: nicht vermeidbar)
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 '{
"hazard_id": "<hid>",
"severity": 5,
"exposure": 3,
"probability": 3,
"avoidance": 5,
"avoidance": 4,
"control_maturity": 2,
"control_coverage": 0.6,
"test_evidence_strength": 0.5,
@@ -310,9 +497,7 @@ curl -sk -X POST https://macmini:8093/sdk/v1/iace/projects/{id}/hazards/{hid}/as
}'
```
Ohne Avoidance (A=0): `InherentRisk = 5×3×3 = 45`
Mit Avoidance A=5: `InherentRisk = 5×3×3×(5/3) = 75` (kritisch!)
Mit Avoidance A=1: `InherentRisk = 5×3×3×(1/3) = 15` (medium)
Ergebnis: `R = 5 × 3 × 3 × 4 = 180`**very_high** (ISO-Schwellwerte)
---
@@ -338,11 +523,35 @@ curl -sk "https://macmini:8093/sdk/v1/iace/controls-library?category=software_fa
| `iace_components` | System-Komponenten |
| `iace_regulatory_classifications` | Regulierungsklassifizierungen |
| `iace_hazard_library` | Benutzerdefinierte Hazard-Templates |
| `iace_hazards` | Projektspezifische Gefaehrdungen |
| `iace_risk_assessments` | SEPA-Risikobewertungen (inkl. avoidance) |
| `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 |
---
## 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).