feat(form-builder): retry/resolve/dismiss artisan commands (WS-6)

Three CLI commands for ops use, mirroring the API endpoints in Task 9: - form-failures:retry (id|submission|org filter, --dry-run) - form-failures:resolve (single id, optional note) - form-failures:dismiss (single id, DismissalReasonType + note) Cross-tenant isolation enforced via form_submissions.organisation_id FK chain (RFC V3). retry_count incremented on retry; failure history preserved (new row on repeat failure, not in-place mutation). Refs: RFC-WS-6.md §3 (Q5), §4 (V2, V3) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 14:25:16 +02:00
parent 0b14416e28
commit 84d57c5bbc
4 changed files with 405 additions and 0 deletions
--- a/api/app/Console/Commands/RetryFormSubmissionActionFailures.php
+++ b/api/app/Console/Commands/RetryFormSubmissionActionFailures.php
@@ -0,0 +1,142 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Enums\FormBuilder\ApplyStatus;
+use App\FormBuilder\Bindings\FormBindingApplicator;
+use App\Models\FormBuilder\FormSubmission;
+use App\Models\FormBuilder\FormSubmissionActionFailure;
+use Illuminate\Console\Command;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Facades\DB;
+use Throwable;
+
+/**
+ * RFC-WS-6 §3 (Q5) — replay open failures via the applicator.
+ * Mirrors the API endpoint (Task 9). Cross-tenant safety via FK chain
+ * to form_submissions.organisation_id.
+ */
+final class RetryFormSubmissionActionFailures extends Command
+{
+    protected $signature = 'form-failures:retry
+        {--id=        : Specific FormSubmissionActionFailure ULID}
+        {--submission= : Retry all open failures for a submission}
+        {--org=       : Retry all open failures across an organisation}
+        {--listener=  : Filter by listener_class FQCN}
+        {--dry-run    : List what would be retried without doing it}';
+
+    protected $description = 'Replay open FormSubmissionActionFailure rows via the applicator';
+
+    public function handle(FormBindingApplicator $applicator): int
+    {
+        if (
+            $this->option('id') === null
+            && $this->option('submission') === null
+            && $this->option('org') === null
+        ) {
+            $this->error('At least one of --id, --submission, or --org is required.');
+
+            return self::FAILURE;
+        }
+
+        $query = $this->buildQuery();
+        $failures = $query->get();
+
+        if ($failures->isEmpty()) {
+            $this->info('No matching open failures.');
+
+            return self::SUCCESS;
+        }
+
+        $rows = [];
+        foreach ($failures as $failure) {
+            if ($this->option('dry-run')) {
+                $rows[] = ['id' => (string) $failure->id, 'submission' => (string) $failure->form_submission_id, 'result' => 'would-retry'];
+                continue;
+            }
+
+            $rows[] = $this->retryOne($failure, $applicator);
+        }
+
+        $this->table(['id', 'submission', 'result'], $rows);
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * @return Builder<FormSubmissionActionFailure>
+     */
+    private function buildQuery(): Builder
+    {
+        $query = FormSubmissionActionFailure::query()->open();
+
+        if (($id = $this->option('id')) !== null) {
+            $query->where('id', $id);
+        }
+        if (($submissionId = $this->option('submission')) !== null) {
+            $query->where('form_submission_id', $submissionId);
+        }
+        if (($listener = $this->option('listener')) !== null) {
+            $query->where('listener_class', $listener);
+        }
+        if (($org = $this->option('org')) !== null) {
+            // FK chain: failure → submission → organisation.
+            $query->whereHas('submission', function (Builder $q) use ($org): void {
+                /** @var Builder<\App\Models\FormBuilder\FormSubmission> $q */
+                $q->where('organisation_id', $org);
+            });
+        }
+
+        return $query;
+    }
+
+    /**
+     * @return array{id:string, submission:string, result:string}
+     */
+    private function retryOne(FormSubmissionActionFailure $failure, FormBindingApplicator $applicator): array
+    {
+        $submission = FormSubmission::query()->withoutGlobalScopes()->find($failure->form_submission_id);
+        if ($submission === null) {
+            return ['id' => (string) $failure->id, 'submission' => (string) $failure->form_submission_id, 'result' => 'submission-gone'];
+        }
+
+        try {
+            DB::transaction(function () use ($applicator, $submission): void {
+                $result = $applicator->apply($submission);
+                FormSubmission::query()
+                    ->whereKey($submission->id)
+                    ->update([
+                        'apply_status' => $result->applyStatus()->value,
+                        'apply_completed_at' => now(),
+                    ]);
+            });
+            $failure->retry_count = (int) $failure->retry_count + 1;
+            $failure->resolved_at = now();
+            $failure->save();
+
+            return ['id' => (string) $failure->id, 'submission' => (string) $submission->id, 'result' => 'succeeded'];
+        } catch (Throwable $e) {
+            // Append a NEW row preserving history, increment retry_count on original.
+            DB::transaction(function () use ($failure, $submission, $e): void {
+                FormSubmissionActionFailure::query()->create([
+                    'form_submission_id' => $submission->id,
+                    'listener_class' => $failure->listener_class,
+                    'failed_at' => now(),
+                    'exception_class' => $e::class,
+                    'exception_message' => $e->getMessage(),
+                    'context' => ['retry_of' => (string) $failure->id],
+                ]);
+                FormSubmissionActionFailure::query()
+                    ->whereKey($failure->id)
+                    ->update(['retry_count' => (int) $failure->retry_count + 1]);
+                FormSubmission::query()
+                    ->whereKey($submission->id)
+                    ->update(['apply_status' => ApplyStatus::FAILED->value]);
+            });
+
+            return ['id' => (string) $failure->id, 'submission' => (string) $submission->id, 'result' => 'failed-again'];
+        }
+    }
+}