Benjamin Admin
df463dbce7
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>
192 lines
8.0 KiB
Markdown
192 lines
8.0 KiB
Markdown
# 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 |
|