<?php

declare(strict_types=1);

namespace Domain\Repository;

// @responsibility: Interface für Entity-Taxonomie-Mapping Persistenz

use Domain\Constants;
use Domain\Entity\EntityTaxonomyMapping;

interface EntityTaxonomyRepositoryInterface
{
    /**
     * Findet alle Taxonomie-Mappings für eine Entity.
     *
     * @return array<EntityTaxonomyMapping>
     */
    public function findByEntityId(int $entityId): array;

    /**
     * Findet alle Entities, die einem Taxonomie-Begriff zugeordnet sind.
     *
     * @return array<array{entity_id: int, relevance: float, validated: bool}>
     */
    public function findByTaxonomyTermId(int $termId): array;

    /**
     * Speichert ein Entity-Taxonomie-Mapping.
     */
    public function save(EntityTaxonomyMapping $mapping): int;

    /**
     * Löscht ein Mapping nach ID.
     */
    public function delete(int $id): bool;

    /**
     * Löscht alle Mappings für eine Entity.
     */
    public function deleteByEntityId(int $entityId): int;

    /**
     * Findet unvalidierte Mappings zur manuellen Prüfung.
     *
     * @return array<EntityTaxonomyMapping>
     */
    public function getUnvalidatedMappings(int $limit = 100): array;

    /**
     * Markiert ein Mapping als validiert.
     */
    public function markAsValidated(int $id): bool;

    /**
     * Prüft ob ein Mapping existiert.
     */
    public function exists(int $entityId, int $taxonomyTermId): bool;

    /**
     * Holt Statistiken über Validierungsstatus.
     *
     * @return array{total: int, validated: int, pending: int}
     */
    public function getValidationStats(): array;
}