Release v0.2.0 archive and space API update

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Archive/BriskArchiveModule.cs

@@ -50,7 +50,7 @@ public sealed class BriskArchiveModule
 
         return await ExecuteAsync(async context =>
         {
-            var finalChecksum = string.IsNullOrWhiteSpace(checksum) ? ComputeSha256(bytes) : checksum;
+            var finalChecksum = string.IsNullOrWhiteSpace(checksum) ? ComputeSha256(bytes) : NormalizeChecksum(checksum);
             var sections = new List<IMultipartFormSection>
             {
                 new MultipartFormDataSection("base_version", (baseVersion ?? 0).ToString()),
@@ -63,6 +63,24 @@ public sealed class BriskArchiveModule
         });
     }
 
+    /// <summary>
+    /// 以 UTF-8 文本形式上传指定槽位的存档。
+    /// </summary>
+    public Task<BriskArchiveUploadResult> UploadTextAsync(int slotNo, string text, int? baseVersion = null, string checksum = null)
+    {
+        RequireNotNull(text, nameof(text));
+        return UploadAsync(slotNo, Encoding.UTF8.GetBytes(text), baseVersion, checksum);
+    }
+
+    /// <summary>
+    /// 以 JSON 文本形式上传指定槽位的存档。
+    /// </summary>
+    public Task<BriskArchiveUploadResult> UploadJsonAsync(int slotNo, object payload, int? baseVersion = null, string checksum = null)
+    {
+        RequireNotNull(payload, nameof(payload));
+        return UploadAsync(slotNo, Encoding.UTF8.GetBytes(BriskJson.Serialize(payload)), baseVersion, checksum);
+    }
+
     /// <summary>
     /// 下载指定槽位的二进制存档。
     /// </summary>
@@ -82,6 +100,24 @@ public sealed class BriskArchiveModule
         });
     }
 
+    /// <summary>
+    /// 以 UTF-8 文本形式下载指定槽位的存档。
+    /// </summary>
+    public async Task<string> DownloadTextAsync(int slotNo)
+    {
+        var result = await DownloadAsync(slotNo);
+        return result == null || result.Bytes == null ? string.Empty : Encoding.UTF8.GetString(result.Bytes);
+    }
+
+    /// <summary>
+    /// 以 JSON 对象形式下载指定槽位的存档。
+    /// </summary>
+    public async Task<object> DownloadJsonAsync(int slotNo)
+    {
+        var text = await DownloadTextAsync(slotNo);
+        return string.IsNullOrWhiteSpace(text) ? null : BriskJson.Deserialize(text);
+    }
+
     private static void ValidateSlotNo(int slotNo)
     {
         RequirePositive(slotNo, nameof(slotNo), "slotNo must be greater than 0.");
@@ -92,8 +128,7 @@ public sealed class BriskArchiveModule
         using (var sha = SHA256.Create())
         {
             var hash = sha.ComputeHash(bytes);
-            var builder = new StringBuilder(hash.Length * 2 + 7);
-            builder.Append("sha256:");
+            var builder = new StringBuilder(hash.Length * 2);
             for (var i = 0; i < hash.Length; i++)
             {
                 builder.Append(hash[i].ToString("x2"));
@@ -103,6 +138,19 @@ public sealed class BriskArchiveModule
         }
     }
 
+    private static string NormalizeChecksum(string checksum)
+    {
+        if (string.IsNullOrWhiteSpace(checksum))
+        {
+            return checksum;
+        }
+
+        var value = checksum.Trim();
+        return value.StartsWith("sha256:", StringComparison.OrdinalIgnoreCase)
+            ? value.Substring("sha256:".Length)
+            : value;
+    }
+
     private static int ReadHeaderInt(Dictionary<string, string> headers, string key)
     {
         var value = ReadHeader(headers, key);