Deduplicate validation persistence in ValidateArtifactJob

Extract ArtifactValidationPersister for shared KOSIT record+attach logic;
veraPDF verdicts persist via supplemental closures so the shared seam
does not type-hint optional validator packages. Closes mooxphp/e-billing#7.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jbagsik

packages/e-billing/CHANGELOG.md

@@ -11,6 +11,7 @@
 
 ### Changed
 
+- Deduplicated KOSIT/veraPDF validation persistence in `ValidateArtifactJob` via `ArtifactValidationPersister`; supplemental verdicts (veraPDF) stay as closures so the shared seam does not type-hint optional validator packages. No behaviour change.
 - Replaced `GenerateXmlJob` / `ValidateXmlJob` / `MergeZugferdPdfJob` with `GenerateArtifactJob` → `ValidateArtifactJob` (generate-first pipeline).
 - `gateway_status` enum is now format-agnostic: `generating`, `generation_failed`, `validating`, `validated`, `validation_failed`, `validator_error`, `ignored_foreign`.
 - Hybrid ZUGFeRD artifacts are built before validation; deliverable PDFs are unencrypted; `artifact_content_hash` is populated on validation pass.

packages/e-billing/src/Jobs/ValidateArtifactJob.php

@@ -22,6 +22,7 @@
 use Moox\EBilling\Formats\FormatRegistry;
 use Moox\EBilling\Models\EbillingDocument;
 use Moox\EBilling\Services\InboxMessagePipelineFinalizer;
+use Moox\EBilling\Support\ArtifactValidationPersister;
 use Moox\EBilling\Support\EBillingArtifactNaming;
 use Moox\Jobs\Traits\JobProgress;
 use Moox\KositValidator\Actions\RecordKositValidation;
@@ -61,6 +62,7 @@ public function handle(
         RecordKositValidation $recordKositValidation,
         VeraPdfService $veraPdf,
         RecordVeraPdfValidation $recordVeraPdfValidation,
+        ArtifactValidationPersister $validationPersister,
         InboxMessagePipelineFinalizer $pipelineFinalizer,
     ): void {
         $this->setProgress(0);
@@ -190,6 +192,11 @@ public function handle(
                 ($veraPdfResult !== null && ! $veraPdfPassed) ? $veraPdfResult->errors() : [],
             ));
 
