Localize sample UI and document release conventions

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Announcement/BriskAnnouncementsModule.cs

@@ -2,9 +2,15 @@ using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
+/// <summary>
+/// 公告模块。
+/// </summary>
 public sealed class BriskAnnouncementsModule
     : BriskModuleBase
 {
+    /// <summary>
+    /// 获取公告列表。
+    /// </summary>
     public async Task<IReadOnlyList<BriskAnnouncementItem>> GetListAsync()
     {
         return await ExecuteAsync(async context =>
@@ -14,6 +20,9 @@ public sealed class BriskAnnouncementsModule
         });
     }
 
+    /// <summary>
+    /// 标记指定公告为已读。
+    /// </summary>
     public async Task MarkReadAsync(long id)
     {
         RequirePositive(id, nameof(id), "Announcement id must be greater than 0.");

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

@@ -5,9 +5,15 @@ using System.Text;
 using System.Threading.Tasks;
 using UnityEngine.Networking;
 
+/// <summary>
+/// 云存档模块。
+/// </summary>
 public sealed class BriskArchiveModule
     : BriskModuleBase
 {
+    /// <summary>
+    /// 获取当前账号的存档槽位列表。
+    /// </summary>
     public async Task<IReadOnlyList<BriskArchiveSlot>> GetSlotsAsync()
     {
         return await ExecuteAsync(async context =>
@@ -17,6 +23,9 @@ public sealed class BriskArchiveModule
         });
     }
 
+    /// <summary>
+    /// 获取指定槽位的元信息。
+    /// </summary>
     public async Task<BriskArchiveMeta> GetMetaAsync(int slotNo)
     {
         ValidateSlotNo(slotNo);
@@ -28,6 +37,9 @@ public sealed class BriskArchiveModule
         });
     }
 
+    /// <summary>
+    /// 上传指定槽位的二进制存档。
+    /// </summary>
     public async Task<BriskArchiveUploadResult> UploadAsync(int slotNo, byte[] bytes, int? baseVersion = null, string checksum = null)
     {
         ValidateSlotNo(slotNo);
@@ -51,6 +63,9 @@ public sealed class BriskArchiveModule
         });
     }
 
