feat(form-builder): form_field_bindings table + polymorphic owner + cascade observer

WS-5a commit 1 of 4 per ARCH-CONSOLIDATION-ADDENDUM-2026-04-24 Q3. Creates the relational home for what was form_fields.binding JSON and form_field_library.default_binding JSON. Owner discriminator is polymorphic morph (owner_type/owner_id) — the pattern the rest of WS-5 (5b validation_rules, 5d options) will reuse. Migration backfills rows from both JSON sources in a single transaction and is genuinely reversible (rollback reconstructs the JSON). Old columns remain in place until commit 3 has switched all readers. Pattern B (binding=null) is represented by absence of row. mode enum covers entity_owned / mirrored only. Cascade on owner delete via observer — bindings are physical state, not historical audit. FormFieldBindingScope enforces multi-tenancy via UNION over both owner chains (form_field → schema → org OR form_field_library → org) — Q2's declarative tenantScopeStrategy() can't walk morph parents. Tests: migration forward/back, morph relation, cascade observer, scope isolation, enum coverage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-24 18:43:11 +02:00
parent 76090b934e
commit af8a9da038
17 changed files with 1081 additions and 0 deletions
--- a/api/app/Models/FormBuilder/FormFieldBinding.php
+++ b/api/app/Models/FormBuilder/FormFieldBinding.php
@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\FormBuilder;
+
+use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
+use App\Enums\FormBuilder\FormFieldBindingMode;
+use App\Models\Scopes\FormFieldBindingScope;
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+
+/**
+ * Relational home for what was `form_fields.binding` and
+ * `form_field_library.default_binding` JSON. Polymorphic owner — morph
+ * aliases `form_field` and `form_field_library`. See ARCH-FORM-BUILDER
+ * §6.7 and ARCH-CONSOLIDATION-ADDENDUM-2026-04-24 §Q3.
+ *
+ * Pattern B (no binding) is represented by the absence of a row. Only
+ * Pattern A (entity_owned) and Pattern C (mirrored) create rows.
+ */
+final class FormFieldBinding extends Model
+{
+    use HasFactory;
+    use HasUlids;
+
+    protected $table = 'form_field_bindings';
+
+    protected static function booted(): void
+    {
+        static::addGlobalScope(new FormFieldBindingScope());
+    }
+
+    protected $fillable = [
+        'owner_type',
+        'owner_id',
+        'target_entity',
+        'target_attribute',
+        'mode',
+        'sync_direction',
+        'merge_strategy',
+        'trust_level',
+        'is_identity_key',
+    ];
+
+    /** @var array<string, string> */
+    protected $casts = [
+        'mode' => FormFieldBindingMode::class,
+        'merge_strategy' => FormFieldBindingMergeStrategy::class,
+        'trust_level' => 'int',
+        'is_identity_key' => 'bool',
+    ];
+
+    public function owner(): MorphTo
+    {
+        return $this->morphTo('owner', 'owner_type', 'owner_id');
+    }
+
+    public function isEntityOwned(): bool
+    {
+        return $this->mode === FormFieldBindingMode::EntityOwned;
+    }
+
+    public function isMirrored(): bool
+    {
+        return $this->mode === FormFieldBindingMode::Mirrored;
+    }
+}