<?php

declare(strict_types=1);

namespace Domain\Repository;

// @responsibility: Interface für Ontology-Persistenz (CRUD + Klassenhierarchie)

interface OntologyRepositoryInterface
{
    /**
     * Holt alle Ontologie-Klassen mit Statistiken.
     *
     * @return array<int, array{id: int, name: string, parent_class_id: ?int, description: ?string, properties: ?string, entity_count: int, subclass_count: int}>
     */
    public function findAll(): array;

    /**
     * Holt Ontologie-Statistiken.
     *
     * @return array{total_classes: int, root_classes: int, classified_entities: int}
     */
    public function getStats(): array;

    /**
     * Findet eine Klasse nach ID.
     *
     * @return array{id: int, name: string, parent_class_id: ?int, description: ?string, properties: ?string}|null
     */
    public function find(int $id): ?array;

    /**
     * Erstellt eine neue Ontologie-Klasse.
     *
     * @param array<string, mixed> $properties JSON-Properties
     * @return int ID der neuen Klasse
     */
    public function create(string $name, ?int $parentId = null, ?string $description = null, array $properties = []): int;

    /**
     * Aktualisiert eine Ontologie-Klasse.
     *
     * @param array<string, mixed> $properties JSON-Properties
     */
    public function update(int $id, string $name, ?int $parentId = null, ?string $description = null, array $properties = []): bool;

    /**
     * Löscht eine Ontologie-Klasse (nur wenn keine Subklassen vorhanden).
     *
     * @return bool False wenn Subklassen vorhanden, True bei Erfolg
     */
    public function delete(int $id): bool;

    /**
     * Holt Klassen für Select-Dropdown (minimale Daten).
     *
     * @return array<int, array{id: int, name: string}>
     */
    public function findForSelect(): array;
}