Fib Integrity Guard

Regelbasiertes Governance- und Integritäts-Plugin für Shopware 6.

FibIntegrityGuard definiert versionierbare Regeln und setzt sie zur Laufzeit in kritischen Pfaden durch:

• DAL Writes (Create/Update/Delete)
• Cart / Checkout
• State Machine Transitions
• API/Import als vorbereitete Scopes (erweiterbar)

Zusätzlich wird jede Regelverletzung als Audit-Event in einer eigenen Violation-Entität gespeichert.

Warum dieses Plugin?

In vielen Shops sind Regeln verteilt über:

• DAL-Validierungen
• Subscriber/Services
• Checkout-Logik
• individuelle Sonderfälle

Das macht Governance schwer nachvollziehbar. FibIntegrityGuard zentralisiert diese Logik in einem einheitlichen Regelmodell.

Funktionsumfang (aktueller Stand)

1) Integrity Rule Modell (DAL, Expression-basiert)

Entity: fib_integrity_rule

Wichtige Felder:

• name
• scope (dal_write, cart, state_transition, api)
• entityName (z. B. product, order, cart, *)
• trigger (z. B. create, update, delete, checkout, enter_state, *)
• conditionType (aktuell: symfony_expression)
• condition (Expression)
• severity (info, warning, critical)
• enforcement (log, warn, block, fix)
• fixAction (JSON, MVP aktuell nur dokumentiert/geloggt)
• priority, active
• validFrom, validTo
• channelIds (JSON-Liste, scoped rules)
• version, previousRuleId

2) Integrity Policy Modell (DAL, Rule Builder-basiert)

Entity: fib_integrity_policy

Wichtige Felder:

• name
• scope (cart, state_transition, dal_write, api)
• ruleId (FK auf Shopware rule)
• enforcement (log, warn, block, fix)
• severity (info, warning, critical)
• entityName, trigger
• priority, active
• validFrom, validTo
• channelIds (JSON-Liste)
• message, description

Damit kann der Merchant den Shopware Rule Builder als Condition-UX nutzen, während FibIntegrityGuard die Durchsetzung übernimmt.

3) Violation Audit Log

Entity: fib_integrity_violation

Speichert pro Treffer:

• ruleId
• contextData (z. B. User/SalesChannel/SourceType)
• entityName, entityId, operation
• payloadSnapshotBefore, payloadSnapshotAfter
• message, severity, createdAt

4) Evaluation Engine

RuleEngine lädt aktive Regeln nach Scope, sortiert nach Priorität und evaluiert die Condition gegen ein standardisiertes Context-Objekt:

• entity
• before
• operation
• user
• salesChannel
• cart (im Cart-Scope)
• context

Condition Engine: Symfony ExpressionLanguage (+ Helper-Funktionen regex_match(), contains()).

Zusätzlich gibt es einen Rule-Builder-Policy-Evaluator (RuleBuilderPolicyEvaluator), der Shopware-Regeln gegen CartRuleScope auswertet.

5) Enforcement-Punkte

DAL Pre-Write (Blocking)

Subscriber auf PreWriteValidationEvent:

• evaluiert nur Regeln mit enforcement=block
• bei Treffer: WriteConstraintViolationException -> Write wird abgebrochen

DAL Post-Write (Warn/Log/Fix-MVP)

Subscriber auf EntityWrittenEvent:

• evaluiert log, warn, fix
• schreibt Violation-Audit
• kein nachträgliches hartes Blocken

Cart / Checkout

Eigener CartValidator:

• evaluiert zuerst fib_integrity_policy (Rule Builder) im Cart-Scope
• Scope cart, Trigger checkout
• bei block: GenericCartError -> Checkout wird verhindert
• evaluiert danach weiterhin fib_integrity_rule (Expression-Modus, Advanced)

State Machine

Subscriber auf StateMachineTransitionEvent:

• Scope state_transition, Trigger enter_state
• block wirft Exception und stoppt Transition

Admin-Modul (MVP)

Enthaltenes Administration-Modul mit:

• Rule List (Filter/Sort/Paging)
• Rule Detail (Create/Edit)
• Policy List (Filter/Sort/Paging)
• Policy Detail (Create/Edit, Rule-Builder-Regelzuordnung)
• Violation List (Inbox)

Hinweis: Ein integrierter "Test Rule against payload" Runner ist als nächster Ausbauschritt vorgesehen.

Installation

Wichtiger Hinweis zu Dependencies

Shopware führt bei plugin:install kein Composer für custom/plugins/* aus.

Das Plugin benötigt:

• symfony/expression-language

Diese Dependency muss vor Aktivierung verfügbar sein (Root-Composer oder gebündeltes Plugin-Vendor).

Standard-Setup

1. Abhängigkeit installieren (im Projekt): composer require symfony/expression-language
2. Plugin bekannt machen: bin/console plugin:refresh
3. Plugin installieren/aktivieren: bin/console plugin:install --activate FibIntegrityGuard
4. Migrationen ausführen: bin/console database:migrate --all FibIntegrityGuard
5. Cache leeren: bin/console cache:clear
6. Admin Build aktualisieren (je nach Setup): bin/console bundle:dump bin/console administration:build

Optionale Testdaten (Seed Command)

Für Demo-/Testzwecke gibt es einen optionalen Seed-Command. Er wird nie automatisch ausgeführt.

Seed (inaktiv, sicherer Default):

• bin/console fib:integrity-guard:seed

Seed + aktivierte Demo-Regeln/-Policies:

• bin/console fib:integrity-guard:seed --activate

Vorhandene Demo-Daten löschen und neu erzeugen:

• bin/console fib:integrity-guard:seed --reset

Der Command legt an:

• eine Shopware Rule-Builder-Regel (alwaysValid) für Policy-Demos
• Beispiel-Policies in fib_integrity_policy
• Beispiel-Expression-Regeln in fib_integrity_rule

Beispiel-Regeln

1) Produktbestand nie negativ (DAL)

• scope: dal_write
• entityName: product
• trigger: update
• condition: entity.stock < 0
• enforcement: block

2) B2B Checkout nur mit VAT-ID

• scope: cart
• entityName: cart
• trigger: checkout
• condition: contains(user.vatIds, null) or user.vatIds == []
• enforcement: block

3) State-Wechsel nur mit Vorbedingung

• scope: state_transition
• entityName: order_transaction
• trigger: enter_state
• condition: entity.toState == "paid" and entity.fromState != "authorized"
• enforcement: block

Sicherheitshinweise

• Keine Raw-PHP-Evaluation, nur ExpressionLanguage.
• Regeln/Policies/Violations sind vom eigenen Rule-Loop ausgenommen (Rekursionsschutz).
• Violation-Writes laufen in einem eigenen Context-State, um Endlosschleifen zu verhindern.

Grenzen im aktuellen MVP

• fixAction wird aktuell geloggt, aber nicht automatisch angewendet.
• channelIds ist JSON-basiert, noch keine native ManyToMany-Verknüpfung.
• Kein Admin-Test-Runner für Conditions.
• Kein spezifischer API-Scope-Subscriber und kein dedizierter Import/Queue-Hook (Scope-Feld ist vorbereitet).

Roadmap (empfohlen)

1. Rule Test Runner im Admin (sample payload -> evaluation result)
2. ACL/Privileges für Rule-Management verfeinern
3. channelIds auf echte Relation umstellen
4. Auto-Fix-Strategien (fixAction) kontrolliert aktivieren
5. Version-Diff UI im Admin