<?php

namespace AIPT\Api\AutomationJobs\Interfaces;

use AIPT\Api\AutomationJobs\Models\JobLog;

/**
 * Job Logger Interface
 * 
 * Defines contract for job logging implementations
 * Following Interface Segregation and Dependency Inversion principles
 * 
 * @since 2.3.0
 */
interface JobLoggerInterface {
    
    /**
     * Log an info message
     * 
     * @param int $job_id Job ID
     * @param string $message Log message
     * @param array $context Additional context data
     * @return bool Success status
     */
    public function info($job_id, $message, $context = []);
    
    /**
     * Log a warning message
     * 
     * @param int $job_id Job ID
     * @param string $message Log message
     * @param array $context Additional context data
     * @return bool Success status
     */
    public function warning($job_id, $message, $context = []);
    
    /**
     * Log an error message
     * 
     * @param int $job_id Job ID
     * @param string $message Log message
     * @param array $context Additional context data
     * @return bool Success status
     */
    public function error($job_id, $message, $context = []);
    
    /**
     * Log a debug message
     * 
     * @param int $job_id Job ID
     * @param string $message Log message
     * @param array $context Additional context data
     * @return bool Success status
     */
    public function debug($job_id, $message, $context = []);
    
    /**
     * Get logs for a job
     * 
     * @param int $job_id Job ID
     * @param array $filters Filters (level, limit, offset)
     * @return array Job logs
     */
    public function getJobLogs($job_id, $filters = []);
    
    /**
     * Get logs by level
     * 
     * @param int $job_id Job ID
     * @param string $level Log level
     * @param int $limit Maximum number of logs
     * @param int $offset Offset for pagination
     * @return array Job logs
     */
    public function getLogsByLevel($job_id, $level, $limit = 50, $offset = 0);
    
    /**
     * Clear logs for a job
     * 
     * @param int $job_id Job ID
     * @param string|null $level Optional level filter
     * @return bool Success status
     */
    public function clearJobLogs($job_id, $level = null);
    
    /**
     * Get log statistics for a job
     * 
     * @param int $job_id Job ID
     * @return array Log statistics by level
     */
    public function getLogStatistics($job_id);
    
    /**
     * Clean old logs
     * 
     * @param int $days_to_keep Number of days to keep logs
     * @return int Number of logs deleted
     */
    public function cleanOldLogs($days_to_keep = 30);
}
