crewli/api/app/Models/FormBuilder/FormSchema.php

<?php

declare(strict_types=1);

namespace App\Models\FormBuilder;

use App\Enums\FormBuilder\FormPurpose;
use App\Enums\FormBuilder\FormSchemaSnapshotMode;
use App\Enums\FormBuilder\FormSubmissionMode;
use App\Models\CrowdType;
use App\Models\Organisation;
use App\Models\Scopes\OrganisationScope;
use App\Models\User;
use App\Support\Json\JsonCanonicalizer;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\MorphTo;
use Illuminate\Database\Eloquent\SoftDeletes;

/**
 * Activity log strategy: explicit calls via logSchemaChange() — no LogsActivity
 * trait (would produce noise). See ARCH-FORM-BUILDER.md §17.1 and S1 Phase 4b.
 */
final class FormSchema extends Model
{
    use HasFactory;
    use HasUlids;
    use SoftDeletes;

    public string $organisationScopeColumn = 'organisation_id';

    protected static function booted(): void
    {
        self::addGlobalScope(new OrganisationScope);
    }

    protected $fillable = [
        'organisation_id',
        'owner_type',
        'owner_id',
        'name',
        'slug',
        'purpose',
        'default_crowd_type_id',
        'description',
        'is_published',
        'submission_mode',
        'public_token',
        'public_token_previous',
        'public_token_rotated_at',
        'submission_deadline',
        'locale',
        'settings',
        'version',
        'snapshot_mode',
        'freeze_on_submit',
        'retention_days',
        'consent_version',
        'section_level_submit',
        'auto_save_enabled',
        'max_submissions',
        'created_by_user_id',
        'last_updated_by_user_id',
        'edit_lock_user_id',
        'edit_lock_expires_at',
    ];

    /** @var array<string, string> */
    protected $casts = [
        'purpose' => FormPurpose::class,
        'submission_mode' => FormSubmissionMode::class,
        'snapshot_mode' => FormSchemaSnapshotMode::class,
        'is_published' => 'bool',
        'freeze_on_submit' => 'bool',
        'section_level_submit' => 'bool',
        'auto_save_enabled' => 'bool',
        'settings' => 'array',
        'submission_deadline' => 'datetime',
        'public_token_rotated_at' => 'datetime',
        'edit_lock_expires_at' => 'datetime',
        'version' => 'int',
        'retention_days' => 'int',
        'max_submissions' => 'int',
    ];

    public function organisation(): BelongsTo
    {
        return $this->belongsTo(Organisation::class);
    }

    /** @return BelongsTo<CrowdType, $this> */
    public function defaultCrowdType(): BelongsTo
    {
        return $this->belongsTo(CrowdType::class, 'default_crowd_type_id');
    }

    public function owner(): MorphTo
    {
        return $this->morphTo();
    }

    public function fields(): HasMany
    {
        return $this->hasMany(FormField::class);
    }

    public function sections(): HasMany
    {
        return $this->hasMany(FormSchemaSection::class);
    }

    public function submissions(): HasMany
    {
        return $this->hasMany(FormSubmission::class);
    }

    public function webhooks(): HasMany
    {
        return $this->hasMany(FormSchemaWebhook::class);
    }

    public function createdBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'created_by_user_id');
    }

    public function lastUpdatedBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'last_updated_by_user_id');
    }

    public function editLockUser(): BelongsTo
    {
        return $this->belongsTo(User::class, 'edit_lock_user_id');
    }

    /**
     * Nuanced activity log (ARCH §17.1; S1 Phase 4b). Callers choose which
     * events are worth logging — e.g. created/deleted/restored, published
     * toggled, purpose changed, freeze_on_submit toggled, retention_days
     * changed, consent_version changed, public_token rotated, snapshot_mode
     * changed. NOT logged (noise): name/description/slug, settings, locale.
     *
     * Bulk-fixture suppression: the activitylog.enabled config key is the
     * kill-switch. Seeders and one-shot commands wrap themselves in
     * App\Support\ActivityLog::suppressed(...). activity()->log() becomes
     * a silent no-op while disabled, so no guard is needed here.
     *
     * @param  array<string, mixed>  $properties
     */
    public function logSchemaChange(string $event, array $properties = []): void
    {
        // RFC-WS-6 session 2.7: properties land in activity_log.properties
        // (MySQL JSON column). Canonicalize so diff/regression assertions
        // and downstream consumers see byte-stable structure regardless of
        // MySQL key-order normalization on round-trip.
        activity()
            ->performedOn($this)
            ->withProperties(JsonCanonicalizer::canonicalize($properties))
            ->log($event);
    }
}