<?php

namespace App\Interfaces;

use App\Models\Resume;
use App\Models\User;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;

/**
 * Resume Repository Interface
 * 
 * Defines the contract for resume-specific data operations.
 * Extends the base repository with resume-specific methods.
 * 
 * @author David Valera Melendez <david@valera-melendez.de>
 * @since February  2025
 */
interface ResumeRepositoryInterface extends BaseRepositoryInterface
{
    /**
     * Get user's resumes
     *
     * @param int $userId
     * @param array $columns
     * @return Collection
     */
    public function getUserResumes(int $userId, array $columns = ['*']): Collection;

    /**
     * Get user's resumes with pagination
     *
     * @param int $userId
     * @param int $perPage
     * @return LengthAwarePaginator
     */
    public function getPaginatedUserResumes(int $userId, int $perPage = 10): LengthAwarePaginator;

    /**
     * Find resume by public URL
     *
     * @param string $publicUrl
     * @return Resume|null
     */
    public function findByPublicUrl(string $publicUrl): ?Resume;

    /**
     * Get public resumes
     *
     * @param int $limit
     * @return Collection
     */
    public function getPublicResumes(int $limit = 20): Collection;

    /**
     * Get resumes by template
     *
     * @param string $template
     * @return Collection
     */
    public function getResumesByTemplate(string $template): Collection;

    /**
     * Get resumes by status
     *
     * @param string $status
     * @return Collection
     */
    public function getResumesByStatus(string $status): Collection;

    /**
     * Get popular resumes (most viewed)
     *
     * @param int $limit
     * @param int $days
     * @return Collection
     */
    public function getPopularResumes(int $limit = 10, int $days = 30): Collection;

    /**
     * Get recent resumes
     *
     * @param int $limit
     * @param int $days
     * @return Collection
     */
    public function getRecentResumes(int $limit = 10, int $days = 7): Collection;

    /**
     * Search resumes
     *
     * @param string $query
     * @param array $filters
     * @param int $limit
     * @return Collection
     */
    public function searchResumes(string $query, array $filters = [], int $limit = 20): Collection;

    /**
     * Get incomplete resumes
     *
     * @param int $threshold
     * @return Collection
     */
    public function getIncompleteResumes(int $threshold = 50): Collection;

    /**
     * Duplicate resume for user
     *
     * @param int $resumeId
     * @param int $userId
     * @param string $newTitle
     * @return Resume
     */
    public function duplicateResume(int $resumeId, int $userId, string $newTitle): Resume;

    /**
     * Update resume view count
     *
     * @param int $resumeId
     * @return bool
     */
    public function incrementViewCount(int $resumeId): bool;

    /**
     * Update resume download count
     *
     * @param int $resumeId
     * @return bool
     */
    public function incrementDownloadCount(int $resumeId): bool;

    /**
     * Get resume statistics
     *
     * @param int|null $userId
     * @return array
     */
    public function getResumeStatistics(?int $userId = null): array;

    /**
     * Get resumes requiring PDF regeneration
     *
     * @return Collection
     */
    public function getResumesNeedingPdfRegeneration(): Collection;

    /**
     * Archive old resumes
     *
     * @param int $days
     * @return int Number of archived resumes
     */
    public function archiveOldResumes(int $days = 365): int;

    /**
     * Get user's resume by title
     *
     * @param int $userId
     * @param string $title
     * @return Resume|null
     */
    public function getUserResumeByTitle(int $userId, string $title): ?Resume;

    /**
     * Check if user can create more resumes
     *
     * @param int $userId
     * @param int $limit
     * @return bool
     */
    public function canUserCreateMoreResumes(int $userId, int $limit = 10): bool;

    /**
     * Get featured resumes for showcase
     *
     * @param int $limit
     * @return Collection
     */
    public function getFeaturedResumes(int $limit = 6): Collection;

    /**
     * Update resume completion percentage
     *
     * @param int $resumeId
     * @return bool
     */
    public function updateCompletionPercentage(int $resumeId): bool;

    /**
     * Get resumes expiring soon
     *
     * @param int $days
     * @return Collection
     */
    public function getResumesExpiringSoon(int $days = 7): Collection;

    /**
     * Bulk update resume status
     *
     * @param array $resumeIds
     * @param string $status
     * @return int Number of updated resumes
     */
    public function bulkUpdateStatus(array $resumeIds, string $status): int;
}