crewli/api/app/Services/FormBuilder/FormFailureRetryService.php

<?php

declare(strict_types=1);

namespace App\Services\FormBuilder;

use App\Enums\FormBuilder\ApplyStatus;
use App\Exceptions\FormBuilder\FailureNotRetriableException;
use App\Exceptions\FormBuilder\ParentSubmissionGoneException;
use App\FormBuilder\Bindings\FormBindingApplicator;
use App\FormBuilder\Bindings\FormBindingExceptionClassifier;
use App\Models\FormBuilder\FormSubmission;
use App\Models\FormBuilder\FormSubmissionActionFailure;
use App\Models\FormBuilder\FormSubmissionActionFailureRetryAttempt;
use App\Models\User;
use Illuminate\Support\Facades\DB;
use Throwable;

/**
 * RFC-WS-6 §3 (Q5) sessie 3c — centralised retry-flow logic.
 *
 * The controller's `retry` action AND the artisan command both delegate
 * here so the per-attempt record write stays consistent across paths.
 *
 * Flow:
 *   1. canBeRetried() guard (open = resolved_at IS NULL AND dismissed_at IS NULL)
 *   2. Run the applicator inside a transaction
 *   3. On success: write retry_attempt(outcome=succeeded), increment
 *      retry_count, set resolved_at + system note + resolved_by_user_id
 *   4. On failure: write retry_attempt(outcome=failed) with the NEW
 *      exception details, increment retry_count. Parent's own
 *      exception_class / exception_message stay audit-immutable —
 *      they represent the FIRST failure.
 *
 * v1.3-delta D2 (per ARCH-BINDINGS §7.1 v1.2 + RFC-WS-6 §Q3 v1.3 addition 2):
 *   - recordFailure now mirrors ApplyBindingsOnFormSubmit's outer-txn path:
 *     writes failure_response_code via FormBindingExceptionClassifier and
 *     apply_completed_at = now() (closes the asymmetry where the listener
 *     wrote this column on both happy and failure paths but the retry
 *     service only wrote it on the success path).
 */
final readonly class FormFailureRetryService
{
    public function __construct(private FormBindingApplicator $applicator) {}

    /**
     * @return array{outcome: 'succeeded'|'failed', attempt: FormSubmissionActionFailureRetryAttempt}
     *
     * @throws FailureNotRetriableException
     * @throws ParentSubmissionGoneException
     */
    public function retry(FormSubmissionActionFailure $failure, ?User $actor = null): array
    {
        if (! $failure->canBeRetried()) {
            throw new FailureNotRetriableException($failure->resolved_at !== null ? 'resolved' : 'dismissed');
        }

        /** @var FormSubmission|null $submission */
        $submission = FormSubmission::query()->withoutGlobalScopes()->find($failure->form_submission_id);
        if ($submission === null) {
            throw new ParentSubmissionGoneException;
        }

        try {
            DB::transaction(function () use ($submission): void {
                $result = $this->applicator->apply($submission);
                FormSubmission::query()
                    ->whereKey($submission->id)
                    ->update([
                        'apply_status' => $result->applyStatus()->value,
                        'apply_completed_at' => now(),
                    ]);
            });

            $attempt = $this->recordSuccess($failure, $actor);

            return ['outcome' => 'succeeded', 'attempt' => $attempt];
        } catch (Throwable $e) {
            $attempt = $this->recordFailure($failure, $submission, $actor, $e);

            return ['outcome' => 'failed', 'attempt' => $attempt];
        }
    }

    private function recordSuccess(FormSubmissionActionFailure $failure, ?User $actor): FormSubmissionActionFailureRetryAttempt
    {
        return DB::transaction(function () use ($failure, $actor): FormSubmissionActionFailureRetryAttempt {
            /** @var FormSubmissionActionFailureRetryAttempt $attempt */
            $attempt = FormSubmissionActionFailureRetryAttempt::query()->create([
                'form_submission_action_failure_id' => $failure->id,
                'attempted_at' => now(),
                'attempted_by_user_id' => $actor?->id,
                'outcome' => 'succeeded',
                'exception_class' => null,
                'exception_message' => null,
            ]);

            $note = $actor instanceof User
                ? "Geslaagde retry door {$actor->name}"
                : 'Geslaagde retry (geautomatiseerd)';

            FormSubmissionActionFailure::query()
                ->whereKey($failure->id)
                ->update([
                    'retry_count' => DB::raw('retry_count + 1'),
                    'resolved_at' => now(),
                    'resolved_by_user_id' => $actor?->id,
                    'resolved_note' => $note,
                ]);

            return $attempt;
        });
    }

    private function recordFailure(
        FormSubmissionActionFailure $failure,
        FormSubmission $submission,
        ?User $actor,
        Throwable $e,
    ): FormSubmissionActionFailureRetryAttempt {
        return DB::transaction(function () use ($failure, $submission, $actor, $e): FormSubmissionActionFailureRetryAttempt {
            /** @var FormSubmissionActionFailureRetryAttempt $attempt */
            $attempt = FormSubmissionActionFailureRetryAttempt::query()->create([
                'form_submission_action_failure_id' => $failure->id,
                'attempted_at' => now(),
                'attempted_by_user_id' => $actor?->id,
                'outcome' => 'failed',
                'exception_class' => $e::class,
                'exception_message' => $e->getMessage(),
            ]);

            FormSubmissionActionFailure::query()
                ->whereKey($failure->id)
                ->update(['retry_count' => DB::raw('retry_count + 1')]);

            // Per ARCH-BINDINGS §7.1 v1.2 retry-service asymmetry note +
            // RFC-WS-6 §Q3 v1.3 addition 2 — mirror ApplyBindingsOnFormSubmit's
            // outer-transaction failure path: same failure_response_code
            // classifier + apply_completed_at write. Single behaviour-change
            // point per the v1.3-delta D1 design.
            FormSubmission::query()
                ->whereKey($submission->id)
                ->update([
                    'apply_status' => ApplyStatus::FAILED->value,
                    'apply_completed_at' => now(),
                    'failure_response_code' => FormBindingExceptionClassifier::classify($e),
                ]);

            return $attempt;
        });
    }
}