presseportale/app/Services/Image/Precheck/ImagePrecheckResult.php

<?php

namespace App\Services\Image\Precheck;

use App\Enums\ImagePrecheckCategory;

/**
 * Rohbefund des Vorab-Checks (DU 12.4): je Kategorie `hit`, `confidence`
 * und bei technischen Mängeln eine `note`. `status` ist `ok` oder `error`;
 * bei `error` sind die Kategorien leer und `errorMessage` beschreibt den
 * Grund (Timeout, unbrauchbare Antwort, kein Schlüssel).
 */
final readonly class ImagePrecheckResult
{
    /**
     * @param  array<string, array{hit: bool, confidence: float, note: string|null}>  $categories
     * @param  array<string, mixed>  $raw
     */
    public function __construct(
        public string $status,
        public array $categories,
        public string $provider,
        public ?string $model,
        public ?string $fileSha256,
        public string $checkedAt,
        public ?string $errorMessage = null,
        public array $raw = [],
    ) {}

    /**
     * @param  array<string, array{hit: bool, confidence: float, note: string|null}>  $categories
     * @param  array<string, mixed>  $raw
     */
    public static function ok(array $categories, string $provider, ?string $model, ?string $fileSha256, array $raw = []): self
    {
        return new self('ok', self::normalize($categories), $provider, $model, $fileSha256, now()->toIso8601String(), null, $raw);
    }

    public static function error(string $message, string $provider, ?string $model, ?string $fileSha256): self
    {
        return new self('error', [], $provider, $model, $fileSha256, now()->toIso8601String(), $message);
    }

    public function isError(): bool
    {
        return $this->status !== 'ok';
    }

    public function confidence(ImagePrecheckCategory $category): float
    {
        $entry = $this->categories[$category->value] ?? null;

        if ($entry === null || ! $entry['hit']) {
            return 0.0;
        }

        return $entry['confidence'];
    }

    public function note(ImagePrecheckCategory $category): ?string
    {
        return $this->categories[$category->value]['note'] ?? null;
    }

    public function withFileSha256(string $sha256): self
    {
        return new self($this->status, $this->categories, $this->provider, $this->model, $sha256, $this->checkedAt, $this->errorMessage, $this->raw);
    }

    /**
     * @return array{status: string, categories: array<string, array{hit: bool, confidence: float, note: string|null}>, provider: string, model: string|null, file_sha256: string|null, checked_at: string, error: string|null}
     */
    public function toArray(): array
    {
        return [
            'status' => $this->status,
            'categories' => $this->categories,
            'provider' => $this->provider,
            'model' => $this->model,
            'file_sha256' => $this->fileSha256,
            'checked_at' => $this->checkedAt,
            'error' => $this->errorMessage,
        ];
    }

    /**
     * Gegenstück zu toArray() für den Komponentenzustand (Hash-Bindung
     * zwischen Vorprüfung und Speichern).
     *
     * @param  array<string, mixed>  $data
     */
    public static function fromArray(array $data): ?self
    {
        if (! isset($data['status'], $data['provider'], $data['checked_at']) || ! is_string($data['status'])) {
            return null;
        }

        return new self(
            $data['status'],
            self::normalize(is_array($data['categories'] ?? null) ? $data['categories'] : []),
            (string) $data['provider'],
            isset($data['model']) ? (string) $data['model'] : null,
            isset($data['file_sha256']) ? (string) $data['file_sha256'] : null,
            (string) $data['checked_at'],
            isset($data['error']) ? (string) $data['error'] : null,
        );
    }

    /**
     * Nur bekannte Kategorien, Konfidenz auf 0…1 begrenzt, Notiz gekürzt.
     *
     * @param  array<string, mixed>  $categories
     * @return array<string, array{hit: bool, confidence: float, note: string|null}>
     */
    private static function normalize(array $categories): array
    {
        $normalized = [];

        foreach (ImagePrecheckCategory::cases() as $category) {
            $entry = $categories[$category->value] ?? null;

            if (! is_array($entry)) {
                continue;
            }

            $confidence = isset($entry['confidence']) && is_numeric($entry['confidence']) ? (float) $entry['confidence'] : 0.0;
            // Nur ein echtes `true` zählt (Audit N20): der String "false" wäre
            // per Cast wahr. Die strikte Schemaprüfung sitzt im Treiber.
            $hit = ($entry['hit'] ?? false) === true;
            $note = isset($entry['note']) && is_string($entry['note']) && trim($entry['note']) !== '' ? mb_substr(trim($entry['note']), 0, 200) : null;

            $normalized[$category->value] = [
                'hit' => $hit,
                'confidence' => max(0.0, min(1.0, round($confidence, 3))),
                'note' => $note,
            ];
        }

        return $normalized;
    }
}