<?php

declare(strict_types=1);

namespace Domain\Repository;

// @responsibility: Interface für Chunk-Persistenz (Text-Chunks aus Dokumenten)

interface ChunkRepositoryInterface
{
    /**
     * Holt Chunk-Statistiken.
     *
     * @return array{total: int, tokens: int, embedded: int}
     */
    public function getStats(): array;

    /**
     * Holt die neuesten Chunks.
     *
     * @return array<int, array{id: int, content: string, token_count: int, created_at: string, qdrant_id: ?string, filename: string}>
     */
    public function findRecent(int $limit = 5): array;

    /**
     * Holt alle Chunks für ein Dokument.
     *
     * @return array<int, array{id: int, chunk_index: int, content: string, token_count: int, heading_path: ?string, metadata: ?string, qdrant_id: ?string, created_at: string}>
     */
    public function findByDocument(int $documentId): array;

    /**
     * Holt gefilterte Chunks mit Pagination.
     *
     * @return array<int, array>
     */
    public function findFiltered(string $search = '', string $embedded = '', int $limit = 50, int $offset = 0): array;

    /**
     * Zählt Chunks nach Filter-Kriterien.
     */
    public function count(string $search = '', string $embedded = ''): int;

    /**
     * Findet einen Chunk nach ID mit Document-Info.
     *
     * @return array|null
     */
    public function find(int $id): ?array;

    /**
     * Findet einen Chunk nach Document-ID und Index.
     *
     * @return array{id: int, chunk_index: int}|null
     */
    public function findByDocumentAndIndex(int $documentId, int $chunkIndex): ?array;

    /**
     * Holt Entitäten für einen Chunk (Graceful Degradation: leeres Array wenn keine).
     *
     * @return array<int, array{id: int, name: string, type: string, relevance_score: float}>
     */
    public function getChunkEntities(int $chunkId): array;

    /**
     * Holt Taxonomie-Mappings für einen Chunk (Graceful Degradation: leeres Array wenn keine).
     *
     * @return array<int, array{term_id: int, term_name: string, term_path: string, confidence: float}>
     */
    public function getChunkTaxonomy(int $chunkId): array;

    /**
     * Findet Chunks die eine bestimmte Entität enthalten.
     *
     * @return array<int, array{chunk_id: int, content: string, relevance_score: float}>
     */
    public function findChunksByEntity(int $entityId, int $limit = 10): array;
}