+            $supplementalPersisters = $this->supplementalValidationPersisters(
+                $veraPdfResult,
+                $recordVeraPdfValidation,
+            );
+
             if ($passed) {
                 $deliverablePath = $document?->deliverableStoragePath($definition->artifactKind);
                 if ($deliverablePath === null || $deliverablePath === '') {
@@ -204,24 +211,22 @@ public function handle(
                 $hash = hash('sha256', $artifactContent);
 
                 DB::transaction(function () use (
+                    $validationPersister,
                     $recordKositValidation,
-                    $recordVeraPdfValidation,
                     $kositResult,
-                    $veraPdfResult,
+                    $supplementalPersisters,
                     $document,
                     $attachment,
                     $hash,
                 ): void {
-                    $kositValidation = $recordKositValidation($kositResult);
+                    $validationPersister->persist(
+                        $document,
+                        $kositResult,
+                        $recordKositValidation,
+                        $supplementalPersisters,
+                    );
 
                     if ($document !== null) {
-                        $document->kositValidations()->attach($kositValidation->id);
-
-                        if ($veraPdfResult instanceof VeraPdfResult) {
-                            $veraPdfValidation = $recordVeraPdfValidation($veraPdfResult);
-                            $document->veraPdfValidations()->attach($veraPdfValidation->id);
-                        }
-
                         $document->artifact_content_hash = $hash;
                         $document->gateway_status = EBillingAttachmentProcessingStatus::Validated;
                         $document->processed_at = now();
@@ -236,24 +241,22 @@ public function handle(
                 $failureMessage = $errorStrings !== [] ? implode('; ', $errorStrings) : 'Artifact validation failed';
 
                 DB::transaction(function () use (
+                    $validationPersister,
                     $recordKositValidation,
-                    $recordVeraPdfValidation,
                     $kositResult,
-                    $veraPdfResult,
+                    $supplementalPersisters,
                     $attachment,
                     $document,
                     $failureMessage,
                 ): void {
-                    $kositValidation = $recordKositValidation($kositResult);
+                    $validationPersister->persist(
+                        $document,
+                        $kositResult,
+                        $recordKositValidation,
+                        $supplementalPersisters,
+                    );
 
                     if ($document !== null) {
-                        $document->kositValidations()->attach($kositValidation->id);
-
-                        if ($veraPdfResult instanceof VeraPdfResult) {
-                            $veraPdfValidation = $recordVeraPdfValidation($veraPdfResult);
-                            $document->veraPdfValidations()->attach($veraPdfValidation->id);
-                        }
-
                         $document->gateway_status = EBillingAttachmentProcessingStatus::ValidationFailed;
                         $document->save();
                     }
@@ -276,6 +279,25 @@ public function handle(
         $this->setProgress(100);
     }
 
+    /**
+     * @return list<\Closure(EbillingDocument): void>
+     */
+    private function supplementalValidationPersisters(
+        mixed $veraPdfResult,
+        RecordVeraPdfValidation $recordVeraPdfValidation,
+    ): array {
+        if (! $veraPdfResult instanceof VeraPdfResult) {
+            return [];
+        }
+
+        return [
+            static function (EbillingDocument $document) use ($veraPdfResult, $recordVeraPdfValidation): void {
+                $veraPdfValidation = $recordVeraPdfValidation($veraPdfResult);
+                $document->veraPdfValidations()->attach($veraPdfValidation->id);
+            },
+        ];
+    }
+
     public function failed(?Throwable $exception = null): void
     {
         $attachment = InboxAttachment::query()->find($this->inboxAttachmentId);

packages/e-billing/src/Support/ArtifactValidationPersister.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Moox\EBilling\Support;
+
+use Closure;
+use Moox\EBilling\Models\EbillingDocument;
+use Moox\KositValidator\Actions\RecordKositValidation;
+use Moox\KositValidator\DTOs\KositResult;
+
+final class ArtifactValidationPersister
+{
+    /**
+     * Persist KOSIT verdict and attach optional supplemental verdicts (e.g. veraPDF via closure).
+     *
+     * Supplemental persisters stay outside this class so e-billing does not type-hint optional
+     * validator packages in the shared persistence seam.
+     *
+     * @param  list<Closure(EbillingDocument): void>  $supplementalPersisters
+     */
+    public function persist(
+        ?EbillingDocument $document,
+        KositResult $kositResult,
+        RecordKositValidation $recordKositValidation,
+        array $supplementalPersisters = [],
+    ): void {
+        $kositValidation = $recordKositValidation($kositResult);
+
+        if ($document === null) {
+            return;
+        }
+
+        $document->kositValidations()->attach($kositValidation->id);
+
+        foreach ($supplementalPersisters as $persistSupplemental) {
+            $persistSupplemental($document);
+        }
+    }
+}

packages/e-billing/tests/Feature/Jobs/GenerateThenValidateArtifactJobTest.php

@@ -14,6 +14,7 @@
 use Moox\EBilling\Formats\FormatRegistry;
 use Moox\EBilling\Jobs\ValidateArtifactJob;
 use Moox\EBilling\Services\InboxMessagePipelineFinalizer;
+use Moox\EBilling\Support\ArtifactValidationPersister;
 use Moox\EBilling\Tests\Support\InvoiceFixtures;
 use Moox\EBilling\Tests\Support\PipelineFixtures;
 use Moox\EBilling\Tests\TestCase;
@@ -113,6 +114,7 @@ function runValidateArtifactJob(int $attachmentId): void
         app(RecordKositValidation::class),
         app(VeraPdfService::class),
         app(RecordVeraPdfValidation::class),
+        app(ArtifactValidationPersister::class),
         app(InboxMessagePipelineFinalizer::class),
     );
 }