test+docs: IACE Phase 3/4 — fehlende Tests + Entwickler-Dokumentation

18 neue Unit/Integration-Tests (phase3_4_test.go): - Narrative Parser: State-Keyword Extraktion (7 Subtests), Transitions, No-Match - CNC Patterns: MachineType-Restriktion, Unique IDs, Referenced Measures exist - VDMA Patterns: MachineType-Restriktion, Unique IDs, Referenced Measures exist - Metalworking/VDMA Measures: Feld-Validierung (ID, Name, Desc, Type, NormRefs) - Full-Library: 476 Measures alle unique - Integration: CNC-Projekt → 84 Patterns → 35 Measures → Trajectory 48→1 - Integration: Maintenance-State filtert Patterns korrekt - Evidence: Count 55, Unique IDs, Sort Order IACE_ENGINE.md Entwickler-Dokumentation: - Architektur-Uebersicht mit Flussdiagramm - Datenmodell: HazardPattern, ProtectiveMeasureEntry, RiskReduction, MatchInput - Operational State Graph mit 9 States und Transitions - Human Interaction Model mit 6 Rollen - Suppression Engine mit RiskTrajectory Beispiel - API-Endpoints Tabelle - Dateien-Referenz (Massnahmen + Patterns) - Test-Ausfuehrungsanleitung Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-10 09:49:29 +02:00
parent 82951785ec
commit df463dbce7
3 changed files with 541 additions and 0 deletions
@@ -12,6 +12,7 @@
 8. [API-Endpoints](#8-api-endpoints)
 9. [Policy-Dateien](#9-policy-dateien)
 10. [Tests ausführen](#10-tests-ausführen)
+11. [IACE CE-Compliance Engine](IACE_ENGINE.md) (separate Datei)

 ---

@@ -0,0 +1,191 @@
+# 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)
+
+```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)
+
+```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)
+
+```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
+
+```bash
+# 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 |