<?php

namespace Modules\ProductCompat\Entities\Enrichment;

/**
 * Value object returned by every enrichment provider.
 *
 * candidates shape:
 *   [
 *     'part_numbers'  => [ ['value' => 'BT.00603.006', 'type' => 'oem', 'confidence' => 70], ... ],
 *     'device_models' => [ ['brand' => 'Acer', 'series' => 'Aspire', 'model' => '5570', 'confidence' => 70], ... ],
 *   ]
 *
 * rich shape (optional — the aggressive/AI pipeline reads it; classic
 * enrichProduct() ignores it, so existing providers are unaffected):
 *   [
 *     'description'  => 'string',
 *     'brand'        => 'string',
 *     'specs'        => [ ['label' => 'Capacity', 'value' => '4400mAh'], ... ],
 *     'image_urls'   => ['https://…', …],
 *     'source_texts' => ['title / description harvested for the AI pass', …],
 *   ]
 */
class EnrichmentResult
{
    public bool $ok;
    public array $candidates;
    public mixed $raw;
    public ?string $message;
    public array $rich;

    public function __construct(bool $ok, array $candidates = [], mixed $raw = null, ?string $message = null, array $rich = [])
    {
        $this->ok = $ok;
        $this->candidates = [
            'part_numbers'  => $candidates['part_numbers']  ?? [],
            'device_models' => $candidates['device_models'] ?? [],
            'barcodes'      => $candidates['barcodes']      ?? [],
        ];
        $this->raw = $raw;
        $this->message = $message;
        $this->rich = $rich;
    }

    public function hasCandidates(): bool
    {
        return ! empty($this->candidates['part_numbers'])
            || ! empty($this->candidates['device_models'])
            || ! empty($this->candidates['barcodes']);
    }

    public static function fail(string $message, mixed $raw = null): self
    {
        return new self(false, [], $raw, $message);
    }

    public static function empty(mixed $raw = null): self
    {
        return new self(true, [], $raw, 'no candidates');
    }
}
