/**
 * ProgressSystemInterface - STRICT interface for all DRS progress systems
 * Like a .h header in C++ - ALL progress systems MUST implement these methods
 *
 * ANY system wanting to work with DRS/SmartGuide MUST implement this interface
 */

import StrictInterface from './StrictInterface.js';

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

    /**
     * Define required methods that ALL progress systems MUST implement
     * @override
     */
    _getAbstractMethods() {
        return [
            // Vocabulary tracking
            'markWordDiscovered',
            'markWordMastered',
            'isWordDiscovered',
            'isWordMastered',

            // Content tracking
            'markPhraseCompleted',
            'markDialogCompleted',
            'markTextCompleted',
            'markAudioCompleted',
            'markImageCompleted',
            'markGrammarCompleted',

            // Prerequisites
            'canComplete',

            // Progress calculation
            'getProgress',

            // Persistence
            'saveProgress',
            'loadProgress',

            // Utility
            'reset'
        ];
    }

    // ========================================
    // VOCABULARY METHODS (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Mark a word as discovered (passive exposure)
     * @param {string} word - Word to mark as discovered
     * @param {Object} metadata - Optional metadata (timestamp, context, etc.)
     * @returns {Promise<void>}
     */
    async markWordDiscovered(word, metadata = {}) {
        this._throwImplementationError('markWordDiscovered');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Mark a word as mastered (active practice)
     * @param {string} word - Word to mark as mastered
     * @param {Object} metadata - Optional metadata (score, attempts, etc.)
     * @returns {Promise<void>}
     */
    async markWordMastered(word, metadata = {}) {
        this._throwImplementationError('markWordMastered');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Check if word is discovered
     * @param {string} word - Word to check
     * @returns {boolean}
     */
    isWordDiscovered(word) {
        this._throwImplementationError('isWordDiscovered');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Check if word is mastered
     * @param {string} word - Word to check
     * @returns {boolean}
     */
    isWordMastered(word) {
        this._throwImplementationError('isWordMastered');
    }

    // ========================================
    // CONTENT TRACKING METHODS (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Mark phrase as completed
     * @param {string} phraseId - Phrase identifier
     * @param {Object} metadata - Optional metadata
     * @returns {Promise<void>}
     */
    async markPhraseCompleted(phraseId, metadata = {}) {
        this._throwImplementationError('markPhraseCompleted');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Mark dialog as completed
     * @param {string} dialogId - Dialog identifier
     * @param {Object} metadata - Optional metadata
     * @returns {Promise<void>}
     */
    async markDialogCompleted(dialogId, metadata = {}) {
        this._throwImplementationError('markDialogCompleted');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Mark text/lesson as completed
     * @param {string} textId - Text identifier
     * @param {Object} metadata - Optional metadata
     * @returns {Promise<void>}
     */
    async markTextCompleted(textId, metadata = {}) {
        this._throwImplementationError('markTextCompleted');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Mark audio as completed
     * @param {string} audioId - Audio identifier
     * @param {Object} metadata - Optional metadata
     * @returns {Promise<void>}
     */
    async markAudioCompleted(audioId, metadata = {}) {
        this._throwImplementationError('markAudioCompleted');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Mark image as completed
     * @param {string} imageId - Image identifier
     * @param {Object} metadata - Optional metadata
     * @returns {Promise<void>}
     */
    async markImageCompleted(imageId, metadata = {}) {
        this._throwImplementationError('markImageCompleted');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Mark grammar concept as completed
     * @param {string} grammarId - Grammar identifier
     * @param {Object} metadata - Optional metadata
     * @returns {Promise<void>}
     */
    async markGrammarCompleted(grammarId, metadata = {}) {
        this._throwImplementationError('markGrammarCompleted');
    }

    // ========================================
    // PREREQUISITE CHECKING (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Check if an item can be completed (prerequisites met)
     * @param {string} itemType - Type of item (vocabulary-discovery, phrase, dialog, etc.)
     * @param {string} itemId - Item identifier
     * @param {Object} context - Additional context (chapter content, etc.)
     * @returns {Object} - { canComplete: boolean, reason: string, missingPrereqs: Array }
     */
    canComplete(itemType, itemId, context = {}) {
        this._throwImplementationError('canComplete');
    }

    // ========================================
    // PROGRESS CALCULATION (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Get current progress for a chapter
     * @param {string} chapterId - Chapter identifier
     * @returns {Object} - Progress data with percentage, breakdown, etc.
     *
     * MUST return format:
     * {
     *   percentage: number,           // 0-100
     *   completedWeight: number,      // Total weight completed
     *   totalWeight: number,          // Total possible weight
     *   breakdown: Object,            // By item type
     *   completedBreakdown: Object    // Completed items by type
     * }
     */
    getProgress(chapterId) {
        this._throwImplementationError('getProgress');
    }

    // ========================================
    // PERSISTENCE (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Save progress to persistent storage
     * @param {string} bookId - Book identifier
     * @param {string} chapterId - Chapter identifier
     * @returns {Promise<void>}
     */
    async saveProgress(bookId, chapterId) {
        this._throwImplementationError('saveProgress');
    }

    /**
     * ⚠️ MUST IMPLEMENT - Load progress from persistent storage
     * @param {string} bookId - Book identifier
     * @param {string} chapterId - Chapter identifier
     * @returns {Promise<Object>} - Loaded progress data
     */
    async loadProgress(bookId, chapterId) {
        this._throwImplementationError('loadProgress');
    }

    // ========================================
    // UTILITY (REQUIRED)
    // ========================================

    /**
     * ⚠️ MUST IMPLEMENT - Reset all progress for a chapter
     * @param {string} bookId - Book identifier
     * @param {string} chapterId - Chapter identifier
     * @returns {Promise<void>}
     */
    async reset(bookId, chapterId) {
        this._throwImplementationError('reset');
    }
}

export default ProgressSystemInterface;
