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;
use Illuminate\Database\Eloquent\Relations\HasMany;

/**
 * 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',
        'exception_trace',
        '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');
    }

    /**
     * RFC-WS-6 Q5 addendum (sessie 3c) — per-attempt retry history.
     * `retry_count` on this model stays as denormalized cache; the
     * detail UI consumes this relation for per-attempt timeline.
     *
     * @return HasMany<FormSubmissionActionFailureRetryAttempt, $this>
     */
    public function retryAttempts(): HasMany
    {
        return $this->hasMany(FormSubmissionActionFailureRetryAttempt::class, 'form_submission_action_failure_id')
            ->latest('attempted_at');
    }

    /**
     * @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;
    }

    /**
     * Sessie 3c (Q2 closure): a resolved failure also blocks retry —
     * retrying a closed failure would either no-op or trigger a
     * spurious state transition. Both are unwanted. Open is the only
     * retriable state.
     */
    public function canBeRetried(): bool
    {
        return $this->resolved_at === null && $this->dismissed_at === null;
    }
}