breakpilot-compliance/docs-src/services/ai-compliance-sdk/IACE_ENGINE.md

IACE CE-Compliance Engine - Entwickler-Dokumentation

Uebersicht

Die IACE (Inherent-risk Adjusted Control Effectiveness) Engine ist das CE-Konformitaetsmodul fuer Maschinensicherheit. Sie automatisiert die Risikobeurteilung nach ISO 12100 durch deterministische Pattern-Matching-Logik ohne LLM-Abhaengigkeit.

Architektur

Narrative Text → Parser → Tags → PatternEngine → Hazards + Measures + Evidence
                                        ↓
                              RiskEngine → RiskTrajectory
                                        ↓
                            CompletenessGates → Tech-File Export

Kernkomponenten

Datei	Funktion
narrative_parser.go	Deterministische Extraktion: Komponenten, Energiequellen, Lifecycle, States, Rollen
pattern_engine.go	PatternEngine mit 1.114 Patterns, State/Role/MachineType-Filtering
engine.go	RiskEngine: InherentRisk, ControlEffectiveness, ResidualRisk, RiskTrajectory
completeness_gates.go	25 Compliance-Gates fuer CE-Export-Freigabe
tag_resolver.go	Tag-Aufloesung: ComponentID → Tags, EnergyID → Tags, Evidence-Bibliothek
measures_library*.go	476 Schutzmassnahmen (8 Dateien)
hazard_patterns*.go	1.114 Gefaehrdungsmuster (38+ Dateien)

Bibliotheken (Stand Phase 3+4)

Bibliothek	Anzahl	Dateien
Hazard Patterns	1.114	hazard_patterns*.go (38 Dateien)
Schutzmassnahmen	476	measures_library*.go (8 Dateien)
Evidenztypen	55	tag_resolver.go (E01-E55)
Operationale Zustaende	9	pattern_engine.go
Menschliche Rollen	6	hazard_pattern_types.go
Maschinentypen (explizit)	13+	CNC, Dreh, Fraes, Schleifen, Schweissen, Holz, Oberfläche, Druck, Pumpe, ...

Datenmodell

HazardPattern (hazard_pattern_types.go)

type HazardPattern struct {
    ID                    string   // z.B. "HP1400"
    NameDE, NameEN        string
    RequiredComponentTags []string // AND-Logik
    RequiredEnergyTags    []string // AND-Logik
    RequiredLifecycles    []string // OR-Logik (mind. 1 muss matchen)
    ExcludedComponentTags []string // NOT-Logik
    GeneratedHazardCats   []string // Output-Kategorien
    SuggestedMeasureIDs   []string // Verweis auf ProtectiveMeasureEntry.ID
    SuggestedEvidenceIDs  []string // Verweis auf EvidenceTypeInfo.ID
    Priority              int
    MachineTypes          []string // nil = feuert fuer alle Typen
    OperationalStates     []string // nil = feuert in allen Zustaenden
    StateTransitions      []string // Format: "from→to"
    HumanRoles            []string // nil = feuert fuer alle Rollen
    // Detail-Felder fuer Hazard-Erzeugung
    ScenarioDE, TriggerDE, HarmDE, AffectedDE, ZoneDE string
    DefaultSeverity, DefaultExposure int
}

ProtectiveMeasureEntry (models_api.go)

type ProtectiveMeasureEntry struct {
    ID             string
    ReductionType  string          // "design", "protection", "protective", "information"
    SubType        string          // z.B. "geometry", "fixed_guard", "ppe"
    Name           string
    Description    string
    HazardCategory string
    NormReferences []string
    RiskReduction  *RiskReduction  // Suppression Engine Profil
    Mandatory      bool
    MandatoryNorm  string
}

type RiskReduction struct {
    SeverityDelta    int  // z.B. -2 (reduziert Schwere um 2 Stufen)
    ExposureDelta    int  // z.B. -2 (reduziert Exposition um 2 Stufen)
    ProbabilityDelta int  // z.B. -1 (reduziert Wahrscheinlichkeit um 1 Stufe)
}

MatchInput / MatchOutput (pattern_engine.go)

type MatchInput struct {
    ComponentLibraryIDs []string
    EnergySourceIDs     []string
    LifecyclePhases     []string
    CustomTags          []string
    OperationalStates   []string  // Filter: nur Patterns fuer diese Zustaende
    StateTransitions    []string  // Filter: nur Patterns fuer diese Uebergaenge
    HumanRoles          []string  // Filter: nur Patterns fuer diese Rollen
}

Operational State Graph

9 Standard-Betriebszustaende mit 20 Transitions:

startup → homing → automatic_operation ↔ manual_operation
                          ↕                     ↕
                    teach_mode              maintenance
                          ↕                     ↕
                      cleaning          emergency_stop → recovery_mode

Patterns mit OperationalStates feuern nur im passenden Zustand. Beispiel:

• HP073 "Wartung ohne LOTO" → nur in maintenance
• HP068 "Unerwarteter Wiederanlauf" → nur in recovery_mode/emergency_stop + StateTransition maintenance→automatic_operation

Human Interaction Model

6 Rollen: operator, maintenance_tech, programmer, cleaning_staff, bystander, supervisor

Patterns mit HumanRoles feuern nur wenn die Rolle im Projekt vorhanden ist. Beispiel:

• HP062 "Fehlprogrammierung" → nur fuer programmer
• HP073 "LOTO-Fehler" → nur fuer maintenance_tech

Suppression Engine (Risk Trajectory)

Die RiskTrajectory berechnet schrittweise Risikoreduktion entlang der ISO 12100 Hierarchie:

Inharent: S=4, E=4, P=3 → 48 (high)
→ Nach Design:      S=3, E=3, P=3 → 27 (medium)   // M001 S-1,E-1 + M012 S-2
→ Nach Schutz:      S=3, E=1, P=2 → 6 (low)       // M067 E-2,P-1
→ Nach Information:  S=3, E=1, P=1 → 3 (negligible) // M161 P-1

Jede Massnahme hat ein RiskReduction-Profil. Deltas werden pro Stufe kumuliert, jeder Parameter auf Minimum 1 geclampt.

API-Endpoints (IACE)

Methode	Pfad	Funktion
POST	/projects/:id/initialize	Narrative parsen → Patterns matchen → Hazards/Measures erzeugen
POST	/projects/:id/parse-narrative	Nur parsen (ohne DB-Schreiben)
GET	/projects/:id/hazards	Alle Gefaehrdungen listen
POST	/projects/:id/hazards/:hid/mitigations	Massnahme einer Gefaehrdung zuordnen
GET	/projects/:id/completeness	25 Compliance-Gates pruefen
POST	/projects/:id/tech-file/sections/:type	Tech-File-Abschnitt generieren
GET	/projects/:id/tech-file/export/:format	CE-Akte exportieren (PDF/DOCX/MD/XLSX)

Tests ausfuehren

# Go Unit + Integration Tests
cd ai-compliance-sdk
go test ./internal/iace/... -v

# Playwright E2E (gegen Live Mac Mini)
cd admin-compliance
npx playwright test e2e/specs/iace-module.spec.ts --config e2e/playwright-live.config.ts

# Alle IACE E2E Tests
npx playwright test e2e/specs/iace-*.spec.ts --config e2e/playwright-live.config.ts

Dateien nach Funktion

Massnahmen-Bibliothek (476 Massnahmen)

Datei	IDs	Inhalt
measures_library.go	M001-M060	Design (Geometrie, Kraft, Material, Ergonomie, Steuerung, Fluid, Laerm)
measures_library_ext.go	M061-M216	Schutz + Information + Phase-1B
measures_library_mandatory.go	MN001-MN025	Norm-Pflichtmassnahmen
measures_library_trbs.go	M217-M301	TRBS 1111/1201/2111/2121/2131/2141/2152
measures_library_osha.go	M302-M371	OSHA Machine Guarding, LOTO, Electrical, Robots, Noise, Ergo, Pressure
measures_library_trgs.go	M372-M382	TRGS Gefahrstoffe (Substitution, Absaugung, Hautschutz, Lagerung)
measures_library_supplementary.go	M383-M403	RAG-Gap: Brandschutz, Laser, MSR-Cyber, Instandhaltung, ASR
measures_library_metalworking.go	M404-M421	CNC/Metalworking (KSS, Schleifen, Schweissen)
measures_library_vdma.go	M422-M451	VDMA: Holz, Oberfläche, Druck, Pumpen

Pattern-Dateien (1.114 Patterns)

Datei-Gruppe	IDs	Inhalt
hazard_patterns.go	HP001-HP044	Basis-Patterns
hazard_patterns_extended*.go	HP045-HP173	Erweiterte Patterns
hazard_patterns_cobot.go	HP059-HP065	Cobot-spezifisch
hazard_patterns_operational.go	HP066-HP093	Stoerung, Wartung, LOTO
hazard_patterns_cnc*.go	HP1400-HP1434	CNC/Metalworking/Schweissen
hazard_patterns_vdma.go	HP1500-HP1549	Holz, Oberfläche, Druck, Pumpen
... (30+ weitere Dateien)		Branchen, Cyber, AI, Final-Patterns