using DramaLing.Api.Models.Entities;

namespace DramaLing.Api.Contracts.Services.Core;

/// <summary>
/// 選項詞彙庫服務介面
/// 提供智能測驗選項生成功能
/// </summary>
public interface IOptionsVocabularyService
{
    /// <summary>
    /// 生成智能干擾選項
    /// </summary>
    /// <param name="targetWord">目標詞彙</param>
    /// <param name="cefrLevel">CEFR 等級</param>
    /// <param name="partOfSpeech">詞性</param>
    /// <param name="count">需要的選項數量</param>
    /// <returns>干擾選項列表</returns>
    Task<List<string>> GenerateDistractorsAsync(
        string targetWord,
        string cefrLevel,
        string partOfSpeech,
        int count = 3);

    /// <summary>
    /// 生成智能干擾選項（含詳細資訊）
    /// </summary>
    /// <param name="targetWord">目標詞彙</param>
    /// <param name="cefrLevel">CEFR 等級</param>
    /// <param name="partOfSpeech">詞性</param>
    /// <param name="count">需要的選項數量</param>
    /// <returns>含詳細資訊的干擾選項</returns>
    Task<List<OptionsVocabulary>> GenerateDistractorsWithDetailsAsync(
        string targetWord,
        string cefrLevel,
        string partOfSpeech,
        int count = 3);

    /// <summary>
    /// 檢查詞彙庫是否有足夠的詞彙支援選項生成
    /// </summary>
    /// <param name="cefrLevel">CEFR 等級</param>
    /// <param name="partOfSpeech">詞性</param>
    /// <returns>是否有足夠詞彙</returns>
    Task<bool> HasSufficientVocabularyAsync(string cefrLevel, string partOfSpeech);
}