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

<?php

declare(strict_types=1);

namespace App\Models\FormBuilder;

use App\Enums\FormBuilder\DismissalReasonType;
use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

/**
 * RFC-WS-6 §3 (Q5) — audit table for binding-pipeline failures.
 *
 * Audit model with no `organisation_id` column. Tenant scope flows via
 * the FK chain to `form_submissions.organisation_id`. The
 * {@see \App\Policies\FormBuilder\FormSubmissionActionFailurePolicy}
 * enforces this at access time per RFC §4 V3 (IDOR-class FK-chain
 * pattern). Do NOT register `OrganisationScope` directly on this model.
 *
 * Resolve and Dismiss are mutually exclusive workflows (RFC V2):
 * - Resolved → succeeded via another path (resolved_at + resolved_note)
 * - Dismissed → will not be replayed (dismissed_at + reason_type/note)
 */
final class FormSubmissionActionFailure extends Model
{
    /** @use HasFactory<\Database\Factories\FormBuilder\FormSubmissionActionFailureFactory> */
    use HasFactory;
    use HasUlids;

    protected $table = 'form_submission_action_failures';

    protected $fillable = [
        'form_submission_id',
        'listener_class',
        'binding_id',
        'failed_at',
        'exception_class',
        'exception_message',
        'context',
        'retry_count',
        'resolved_at',
        'resolved_by_user_id',
        'resolved_note',
        'dismissed_at',
        'dismissed_by_user_id',
        'dismissed_reason_type',
        'dismissed_reason_note',
    ];

    /** @var array<string, string> */
    protected $casts = [
        'failed_at' => 'datetime',
        'resolved_at' => 'datetime',
        'dismissed_at' => 'datetime',
        'context' => 'array',
        'retry_count' => 'int',
        'dismissed_reason_type' => DismissalReasonType::class,
    ];

    /** @return BelongsTo<FormSubmission, $this> */
    public function submission(): BelongsTo
    {
        return $this->belongsTo(FormSubmission::class, 'form_submission_id');
    }

    /** @return BelongsTo<FormFieldBinding, $this> */
    public function binding(): BelongsTo
    {
        return $this->belongsTo(FormFieldBinding::class, 'binding_id');
    }

    /** @return BelongsTo<User, $this> */
    public function resolvedBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'resolved_by_user_id');
    }

    /** @return BelongsTo<User, $this> */
    public function dismissedBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'dismissed_by_user_id');
    }

    /**
     * @param  Builder<FormSubmissionActionFailure>  $query
     * @return Builder<FormSubmissionActionFailure>
     */
    protected function scopeOpen(Builder $query): Builder
    {
        return $query->whereNull('resolved_at')->whereNull('dismissed_at');
    }

    /**
     * @param  Builder<FormSubmissionActionFailure>  $query
     * @return Builder<FormSubmissionActionFailure>
     */
    protected function scopeResolved(Builder $query): Builder
    {
        return $query->whereNotNull('resolved_at');
    }

    /**
     * @param  Builder<FormSubmissionActionFailure>  $query
     * @return Builder<FormSubmissionActionFailure>
     */
    protected function scopeDismissed(Builder $query): Builder
    {
        return $query->whereNotNull('dismissed_at');
    }

    public function isOpen(): bool
    {
        return $this->resolved_at === null && $this->dismissed_at === null;
    }

    public function canBeRetried(): bool
    {
        return $this->dismissed_at === null;
    }
}