dramaling-vocab-learning/backend/DramaLing.Api/Utils/CEFRHelper.cs

using System.Collections.Generic;
using System.Linq;

namespace DramaLing.Api.Utils
{
    /// <summary>
    /// CEFR 等級轉換和比較輔助類別
    /// 處理字串格式 (A1, A2, B1, B2, C1, C2) 與數字格式 (0-6) 的轉換
    /// </summary>
    public static class CEFRHelper
    {
        /// <summary>
        /// CEFR 等級映射表
        /// 0 = 未知/完全沒概念
        /// 1-6 = A1 到 C2
        /// </summary>
        private static readonly Dictionary<string, int> LevelToNumericMap = new()
        {
            ["A0"] = 0,
            ["A1"] = 1,
            ["A2"] = 2,
            ["B1"] = 3,
            ["B2"] = 4,
            ["C1"] = 5,
            ["C2"] = 6
        };

        /// <summary>
        /// 數字到字串的反向映射
        /// </summary>
        private static readonly Dictionary<int, string> NumericToLevelMap =
            LevelToNumericMap.ToDictionary(kvp => kvp.Value, kvp => kvp.Key);

        /// <summary>
        /// 將 CEFR 字串等級轉換為數字
        /// </summary>
        /// <param name="level">CEFR 等級字串 (A1, A2, B1, B2, C1, C2)</param>
        /// <returns>數字等級 (0=未知, 1-6=A1-C2)</returns>
        public static int ToNumeric(string? level)
        {
            if (string.IsNullOrWhiteSpace(level))
                return 0;

            var normalizedLevel = level.Trim().ToUpper();
            return LevelToNumericMap.TryGetValue(normalizedLevel, out var numeric) ? numeric : 0;
        }

        /// <summary>
        /// 將數字等級轉換為 CEFR 字串
        /// </summary>
        /// <param name="level">數字等級 (0-6)</param>
        /// <returns>CEFR 等級字串，無效值返回 "Unknown"</returns>
        public static string ToString(int level)
        {
            return NumericToLevelMap.TryGetValue(level, out var cefr) ? cefr : "Unknown";
        }

        /// <summary>
        /// 比較兩個等級：level1 是否高於 level2
        /// </summary>
        /// <param name="level1">等級1 (數字)</param>
        /// <param name="level2">等級2 (數字)</param>
        /// <returns>level1 > level2</returns>
        public static bool IsHigherThan(int level1, int level2)
        {
            return level1 > level2;
        }

        /// <summary>
        /// 比較兩個等級：level1 是否低於 level2
        /// </summary>
        /// <param name="level1">等級1 (數字)</param>
        /// <param name="level2">等級2 (數字)</param>
        /// <returns>level1 < level2</returns>
        public static bool IsLowerThan(int level1, int level2)
        {
            return level1 < level2;
        }

        /// <summary>
        /// 比較兩個等級是否相同
        /// </summary>
        /// <param name="level1">等級1 (數字)</param>
        /// <param name="level2">等級2 (數字)</param>
        /// <returns>level1 == level2</returns>
        public static bool IsSameLevel(int level1, int level2)
        {
            return level1 == level2;
        }

        /// <summary>
        /// 字串版本：比較兩個 CEFR 等級
        /// </summary>
        /// <param name="level1">等級1 (字串)</param>
        /// <param name="level2">等級2 (字串)</param>
        /// <returns>level1 > level2</returns>
        public static bool IsHigherThan(string? level1, string? level2)
        {
            return IsHigherThan(ToNumeric(level1), ToNumeric(level2));
        }

        /// <summary>
        /// 字串版本：比較兩個 CEFR 等級
        /// </summary>
        /// <param name="level1">等級1 (字串)</param>
        /// <param name="level2">等級2 (字串)</param>
        /// <returns>level1 < level2</returns>
        public static bool IsLowerThan(string? level1, string? level2)
        {
            return IsLowerThan(ToNumeric(level1), ToNumeric(level2));
        }

        /// <summary>
        /// 字串版本：比較兩個 CEFR 等級是否相同
        /// </summary>
        /// <param name="level1">等級1 (字串)</param>
        /// <param name="level2">等級2 (字串)</param>
        /// <returns>level1 == level2</returns>
        public static bool IsSameLevel(string? level1, string? level2)
        {
            return IsSameLevel(ToNumeric(level1), ToNumeric(level2));
        }

        /// <summary>
        /// 驗證數字等級是否有效
        /// </summary>
        /// <param name="level">數字等級</param>
        /// <returns>是否在 0-6 範圍內</returns>
        public static bool IsValidNumericLevel(int level)
        {
            return level >= 0 && level <= 6;
        }

        /// <summary>
        /// 驗證字串等級是否有效
        /// </summary>
        /// <param name="level">字串等級</param>
        /// <returns>是否為有效的 CEFR 等級</returns>
        public static bool IsValidStringLevel(string? level)
        {
            if (string.IsNullOrWhiteSpace(level))
                return false;

            var normalizedLevel = level.Trim().ToUpper();
            return LevelToNumericMap.ContainsKey(normalizedLevel);
        }

        /// <summary>
        /// 取得所有有效的數字等級
        /// </summary>
        /// <returns>數字等級陣列 (0-6)</returns>
        public static int[] GetAllNumericLevels()
        {
            return new int[] { 0, 1, 2, 3, 4, 5, 6 };
        }

        /// <summary>
        /// 取得所有有效的字串等級
        /// </summary>
        /// <returns>CEFR 等級字串陣列</returns>
        public static string[] GetAllStringLevels()
        {
            return new string[] { "A1", "A2", "B1", "B2", "C1", "C2" };
        }
    }
}