+    /// <summary>
+    /// 下载指定槽位的二进制存档。
+    /// </summary>
     public async Task<BriskArchiveDownloadResult> DownloadAsync(int slotNo)
     {
         ValidateSlotNo(slotNo);

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Auth/BriskAuthModule.cs

@@ -2,9 +2,15 @@ using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
+/// <summary>
+/// Brisk 认证模块。
+/// </summary>
 public sealed class BriskAuthModule
     : BriskModuleBase
 {
+    /// <summary>
+    /// 通过稳定的第三方用户 ID 换取 Brisk 登录态。
+    /// </summary>
     public async Task<BriskLoginResult> LoginWithUserIdAsync(string loginProvider, string loginUserId, BriskProfile profile = null)
     {
         RequireNotEmpty(loginProvider, nameof(loginProvider));
@@ -13,6 +19,9 @@ public sealed class BriskAuthModule
         return await LoginInternalAsync(CreateLoginBody(loginProvider, profile, loginUserId, null), loginProvider, loginUserId);
     }
 
+    /// <summary>
+    /// 通过第三方返回的 code 换取 Brisk 登录态。
+    /// </summary>
     public async Task<BriskLoginResult> LoginWithCodeAsync(string loginProvider, string code, BriskProfile profile = null)
     {
         RequireNotEmpty(loginProvider, nameof(loginProvider));
@@ -21,6 +30,9 @@ public sealed class BriskAuthModule
         return await LoginInternalAsync(CreateLoginBody(loginProvider, profile, null, code), loginProvider, null);
     }
 
+    /// <summary>
+    /// 登出当前账号并清理本地会话。
+    /// </summary>
     public async Task LogoutAsync()
     {
         var context = GetContext();

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Config/BriskConfigModule.cs

@@ -2,9 +2,15 @@ using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
+/// <summary>
+/// 动态配置模块。
+/// </summary>
 public sealed class BriskConfigModule
     : BriskModuleBase
 {
+    /// <summary>
+    /// 获取当前客户端命中的动态配置。
+    /// </summary>
     public async Task<BriskConfigCurrent> GetCurrentAsync()
     {
         return await ExecutePublicAsync(async context =>
@@ -14,6 +20,9 @@ public sealed class BriskConfigModule
         });
     }
 
+    /// <summary>
+    /// 刷新并重新获取动态配置。
+    /// </summary>
     public Task<BriskConfigCurrent> RefreshAsync()
     {
         return GetCurrentAsync();

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Core/Brisk.cs

@@ -2,6 +2,10 @@ using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
+/// <summary>
+/// Brisk SDK 的静态总入口。
+/// 初始化完成后，开发者可以通过 <c>Brisk.Auth</c>、<c>Brisk.Leaderboard</c> 等模块直接访问能力。
+/// </summary>
 public static class Brisk
 {
     private static BriskContext s_context;
@@ -17,40 +21,101 @@ public static class Brisk
         Space = new BriskSpaceModule();
     }
 
+    /// <summary>
+    /// SDK 初始化完成后触发。
+    /// </summary>
     public static event Action OnInitialized;
+    /// <summary>
+    /// 登录成功并保存会话后触发。
+    /// </summary>
     public static event Action OnLoggedIn;
+    /// <summary>
+    /// 主动登出并清理本地会话后触发。
+    /// </summary>
     public static event Action OnLoggedOut;
+    /// <summary>
+    /// 发生维护、封禁、强更等严重阻断错误时触发。
+    /// </summary>
     public static event Action<BriskBlockingException> OnBlockingError;
+    /// <summary>
+    /// 登录态失效并清空本地会话时触发。
+    /// </summary>
     public static event Action<BriskAuthExpiredException> OnAuthExpired;
 
+    /// <summary>
+    /// 认证模块入口。
+    /// </summary>
     public static BriskAuthModule Auth { get; }
 
+    /// <summary>
+    /// 玩家模块入口。
+    /// </summary>
     public static BriskPlayerModule Player { get; }
 
+    /// <summary>
+    /// 动态配置模块入口。
+    /// </summary>
     public static BriskConfigModule Config { get; }
 
+    /// <summary>
+    /// 公告模块入口。
+    /// </summary>
     public static BriskAnnouncementsModule Announcements { get; }
 
+    /// <summary>
+    /// 排行榜模块入口。
+    /// </summary>
     public static BriskLeaderboardModule Leaderboard { get; }
 
+    /// <summary>
+    /// 云存档模块入口。
+    /// </summary>
     public static BriskArchiveModule Archive { get; }
 
+    /// <summary>
+    /// 玩家空间模块入口。
+    /// </summary>
     public static BriskSpaceModule Space { get; }
 
+    /// <summary>
+    /// 当前 SDK 是否已完成初始化。
+    /// </summary>
     public static bool IsInitialized => s_context != null;
 
+    /// <summary>
+    /// 当前是否存在可用登录态。
+    /// </summary>
     public static bool IsLoggedIn => s_context != null && s_context.Session.HasAccessToken;
 
+    /// <summary>
+    /// 当前访问令牌。
+    /// </summary>
     public static string AccessToken => s_context != null ? s_context.Session.AccessToken : null;
 
+    /// <summary>
+    /// 当前玩家 ID。
+    /// </summary>
     public static string PlayerId => s_context != null ? s_context.Session.PlayerId : null;
 
+    /// <summary>
+    /// 当前登录身份摘要。
+    /// </summary>
     public static BriskIdentity Identity => s_context != null ? s_context.Session.Identity : null;
 
+    /// <summary>
+    /// 当前初始化选项。
+    /// </summary>
     public static BriskOptions Options => s_context != null ? s_context.Options : null;
 
+    /// <summary>
+    /// 初始化阶段获取到的 bootstrap 结果。
+    /// </summary>
     public static BriskBootstrapResult Bootstrap => s_context != null ? s_context.Bootstrap : null;
 
+    /// <summary>
+    /// 初始化 SDK，并执行 bootstrap 与本地会话恢复。
+    /// </summary>
+    /// <param name="options">初始化选项。</param>
     public static async Task InitializeAsync(BriskOptions options)
     {
         if (options == null)
@@ -79,16 +144,27 @@ public static class Brisk
         }
     }
 
+    /// <summary>
+    /// 关闭 SDK 并清空当前上下文。
+    /// </summary>
     public static void Shutdown()
     {
         s_context = null;
     }
 
+    /// <summary>
+    /// 设置严重错误的展示器。
+    /// </summary>
+    /// <param name="presenter">自定义错误展示器；传入 null 时恢复默认展示器。</param>
     public static void SetErrorPresenter(IBriskErrorPresenter presenter)
     {
         GetRequiredContext().ErrorPresenter = presenter ?? BriskDefaultErrorPresenter.Instance;
     }
 
+    /// <summary>
+    /// 设置阻断错误确认后的退出回调。
+    /// </summary>
+    /// <param name="exitHandler">项目方自定义退出逻辑。</param>
     public static void SetExitHandler(Action exitHandler)
     {
         GetRequiredContext().ExitHandler = exitHandler;

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Core/BriskOptions.cs

@@ -1,17 +1,50 @@
 using System;
 
+/// <summary>
+/// Brisk SDK 初始化参数。
+/// </summary>
 public sealed class BriskOptions
 {
+    /// <summary>
+    /// 服务端基础地址。可以传主机地址，SDK 会自动补上 <c>/api</c>。
+    /// </summary>
     public string BaseUrl;
+    /// <summary>
+    /// 项目标识。
+    /// </summary>
     public string GameKey;
+    /// <summary>
+    /// 客户端版本号。
+    /// </summary>
     public string ClientVersion;
+    /// <summary>
+    /// 设备标识。
+    /// </summary>
     public string DeviceId;
+    /// <summary>
+    /// 是否启用调试日志。
+    /// </summary>
     public bool EnableLog;
+    /// <summary>
+    /// 初始化时是否主动校验本地会话有效性。
+    /// </summary>
     public bool ValidateSessionOnInitialize = true;
+    /// <summary>
+    /// 自定义登录态持久化实现。
+    /// </summary>
     public IBriskTokenStore TokenStore;
+    /// <summary>
+    /// 自定义严重错误展示器。
+    /// </summary>
     public IBriskErrorPresenter ErrorPresenter;
+    /// <summary>
+    /// 阻断错误确认后的退出处理逻辑。
+    /// </summary>
     public Action ExitHandler;
 
+    /// <summary>
+    /// 校验并规范化初始化参数。
+    /// </summary>
     public void Validate()
     {
         if (string.IsNullOrWhiteSpace(BaseUrl))

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Core/IBriskErrorPresenter.cs

@@ -1,6 +1,15 @@
+/// <summary>
+/// 自定义严重错误展示接口。
+/// </summary>
 public interface IBriskErrorPresenter
 {
+    /// <summary>
+    /// 展示维护、封禁、强更等阻断错误。
+    /// </summary>
     void ShowBlockingError(BriskBlockingException exception);
 
+    /// <summary>
+    /// 展示登录态失效提示。
+    /// </summary>
     void ShowAuthExpired(BriskAuthExpiredException exception);
 }

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Core/IBriskTokenStore.cs

@@ -1,10 +1,22 @@
 using System.Threading.Tasks;
 
+/// <summary>
+/// 自定义登录态持久化接口。
+/// </summary>
 public interface IBriskTokenStore
 {
+    /// <summary>
+    /// 保存当前登录会话。
+    /// </summary>
     Task SaveAsync(BriskStoredSession session);
 
+    /// <summary>
+    /// 读取本地保存的登录会话。
+    /// </summary>
     Task<BriskStoredSession> LoadAsync();
 
+    /// <summary>
+    /// 清空本地保存的登录会话。
+    /// </summary>
     Task ClearAsync();
 }

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Leaderboard/BriskLeaderboardModule.cs

@@ -2,9 +2,15 @@ using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
+/// <summary>
+/// 排行榜模块。
+/// </summary>
 public sealed class BriskLeaderboardModule
     : BriskModuleBase
 {
+    /// <summary>
+    /// 获取排行榜 Top 列表。
+    /// </summary>
     public async Task<IReadOnlyList<BriskLeaderboardEntry>> GetTopAsync(string rankKey, int limit = 20)
     {
         ValidateRankKey(rankKey);
@@ -19,6 +25,9 @@ public sealed class BriskLeaderboardModule
         });
     }
 
+    /// <summary>
+    /// 获取当前玩家在排行榜中的信息。
+    /// </summary>
     public async Task<BriskLeaderboardPlayerRank> GetMeAsync(string rankKey)
     {
         ValidateRankKey(rankKey);
@@ -30,6 +39,9 @@ public sealed class BriskLeaderboardModule
         });
     }
 
+    /// <summary>
+    /// 获取当前玩家附近的排名区间。
+    /// </summary>
     public async Task<IReadOnlyList<BriskLeaderboardEntry>> GetAroundMeAsync(string rankKey, int range = 10)
     {
         ValidateRankKey(rankKey);
@@ -44,6 +56,9 @@ public sealed class BriskLeaderboardModule
         });
     }
 
+    /// <summary>
+    /// 提交当前玩家分数。
+    /// </summary>
     public async Task SubmitScoreAsync(string rankKey, long score)
     {
         ValidateRankKey(rankKey);
@@ -57,6 +72,9 @@ public sealed class BriskLeaderboardModule
         });
     }
 
