Files
breakpilot-compliance/ai-compliance-sdk/internal/iace/models.go
Benjamin Admin efeacc1619
All checks were successful
CI / go-lint (push) Has been skipped
CI / python-lint (push) Has been skipped
CI / nodejs-lint (push) Has been skipped
CI / test-go-ai-compliance (push) Successful in 35s
CI / test-python-backend-compliance (push) Successful in 33s
CI / test-python-document-crawler (push) Successful in 21s
CI / test-python-dsms-gateway (push) Successful in 19s
feat(iace): Hazard-Library v2, Controls-Library, SEPA Avoidance, CE RAG-Ingest
- Hazard-Library: +79 neue Eintraege in 12 Kategorien (software_fault,
  hmi_error, mechanical_hazard, electrical_hazard, thermal_hazard,
  emc_hazard, configuration_error, safety_function_failure,
  logging_audit_failure, integration_error, environmental_hazard,
  maintenance_hazard) — Gesamtanzahl: ~116 Eintraege in 24 Kategorien
- Controls-Library: neue Datei controls_library.go mit 200 Eintraegen
  in 6 Domaenen (REQ/ARCH/SWDEV/VER/CYBER/DOC)
- Handler: GET /sdk/v1/iace/controls-library (?domain=, ?category=)
- SEPA: CalculateInherentRisk() + 4. Param Avoidance (0=disabled,
  1-5: 3=neutral); RiskComputeInput.Avoidance, RiskAssessment.Avoidance,
  AssessRiskRequest.Avoidance — backward-kompatibel (A=0 → S×E×P)
- Tests: engine_test.go + hazard_library_test.go aktualisiert
- Scripts: ingest-ce-corpus.sh — 15 CE/Safety-Dokumente (EUR-Lex,
  NIST, ENISA, NASA, OWASP, MITRE CWE) in bp_compliance_ce und
  bp_compliance_datenschutz
- Docs: docs-src/services/sdk-modules/iace.md + mkdocs.yml Nav-Eintrag

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-05 17:13:01 +01:00

488 lines
22 KiB
Go

