<?php

declare(strict_types=1);

namespace App\Domain\Shared\Domain\Contract;

/**
 * Service centralisé de gestion des chemins et de l'enregistrement des fichiers
 * liés aux mangas (manga/volume/chapter) et des archives CBZ.
 */
interface MangaPathManagerInterface
{
    /**
     * Retourne (et crée si nécessaire) le dossier du manga.
     */
    public function getMangaDirectory(string $mangaTitle, string $publicationYear): string;

    /**
     * Retourne (et crée si nécessaire) le dossier du volume.
     */
    public function getVolumeDirectory(string $mangaTitle, string $publicationYear, int $volumeNumber): string;

    /**
     * Construit (et garantit l'existence des dossiers) le chemin complet d'un CBZ de chapitre.
     */
    public function buildChapterCbzPath(string $mangaTitle, string $publicationYear, int $volumeNumber, string $chapterNumber): string;

    /**
     * Construit (et garantit l'existence des dossiers) le chemin complet d'un CBZ de volume.
     */
    public function buildVolumeCbzPath(string $mangaTitle, string $publicationYear, int $volumeNumber): string;

    /**
     * Crée une archive CBZ à partir d'une liste de fichiers et l'écrit au chemin fourni.
     *
     * @param array<int, string> $files Chemins absolus des fichiers à packager
     */
    public function createCbzArchive(array $files, string $cbzPath): void;

    /**
     * Déplace un fichier existant vers une destination. Crée les dossiers si nécessaire.
     */
    public function moveFileTo(string $sourcePath, string $destinationPath): void;

    /**
     * Indique si un fichier existe et est lisible.
     */
    public function fileExists(string $path): bool;
}
