<?php

declare(strict_types=1);

namespace Domain\Repository;

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

use Domain\Entity\ChunkTaxonomyMapping;

interface ChunkTaxonomyRepositoryInterface
{
    /**
     * Findet alle Taxonomie-Mappings für einen Chunk.
     *
     * @return array<ChunkTaxonomyMapping>
     */
    public function findByChunkId(int $chunkId): array;

    /**
     * Findet alle Chunks, die einem Taxonomie-Begriff zugeordnet sind.
     *
     * @return array<array{chunk_id: int, confidence: float, source: string}>
     */
    public function findByTaxonomyTermId(int $termId): array;

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

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

    /**
     * Löscht alle Mappings für einen Chunk.
     */
    public function deleteByChunkId(int $chunkId): int;

    /**
     * Findet Chunks ohne Taxonomie-Mapping.
     *
     * @return array<array{id: int, document_id: int, content: string}>
     */
    public function getUnmappedChunks(int $limit = 100): array;

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

    /**
     * Zählt Mappings pro Taxonomie-Begriff.
     *
     * @return array<int, int> [term_id => count]
     */
    public function countByTaxonomyTerm(): array;
}