+    /// <summary>
+    /// 获取当前赛季信息。
+    /// </summary>
     public async Task<BriskRankSeasonInfo> GetCurrentSeasonAsync(string rankKey)
     {
         ValidateRankKey(rankKey);
@@ -68,6 +86,9 @@ public sealed class BriskLeaderboardModule
         });
     }
 
+    /// <summary>
+    /// 获取赛季历史列表。
+    /// </summary>
     public async Task<IReadOnlyList<BriskRankSeasonInfo>> GetSeasonHistoryAsync(string rankKey, int limit = 20)
     {
         ValidateRankKey(rankKey);
@@ -82,6 +103,9 @@ public sealed class BriskLeaderboardModule
         });
     }
 
+    /// <summary>
+    /// 获取指定历史赛季的排行榜详情。
+    /// </summary>
     public async Task<IReadOnlyList<BriskLeaderboardEntry>> GetSeasonHistoryDetailAsync(string rankKey, string seasonId, int limit = 20)
     {
         ValidateRankKey(rankKey);

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Models/BriskConfigCurrent.cs

@@ -1,7 +1,16 @@
 using System.Collections.Generic;
 
+/// <summary>
+/// 当前客户端命中的动态配置结果。
+/// </summary>
 public sealed class BriskConfigCurrent
 {
+    /// <summary>
+    /// 功能开关集合。
+    /// </summary>
     public Dictionary<string, object> FeatureFlags;
+    /// <summary>
+    /// 动态配置集合。
+    /// </summary>
     public Dictionary<string, object> DynamicConfig;
 }

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Models/BriskIdentity.cs

@@ -1,7 +1,22 @@
+/// <summary>
+/// 当前登录身份摘要。
+/// </summary>
 public sealed class BriskIdentity
 {
+    /// <summary>
+    /// 登录提供方。
+    /// </summary>
     public string LoginProvider;
+    /// <summary>
+    /// 登录用户 ID。
+    /// </summary>
     public string LoginUserId;
+    /// <summary>
+    /// 玩家 ID。
+    /// </summary>
     public string PlayerId;
+    /// <summary>
+    /// 项目账号 ID。
+    /// </summary>
     public string ProjectAccountId;
 }

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Models/BriskLoginResult.cs

@@ -1,11 +1,38 @@
+/// <summary>
+/// 登录成功后的返回结果。
+/// </summary>
 public sealed class BriskLoginResult
 {
+    /// <summary>
+    /// Brisk 访问令牌。
+    /// </summary>
     public string AccessToken;
+    /// <summary>
+    /// 令牌有效时长，单位秒。
+    /// </summary>
     public int ExpiresIn;
+    /// <summary>
+    /// 玩家 ID。
+    /// </summary>
     public string PlayerId;
+    /// <summary>
+    /// 项目账号 ID。
+    /// </summary>
     public string ProjectAccountId;
+    /// <summary>
+    /// 登录提供方。
+    /// </summary>
     public string LoginProvider;
+    /// <summary>
+    /// 登录用户 ID。
+    /// </summary>
     public string LoginUserId;
+    /// <summary>
+    /// 是否为新玩家。
+    /// </summary>
     public bool IsNewPlayer;
+    /// <summary>
+    /// 玩家资料。
+    /// </summary>
     public BriskProfile Profile;
 }

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Models/BriskPlayerMe.cs

@@ -1,10 +1,34 @@
+/// <summary>
+/// 当前玩家资料。
+/// </summary>
 public sealed class BriskPlayerMe
 {
+    /// <summary>
+    /// 玩家 ID。
+    /// </summary>
     public string PlayerId;
+    /// <summary>
+    /// 项目账号 ID。
+    /// </summary>
     public string ProjectAccountId;
+    /// <summary>
+    /// 登录提供方。
+    /// </summary>
     public string LoginProvider;
+    /// <summary>
+    /// 登录用户 ID。
+    /// </summary>
     public string LoginUserId;
+    /// <summary>
+    /// 昵称。
+    /// </summary>
     public string Nickname;
+    /// <summary>
+    /// 头像地址。
+    /// </summary>
     public string AvatarUrl;
+    /// <summary>
+    /// 扩展资料。
+    /// </summary>
     public object ProfileJson;
 }

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Models/BriskProfile.cs

@@ -1,6 +1,18 @@
+/// <summary>
+/// 登录时可选上传的玩家资料。
+/// </summary>
 public sealed class BriskProfile
 {
+    /// <summary>
+    /// 玩家昵称。
+    /// </summary>
     public string Nickname;
+    /// <summary>
+    /// 玩家头像地址。
+    /// </summary>
     public string AvatarUrl;
+    /// <summary>
+    /// 额外扩展资料。
+    /// </summary>
     public object ProfileJson;
 }

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Player/BriskPlayerModule.cs

@@ -1,9 +1,15 @@
 using System;
 using System.Threading.Tasks;
 
+/// <summary>
+/// 玩家模块。
+/// </summary>
 public sealed class BriskPlayerModule
     : BriskModuleBase
 {
+    /// <summary>
+    /// 获取当前登录玩家信息。
+    /// </summary>
     public async Task<BriskPlayerMe> GetMeAsync()
     {
         return await ExecuteAsync(async context =>

PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime/Space/BriskSpaceModule.cs

@@ -2,9 +2,15 @@ using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
+/// <summary>
+/// 玩家空间模块。
+/// </summary>
 public sealed class BriskSpaceModule
     : BriskModuleBase
 {
+    /// <summary>
+    /// 按玩家 ID 获取空间数据。
+    /// </summary>
     public async Task<BriskSpaceView> GetByPlayerIdAsync(string playerId)
     {
         ValidatePlayerId(playerId);
@@ -16,6 +22,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 按登录身份获取空间数据。
+    /// </summary>
     public async Task<BriskSpaceView> GetByLoginIdentityAsync(string loginProvider, string loginUserId)
     {
         ValidateLoginIdentity(loginProvider, loginUserId);
@@ -27,6 +36,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 按玩家 ID 获取空间统计。
+    /// </summary>
     public async Task<BriskSpaceStats> GetStatsByPlayerIdAsync(string playerId)
     {
         ValidatePlayerId(playerId);
@@ -38,6 +50,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 按登录身份获取空间统计。
+    /// </summary>
     public async Task<BriskSpaceStats> GetStatsByLoginIdentityAsync(string loginProvider, string loginUserId)
     {
         ValidateLoginIdentity(loginProvider, loginUserId);
@@ -49,6 +64,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 按玩家 ID 点赞空间。
+    /// </summary>
     public async Task LikeByPlayerIdAsync(string playerId)
     {
         ValidatePlayerId(playerId);
@@ -58,6 +76,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 按玩家 ID 取消点赞空间。
+    /// </summary>
     public async Task UnlikeByPlayerIdAsync(string playerId)
     {
         ValidatePlayerId(playerId);
@@ -67,6 +88,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 按登录身份点赞空间。
+    /// </summary>
     public async Task LikeByLoginIdentityAsync(string loginProvider, string loginUserId)
     {
         ValidateLoginIdentity(loginProvider, loginUserId);
@@ -76,6 +100,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 按登录身份取消点赞空间。
+    /// </summary>
     public async Task UnlikeByLoginIdentityAsync(string loginProvider, string loginUserId)
     {
         ValidateLoginIdentity(loginProvider, loginUserId);
@@ -85,6 +112,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 更新当前玩家自己的空间内容。
+    /// </summary>
     public async Task UpdateMyAsync(object payload)
     {
         RequireNotNull(payload, nameof(payload));
@@ -98,6 +128,9 @@ public sealed class BriskSpaceModule
         });
     }
 
+    /// <summary>
+    /// 获取我的访客列表。
+    /// </summary>
     public async Task<IReadOnlyList<BriskSpaceVisit>> GetMyVisitsAsync()
     {
         return await ExecuteAsync(async context =>