/**
 * DRSExerciseInterface - STRICT interface for all DRS exercise modules
 * Like a .h header in C++ - ALL exercise modules MUST implement these methods
 *
 * ANY module wanting to work with DRS/SmartGuide MUST implement this interface
 */

import StrictInterface from './StrictInterface.js';

class DRSExerciseInterface extends StrictInterface {
    constructor(implementationName) {
        super(implementationName);
    }

    /**
     * Define required methods that ALL DRS exercise modules MUST implement
     * @override
     */
    _getAbstractMethods() {
        return [
            // Lifecycle
            'init',
            'render',
            'destroy',

            // Exercise logic
            'validate',
            'getResults',
            'handleUserInput',

            // Progress tracking
            'markCompleted',
            'getProgress',

            // Metadata
            'getExerciseType',
            'getExerciseConfig'
        ];
    }

    // ========================================
    // LIFECYCLE METHODS (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Initialize the exercise module
     * @param {Object} config - Exercise configuration
     * @param {Object} content - Exercise content data
     * @returns {Promise<void>}
     */
    async init(config, content) {
        this._throwImplementationError('init');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Render the exercise UI
     * @param {HTMLElement} container - Container element to render into
     * @returns {Promise<void>}
     */
    async render(container) {
        this._throwImplementationError('render');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Clean up and destroy the exercise
     * @returns {Promise<void>}
     */
    async destroy() {
        this._throwImplementationError('destroy');
    }

    // ========================================
    // EXERCISE LOGIC (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Validate user's answer
     * @param {*} userAnswer - User's answer (format depends on exercise type)
     * @returns {Promise<Object>} - Validation result
     *
     * MUST return format:
     * {
     *   isCorrect: boolean,
     *   score: number,           // 0-100
     *   feedback: string,
     *   explanation: string,
     *   metadata: Object         // Exercise-specific data
     * }
     */
    async validate(userAnswer) {
        this._throwImplementationError('validate');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Get exercise results and statistics
     * @returns {Object} - Results data
     *
     * MUST return format:
     * {
     *   score: number,           // 0-100
     *   attempts: number,
     *   timeSpent: number,       // milliseconds
     *   completed: boolean,
     *   details: Object          // Exercise-specific details
     * }
     */
    getResults() {
        this._throwImplementationError('getResults');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Handle user input during exercise
     * @param {Event} event - User input event
     * @param {*} data - Input data
     * @returns {void}
     */
    handleUserInput(event, data) {
        this._throwImplementationError('handleUserInput');
    }

    // ========================================
    // PROGRESS TRACKING (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Mark exercise as completed and save progress
     * @param {Object} results - Exercise results
     * @returns {Promise<void>}
     */
    async markCompleted(results) {
        this._throwImplementationError('markCompleted');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Get current exercise progress
     * @returns {Object} - Progress data
     *
     * MUST return format:
     * {
     *   percentage: number,      // 0-100
     *   currentStep: number,
     *   totalSteps: number,
     *   itemsCompleted: number,
     *   itemsTotal: number
     * }
     */
    getProgress() {
        this._throwImplementationError('getProgress');
    }

    // ========================================
    // METADATA (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Get exercise type identifier
     * @returns {string} - Exercise type (e.g., 'vocabulary', 'text-analysis', 'grammar')
     */
    getExerciseType() {
        this._throwImplementationError('getExerciseType');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Get exercise configuration
     * @returns {Object} - Configuration object
     *
     * MUST return format:
     * {
     *   type: string,            // Exercise type
     *   difficulty: string,      // 'easy', 'medium', 'hard'
     *   estimatedTime: number,   // minutes
     *   prerequisites: Array,    // Required prerequisites
     *   metadata: Object         // Exercise-specific config
     * }
     */
    getExerciseConfig() {
        this._throwImplementationError('getExerciseConfig');
    }
}

export default DRSExerciseInterface;
