bert.hausmans/crewli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(form-builder): retry history table + integration (WS-6)

Browse Source 
Per-attempt retry history (timestamp, user, outcome, exception detail
if failed) replaces the counter-only retry_count tracking.

Changes:

- New `form_submission_action_failure_retry_attempts` table (cascade on
  parent delete, nullOnDelete on user). Explicit short FK names
  (`fsafra_failure_fk`, `fsafra_user_fk`) — auto-generated names exceed
  MySQL's 64-char identifier limit.
- New FormSubmissionActionFailureRetryAttempt model + factory +
  succeeded() state.
- Parent FormSubmissionActionFailure gets retryAttempts() HasMany
  relation (latest('attempted_at')).
- New FormFailureRetryService centralises the retry-flow logic. Both
  the API controller and the artisan command delegate to it. Service
  writes a retry_attempt record per attempt; parent's retry_count
  stays as denormalised cache for index-view performance.
- Successful retry: attempt(succeeded) + parent.retry_count++ +
  parent.resolved_at + parent.resolved_by_user_id + parent.resolved_note
  ("Geslaagde retry door {actor.name}" or "Geslaagde retry
  (geautomatiseerd)" for command-line invocation without an actor).
- Failed retry: attempt(failed) with NEW exception details +
  parent.retry_count++. Parent's exception_class/_message stay
  audit-immutable — they represent the FIRST failure.
- canBeRetried() now correctly checks both resolved_at AND
  dismissed_at (sessie 2's open question Q2 closure).
- New FailureNotRetriableException (controller → 422) and
  ParentSubmissionGoneException (controller → 410) for cleaner
  flow control.

12 new tests:
- FormSubmissionActionFailureRetryAttemptTest (5 unit tests)
- RetryFlowProducesRetryAttemptsTest (7 integration tests covering
  succeeded path, failed path, resolved/dismissed blocking,
  multiple-retries chronological ordering, canBeRetried truth tables)

Pre-existing tests touched:
- FormSubmissionActionFailureTest::test_can_be_retried_only_for_open_state
  — updated to reflect Q2 closure (resolved now blocks too).
- Ws6FoundationMigrationTest::test_down_methods_clean_up_columns_and_table
  — child table must drop before parent (FK constraint).
- 5 backfill test step-counts bumped +1 (new migration sits at top).

SCHEMA.md → v2.9. Schema dump regenerated.

Refs: RFC-WS-6.md §3 Q5 addendum, sessie 2 Q2

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
bert.hausmans
2026-04-28 22:53:36 +02:00
parent acd7cf5ec8
commit b47e096a55
20 changed files with 767 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
api/app/Services/FormBuilder/FormFailureRetryService.php Normal file
View File

@@ -0,0 +1,135 @@
<?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\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.
*/
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')]);
FormSubmission::query()
->whereKey($submission->id)
->update(['apply_status' => ApplyStatus::FAILED->value]);
return $attempt;
});
}
}