package iace
import (
"encoding/json"
"time"
"github.com/google/uuid"
)
// ============================================================================
// Constants / Enums
// ============================================================================
// ProjectStatus represents the lifecycle status of an IACE project
type ProjectStatus string
const (
ProjectStatusDraft ProjectStatus = "draft"
ProjectStatusOnboarding ProjectStatus = "onboarding"
ProjectStatusClassification ProjectStatus = "classification"
ProjectStatusHazardAnalysis ProjectStatus = "hazard_analysis"
ProjectStatusMitigation ProjectStatus = "mitigation"
ProjectStatusVerification ProjectStatus = "verification"
ProjectStatusTechFile ProjectStatus = "tech_file"
ProjectStatusCompleted ProjectStatus = "completed"
ProjectStatusArchived ProjectStatus = "archived"
)
// ComponentType represents the type of a system component
type ComponentType string
const (
ComponentTypeSoftware ComponentType = "software"
ComponentTypeFirmware ComponentType = "firmware"
ComponentTypeAIModel ComponentType = "ai_model"
ComponentTypeHMI ComponentType = "hmi"
ComponentTypeSensor ComponentType = "sensor"
ComponentTypeActuator ComponentType = "actuator"
ComponentTypeController ComponentType = "controller"
ComponentTypeNetwork ComponentType = "network"
ComponentTypeOther ComponentType = "other"
)
// RegulationType represents the applicable EU regulation
type RegulationType string
const (
RegulationNIS2 RegulationType = "nis2"
RegulationAIAct RegulationType = "ai_act"
RegulationCRA RegulationType = "cra"
RegulationMachineryRegulation RegulationType = "machinery_regulation"
)
// HazardStatus represents the lifecycle status of a hazard
type HazardStatus string
const (
HazardStatusIdentified HazardStatus = "identified"
HazardStatusAssessed HazardStatus = "assessed"
HazardStatusMitigated HazardStatus = "mitigated"
HazardStatusAccepted HazardStatus = "accepted"
HazardStatusClosed HazardStatus = "closed"
)
// AssessmentType represents the type of risk assessment
type AssessmentType string
const (
AssessmentTypeInitial AssessmentType = "initial"
AssessmentTypePostMitigation AssessmentType = "post_mitigation"
AssessmentTypeReassessment AssessmentType = "reassessment"
)
// RiskLevel represents the severity level of a risk
type RiskLevel string
const (
RiskLevelCritical RiskLevel = "critical"
RiskLevelHigh RiskLevel = "high"
RiskLevelMedium RiskLevel = "medium"
RiskLevelLow RiskLevel = "low"
RiskLevelNegligible RiskLevel = "negligible"
)
// ReductionType represents the type of risk reduction measure
type ReductionType string
const (
ReductionTypeDesign ReductionType = "design"
ReductionTypeProtective ReductionType = "protective"
ReductionTypeInformation ReductionType = "information"
)
// MitigationStatus represents the lifecycle status of a mitigation measure
type MitigationStatus string
const (
MitigationStatusPlanned MitigationStatus = "planned"
MitigationStatusImplemented MitigationStatus = "implemented"
MitigationStatusVerified MitigationStatus = "verified"
MitigationStatusRejected MitigationStatus = "rejected"
)
// VerificationMethod represents the method used for verification
type VerificationMethod string
const (
VerificationMethodTest VerificationMethod = "test"
VerificationMethodAnalysis VerificationMethod = "analysis"
VerificationMethodInspection VerificationMethod = "inspection"
VerificationMethodReview VerificationMethod = "review"
)
// TechFileSectionStatus represents the status of a technical file section
type TechFileSectionStatus string
const (
TechFileSectionStatusDraft TechFileSectionStatus = "draft"
TechFileSectionStatusGenerated TechFileSectionStatus = "generated"
TechFileSectionStatusReviewed TechFileSectionStatus = "reviewed"
TechFileSectionStatusApproved TechFileSectionStatus = "approved"
)
// MonitoringEventType represents the type of monitoring event
type MonitoringEventType string
const (
MonitoringEventTypeIncident MonitoringEventType = "incident"
MonitoringEventTypeUpdate MonitoringEventType = "update"
MonitoringEventTypeDriftAlert MonitoringEventType = "drift_alert"
MonitoringEventTypeRegulationChange MonitoringEventType = "regulation_change"
MonitoringEventTypeAudit MonitoringEventType = "audit"
)
// AuditAction represents the type of action recorded in the audit trail
type AuditAction string
const (
AuditActionCreate AuditAction = "create"
AuditActionUpdate AuditAction = "update"
AuditActionDelete AuditAction = "delete"
AuditActionApprove AuditAction = "approve"
AuditActionVerify AuditAction = "verify"
)
// ============================================================================
// Main Entities
// ============================================================================
// Project represents an IACE compliance project for a machine or system
type Project struct {
ID uuid.UUID `json:"id"`
TenantID uuid.UUID `json:"tenant_id"`
MachineName string `json:"machine_name"`
MachineType string `json:"machine_type"`
Manufacturer string `json:"manufacturer"`
Description string `json:"description,omitempty"`
NarrativeText string `json:"narrative_text,omitempty"`
Status ProjectStatus `json:"status"`
CEMarkingTarget string `json:"ce_marking_target,omitempty"`
CompletenessScore float64 `json:"completeness_score"`
RiskSummary map[string]int `json:"risk_summary,omitempty"`
TriggeredRegulations json.RawMessage `json:"triggered_regulations,omitempty"`
Metadata json.RawMessage `json:"metadata,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ArchivedAt *time.Time `json:"archived_at,omitempty"`
}
// Component represents a system component within a project
type Component struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
ParentID *uuid.UUID `json:"parent_id,omitempty"`
Name string `json:"name"`
ComponentType ComponentType `json:"component_type"`
Version string `json:"version,omitempty"`
Description string `json:"description,omitempty"`
IsSafetyRelevant bool `json:"is_safety_relevant"`
IsNetworked bool `json:"is_networked"`
Metadata json.RawMessage `json:"metadata,omitempty"`
SortOrder int `json:"sort_order"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// RegulatoryClassification represents the classification result for a regulation
type RegulatoryClassification struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
Regulation RegulationType `json:"regulation"`
ClassificationResult string `json:"classification_result"`
RiskLevel RiskLevel `json:"risk_level"`
Confidence float64 `json:"confidence"`
Reasoning string `json:"reasoning,omitempty"`
RAGSources json.RawMessage `json:"rag_sources,omitempty"`
Requirements json.RawMessage `json:"requirements,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// HazardLibraryEntry represents a reusable hazard template from the library
type HazardLibraryEntry struct {
ID uuid.UUID `json:"id"`
Category string `json:"category"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
DefaultSeverity int `json:"default_severity"`
DefaultProbability int `json:"default_probability"`
ApplicableComponentTypes []string `json:"applicable_component_types"`
RegulationReferences []string `json:"regulation_references"`
SuggestedMitigations json.RawMessage `json:"suggested_mitigations,omitempty"`
IsBuiltin bool `json:"is_builtin"`
TenantID *uuid.UUID `json:"tenant_id,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
// Hazard represents a specific hazard identified within a project
type Hazard struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
ComponentID uuid.UUID `json:"component_id"`
LibraryHazardID *uuid.UUID `json:"library_hazard_id,omitempty"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Scenario string `json:"scenario,omitempty"`
Category string `json:"category"`
Status HazardStatus `json:"status"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// RiskAssessment represents a quantitative risk assessment for a hazard
type RiskAssessment struct {
ID uuid.UUID `json:"id"`
HazardID uuid.UUID `json:"hazard_id"`
Version int `json:"version"`
AssessmentType AssessmentType `json:"assessment_type"`
Severity int `json:"severity"`
Exposure int `json:"exposure"`
Probability int `json:"probability"`
Avoidance int `json:"avoidance,omitempty"` // 0=disabled, 1-5 (3=neutral)
InherentRisk float64 `json:"inherent_risk"`
ControlMaturity int `json:"control_maturity"`
ControlCoverage float64 `json:"control_coverage"`
TestEvidenceStrength float64 `json:"test_evidence_strength"`
CEff float64 `json:"c_eff"`
ResidualRisk float64 `json:"residual_risk"`
RiskLevel RiskLevel `json:"risk_level"`
IsAcceptable bool `json:"is_acceptable"`
AcceptanceJustification string `json:"acceptance_justification,omitempty"`
AssessedBy uuid.UUID `json:"assessed_by"`
CreatedAt time.Time `json:"created_at"`
}
// Mitigation represents a risk reduction measure applied to a hazard
type Mitigation struct {
ID uuid.UUID `json:"id"`
HazardID uuid.UUID `json:"hazard_id"`
ReductionType ReductionType `json:"reduction_type"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Status MitigationStatus `json:"status"`
VerificationMethod VerificationMethod `json:"verification_method,omitempty"`
VerificationResult string `json:"verification_result,omitempty"`
VerifiedAt *time.Time `json:"verified_at,omitempty"`
VerifiedBy uuid.UUID `json:"verified_by,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// Evidence represents an uploaded file that serves as evidence for compliance
type Evidence struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
MitigationID *uuid.UUID `json:"mitigation_id,omitempty"`
VerificationPlanID *uuid.UUID `json:"verification_plan_id,omitempty"`
FileName string `json:"file_name"`
FilePath string `json:"file_path"`
FileHash string `json:"file_hash"`
FileSize int64 `json:"file_size"`
MimeType string `json:"mime_type"`
Description string `json:"description,omitempty"`
UploadedBy uuid.UUID `json:"uploaded_by"`
CreatedAt time.Time `json:"created_at"`
}
// VerificationPlan represents a plan for verifying compliance measures
type VerificationPlan struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
HazardID *uuid.UUID `json:"hazard_id,omitempty"`
MitigationID *uuid.UUID `json:"mitigation_id,omitempty"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
AcceptanceCriteria string `json:"acceptance_criteria,omitempty"`
Method VerificationMethod `json:"method"`
Status string `json:"status"`
Result string `json:"result,omitempty"`
CompletedAt *time.Time `json:"completed_at,omitempty"`
CompletedBy uuid.UUID `json:"completed_by,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// TechFileSection represents a section of the technical documentation file
type TechFileSection struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
SectionType string `json:"section_type"`
Title string `json:"title"`
Content string `json:"content,omitempty"`
Version int `json:"version"`
Status TechFileSectionStatus `json:"status"`
ApprovedBy uuid.UUID `json:"approved_by,omitempty"`
ApprovedAt *time.Time `json:"approved_at,omitempty"`
Metadata json.RawMessage `json:"metadata,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// MonitoringEvent represents a post-market monitoring event
type MonitoringEvent struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
EventType MonitoringEventType `json:"event_type"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Severity string `json:"severity"`
ImpactAssessment string `json:"impact_assessment,omitempty"`
Status string `json:"status"`
ResolvedAt *time.Time `json:"resolved_at,omitempty"`
ResolvedBy uuid.UUID `json:"resolved_by,omitempty"`
Metadata json.RawMessage `json:"metadata,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// AuditTrailEntry represents an immutable audit log entry for compliance traceability
type AuditTrailEntry struct {
ID uuid.UUID `json:"id"`
ProjectID uuid.UUID `json:"project_id"`
EntityType string `json:"entity_type"`
EntityID uuid.UUID `json:"entity_id"`
Action AuditAction `json:"action"`
UserID uuid.UUID `json:"user_id"`
OldValues json.RawMessage `json:"old_values,omitempty"`
NewValues json.RawMessage `json:"new_values,omitempty"`
Hash string `json:"hash"`
CreatedAt time.Time `json:"created_at"`
}
// ============================================================================
// API Request Types
// ============================================================================
// CreateProjectRequest is the API request for creating a new IACE project
type CreateProjectRequest struct {
MachineName string `json:"machine_name" binding:"required"`
MachineType string `json:"machine_type" binding:"required"`
Manufacturer string `json:"manufacturer" binding:"required"`
Description string `json:"description,omitempty"`
NarrativeText string `json:"narrative_text,omitempty"`
CEMarkingTarget string `json:"ce_marking_target,omitempty"`
Metadata json.RawMessage `json:"metadata,omitempty"`
}
// UpdateProjectRequest is the API request for updating an existing project
type UpdateProjectRequest struct {
MachineName *string `json:"machine_name,omitempty"`
MachineType *string `json:"machine_type,omitempty"`
Manufacturer *string `json:"manufacturer,omitempty"`
Description *string `json:"description,omitempty"`
NarrativeText *string `json:"narrative_text,omitempty"`
CEMarkingTarget *string `json:"ce_marking_target,omitempty"`
Metadata *json.RawMessage `json:"metadata,omitempty"`
}
// CreateComponentRequest is the API request for adding a component to a project
type CreateComponentRequest struct {
ProjectID uuid.UUID `json:"project_id" binding:"required"`
ParentID *uuid.UUID `json:"parent_id,omitempty"`
Name string `json:"name" binding:"required"`
ComponentType ComponentType `json:"component_type" binding:"required"`
Version string `json:"version,omitempty"`
Description string `json:"description,omitempty"`
IsSafetyRelevant bool `json:"is_safety_relevant"`
IsNetworked bool `json:"is_networked"`
}
// CreateHazardRequest is the API request for creating a new hazard
type CreateHazardRequest struct {
ProjectID uuid.UUID `json:"project_id" binding:"required"`
ComponentID uuid.UUID `json:"component_id" binding:"required"`
LibraryHazardID *uuid.UUID `json:"library_hazard_id,omitempty"`
Name string `json:"name" binding:"required"`
Description string `json:"description,omitempty"`
Scenario string `json:"scenario,omitempty"`
Category string `json:"category" binding:"required"`
}
// AssessRiskRequest is the API request for performing a risk assessment
type AssessRiskRequest struct {
HazardID uuid.UUID `json:"hazard_id" binding:"required"`
Severity int `json:"severity" binding:"required"`
Exposure int `json:"exposure" binding:"required"`
Probability int `json:"probability" binding:"required"`
Avoidance int `json:"avoidance,omitempty"` // 0=disabled, 1-5 (3=neutral)
ControlMaturity int `json:"control_maturity" binding:"required"`
ControlCoverage float64 `json:"control_coverage" binding:"required"`
TestEvidenceStrength float64 `json:"test_evidence_strength" binding:"required"`
AcceptanceJustification string `json:"acceptance_justification,omitempty"`
}
// CreateMitigationRequest is the API request for creating a mitigation measure
type CreateMitigationRequest struct {
HazardID uuid.UUID `json:"hazard_id" binding:"required"`
ReductionType ReductionType `json:"reduction_type" binding:"required"`
Name string `json:"name" binding:"required"`
Description string `json:"description,omitempty"`
}
// CreateVerificationPlanRequest is the API request for creating a verification plan
type CreateVerificationPlanRequest struct {
ProjectID uuid.UUID `json:"project_id" binding:"required"`
HazardID *uuid.UUID `json:"hazard_id,omitempty"`
MitigationID *uuid.UUID `json:"mitigation_id,omitempty"`
Title string `json:"title" binding:"required"`
Description string `json:"description,omitempty"`
AcceptanceCriteria string `json:"acceptance_criteria,omitempty"`
Method VerificationMethod `json:"method" binding:"required"`
}
// CreateMonitoringEventRequest is the API request for logging a monitoring event
type CreateMonitoringEventRequest struct {
ProjectID uuid.UUID `json:"project_id" binding:"required"`
EventType MonitoringEventType `json:"event_type" binding:"required"`
Title string `json:"title" binding:"required"`
Description string `json:"description,omitempty"`
Severity string `json:"severity" binding:"required"`
}
// InitFromProfileRequest is the API request for initializing a project from a company profile
type InitFromProfileRequest struct {
CompanyProfile json.RawMessage `json:"company_profile" binding:"required"`
ComplianceScope json.RawMessage `json:"compliance_scope" binding:"required"`
}
// ============================================================================
// API Response Types
// ============================================================================
// ProjectListResponse is the API response for listing projects
type ProjectListResponse struct {
Projects []Project `json:"projects"`
Total int `json:"total"`
}
// ProjectDetailResponse is the API response for a single project with related entities
type ProjectDetailResponse struct {
Project
Components []Component `json:"components"`
Classifications []RegulatoryClassification `json:"classifications"`
CompletenessGates []CompletenessGate `json:"completeness_gates"`
}
// RiskSummaryResponse is the API response for an aggregated risk overview
type RiskSummaryResponse struct {
TotalHazards int `json:"total_hazards"`
Critical int `json:"critical"`
High int `json:"high"`
Medium int `json:"medium"`
Low int `json:"low"`
Negligible int `json:"negligible"`
OverallRiskLevel RiskLevel `json:"overall_risk_level"`
AllAcceptable bool `json:"all_acceptable"`
}
// CompletenessGate represents a single gate in the project completeness checklist
type CompletenessGate struct {
ID string `json:"id"`
Category string `json:"category"`
Label string `json:"label"`
Required bool `json:"required"`
Passed bool `json:"passed"`
Details string `json:"details,omitempty"`
}