<?php

if (!defined('ABSPATH')) {
    exit;
}

/**
 * Pipeline Step Abstract Base Class
 * 
 * All pipeline steps must extend this class and implement the execute() method.
 * Provides consistent interface and common functionality for all steps.
 */
abstract class AIGH_Pipeline_Step {
    
    /**
     * @var string Unique identifier for this step type
     */
    protected $step_type = '';
    
    /**
     * @var string Display name for this step
     */
    protected $step_name = '';
    
    /**
     * @var string Description of what this step does
     */
    protected $description = '';
    
    /**
     * @var array Configuration for this step instance
     */
    protected $config = array();
    
    /**
     * @var array Required input keys that must exist in context
     */
    protected $required_inputs = array();
    
    /**
     * @var array Output keys that this step will set in context
     */
    protected $output_keys = array();
    
    /**
     * @var int Estimated execution time in seconds
     */
    protected $estimated_duration = 15;
    
    /**
     * @var string Category for grouping steps (input, processing, refinement, output, control)
     */
    protected $category = 'processing';
    
    /**
     * Constructor
     *
     * @param array $config Step-specific configuration
     */
    public function __construct($config = array()) {
        $this->config = wp_parse_args($config, $this->get_default_config());
    }
    
    /**
     * Execute the step
     * 
     * This is the main method that performs the step's work.
     * Must be implemented by all step classes.
     *
     * @param AIGH_Pipeline_Context $context
     * @return AIGH_Pipeline_Context|WP_Error Modified context or error
     */
    abstract public function execute($context);
    
    /**
     * Get default configuration for this step type
     *
     * @return array
     */
    protected function get_default_config() {
        return array();
    }
    
    /**
     * Validate that required inputs exist in context
     *
     * @param AIGH_Pipeline_Context $context
     * @return bool|WP_Error True if valid, WP_Error if invalid
     */
    public function validate_inputs($context) {
        foreach ($this->required_inputs as $input) {
            if (!$context->has($input)) {
                return new WP_Error(
                    'missing_input',
                    sprintf('Required input "%s" not found in context for step "%s"', $input, $this->step_name)
                );
            }
        }
        
        return true;
    }
    
    /**
     * Get step metadata
     *
     * @return array
     */
    public function get_metadata() {
        return array(
            'step_type' => $this->step_type,
            'step_name' => $this->step_name,
            'description' => $this->description,
            'category' => $this->category,
            'required_inputs' => $this->required_inputs,
            'output_keys' => $this->output_keys,
            'estimated_duration' => $this->estimated_duration,
            'config' => $this->config
        );
    }
    
    /**
     * Get step type identifier
     *
     * @return string
     */
    public function get_type() {
        return $this->step_type;
    }
    
    /**
     * Get step display name
     *
     * @return string
     */
    public function get_name() {
        return $this->step_name;
    }
    
    /**
     * Get step description
     *
     * @return string
     */
    public function get_description() {
        return $this->description;
    }
    
    /**
     * Get step category
     *
     * @return string
     */
    public function get_category() {
        return $this->category;
    }
    
    /**
     * Get estimated duration
     *
     * @return int Seconds
     */
    public function get_estimated_duration() {
        return $this->estimated_duration;
    }
    
    /**
     * Get current configuration
     *
     * @return array
     */
    public function get_config() {
        return $this->config;
    }
    
    /**
     * Update configuration
     *
     * @param array $config
     */
    public function set_config($config) {
        $this->config = wp_parse_args($config, $this->get_default_config());
    }
    
    /**
     * Get a single config value
     *
     * @param string $key
     * @param mixed $default
     * @return mixed
     */
    protected function get_config_value($key, $default = null) {
        return isset($this->config[$key]) ? $this->config[$key] : $default;
    }
    
    /**
     * Log step execution start
     *
     * @param AIGH_Pipeline_Context $context
     */
    protected function log_start($context) {
        $context->set_metadata('current_step', $this->step_name);
        $context->set_metadata('current_step_start', microtime(true));
    }
    
    /**
     * Log step execution end
     *
     * @param AIGH_Pipeline_Context $context
     * @param bool $success
     */
    protected function log_end($context, $success = true) {
        $start_time = $context->get_metadata('current_step_start', microtime(true));
        $duration = microtime(true) - $start_time;
        
        $context->set_metadata('last_step', $this->step_name);
        $context->set_metadata('last_step_duration', $duration);
        $context->set_metadata('last_step_success', $success);
        $context->increment_step_count();
    }
    
    /**
     * Helper method to safely get value from context with validation
     *
     * @param AIGH_Pipeline_Context $context
     * @param string $key
     * @param mixed $default
     * @return mixed
     */
    protected function get_from_context($context, $key, $default = null) {
        return $context->get($key, $default);
    }
    
    /**
     * Helper method to safely set value in context
     *
     * @param AIGH_Pipeline_Context $context
     * @param string $key
     * @param mixed $value
     */
    protected function set_in_context($context, $key, $value) {
        $context->set($key, $value);
    }
    
    /**
     * Create an error for this step
     *
     * @param string $code Error code
     * @param string $message Error message
     * @param array $data Additional error data
     * @return WP_Error
     */
    protected function create_error($code, $message, $data = array()) {
        return new WP_Error(
            $code,
            $message,
            array_merge(array('step' => $this->step_name), $data)
        );
    }
    
    /**
     * Check if this step can be executed (override for complex validation)
     *
     * @param AIGH_Pipeline_Context $context
     * @return bool|WP_Error
     */
    public function can_execute($context) {
        return $this->validate_inputs($context);
    }
    
    /**
     * Get configuration schema for UI rendering
     * Override this to define what settings this step needs
     *
     * @return array
     */
    public function get_config_schema() {
        return array();
    }
    
    /**
     * Serialize step configuration for storage
     *
     * @return array
     */
    public function to_array() {
        return array(
            'step_type' => $this->step_type,
            'step_name' => $this->step_name,
            'config' => $this->config
        );
    }
    
    /**
     * Create step instance from array
     *
     * @param array $data
     * @return AIGH_Pipeline_Step|WP_Error
     */
    public static function from_array($data) {
        // This will be implemented by the Step Registry
        // which knows how to instantiate step classes
        return new WP_Error('not_implemented', 'Use Step Registry to create steps from array');
    }
}