存档重构，游戏内容解锁机制；教程完善（未完成）

Assets/Scripts/Saving/SongStatusSave.cs

@@ -2,24 +2,69 @@ using System.Collections;
 using System.Collections.Generic;
 using UnityEngine;
 
+using System.Collections.Generic;
+
 namespace Ichni.RhythmGame
 {
+    /// <summary>
+    /// 单首歌曲的持久化容器。
+    /// <see cref="isCompleted"/> 只表示玩家曾完成过该歌曲；具体难度的成绩、Revision 与 Max Combo
+    /// 由 <see cref="beatmapSavesByDifficultyId"/> 中对应稳定难度 ID 的 <see cref="BeatmapSave"/> 管理。
+    /// </summary>
     public class SongStatusSave
     {
+        /// <summary>至少有一次有效结算完成；谱面 Revision 变化不会回退该流程状态。</summary>
         public bool isCompleted;
+
+        /// <summary>预留的歌曲级扩展字段；赋予新语义前须评估 Schema Version 是否需要递增。</summary>
         public string additionalInfo;
-        public List<BeatmapSave> beatmapSaves;
+
+        /// <summary>
+        /// 以 <c>DifficultyData.saveDifficultyId</c> 为 Key 的谱面成绩。
+        /// Key 不依赖选曲列表位置，因此重排、隐藏或删除中间难度不会让其他难度的成绩错位。
+        /// 被内容定义移除的 Key 暂时保留在存档中，但 UI 与章节完成度只读取当前仍存在的难度。
+        /// </summary>
+        public Dictionary<int, BeatmapSave> beatmapSavesByDifficultyId = new();
 
         public SongStatusSave()
         {
             
         }
         
-        public SongStatusSave(bool isCompleted, string additionalInfo, List<BeatmapSave> beatmapSaves)
+        public SongStatusSave(bool isCompleted, string additionalInfo, Dictionary<int, BeatmapSave> beatmapSavesByDifficultyId)
         {
             this.isCompleted = isCompleted;
             this.additionalInfo = additionalInfo;
-            this.beatmapSaves = beatmapSaves;
+            this.beatmapSavesByDifficultyId = beatmapSavesByDifficultyId;
+        }
+
+        /// <summary>只读查询当前定义的难度成绩；不会因 UI 展示而创建新的存档记录。</summary>
+        public bool TryGetBeatmapSave(int saveDifficultyId, out BeatmapSave beatmapSave)
+        {
+            beatmapSave = null;
+            return saveDifficultyId >= 0 && beatmapSavesByDifficultyId != null &&
+                   beatmapSavesByDifficultyId.TryGetValue(saveDifficultyId, out beatmapSave) && beatmapSave != null;
+        }
+
+        /// <summary>
+        /// 获取或创建指定稳定难度 ID 的成绩容器。
+        /// 仅存档写入/内容对账可调用此方法；选曲 UI 应使用 <see cref="TryGetBeatmapSave"/>。
+        /// </summary>
+        public BeatmapSave GetOrCreateBeatmapSave(int saveDifficultyId)
+        {
+            if (saveDifficultyId < 0)
+            {
+                return null;
+            }
+
+            beatmapSavesByDifficultyId ??= new Dictionary<int, BeatmapSave>();
+            if (!beatmapSavesByDifficultyId.TryGetValue(saveDifficultyId, out BeatmapSave beatmapSave) || beatmapSave == null)
+            {
+                beatmapSave = new BeatmapSave(0f, false, false);
+                beatmapSavesByDifficultyId[saveDifficultyId] = beatmapSave;
+            }
+
+            return beatmapSave;
         }
     }
-}
+}