# 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 |