From e07a9086b1515661ccd51ef2856b131709ef2831 Mon Sep 17 00:00:00 2001 From: "CORE-FOLDCC\\Core" <1813547935@qq.com> Date: Fri, 10 Apr 2026 22:53:42 +0800 Subject: [PATCH] Consolidate root documentation --- Brisk Package 发布流程.md | 110 ------- Brisk Unity SDK 实施计划.md | 202 ------------ Brisk Unity SDK 快速开始.md | 159 ---------- Brisk Unity SDK 设计草案.md | 600 ------------------------------------ README.md | 127 ++++++++ 5 files changed, 127 insertions(+), 1071 deletions(-) delete mode 100644 Brisk Package 发布流程.md delete mode 100644 Brisk Unity SDK 实施计划.md delete mode 100644 Brisk Unity SDK 快速开始.md delete mode 100644 Brisk Unity SDK 设计草案.md create mode 100644 README.md diff --git a/Brisk Package 发布流程.md b/Brisk Package 发布流程.md deleted file mode 100644 index a8e1e69..0000000 --- a/Brisk Package 发布流程.md +++ /dev/null @@ -1,110 +0,0 @@ -# Brisk Package 发布流程 - -本文档用于约定当前仓库的发布方式。 - -仓库地址： - -- `http://private.lightyears.ltd:18650/foldcc/CC-Framework.BriskGameServer.git` - -## 开发态 - -当前仓库是 Unity 原始开发工程： - -- SDK 活代码放在 `Assets/BriskSdk/Runtime` -- 示例脚本放在 `Assets/BriskSdk/Samples/QuickStart` -- 示例场景放在 `Assets/Scenes/BriskQuickStartScene.unity` - -## 发布态 - -对外发布 Git Package 时，不直接把整个 Unity 工程作为包发布。 - -统一从以下目录产出 package 内容： - -- `PackageSource/com.foldcc.cc-framework.BriskGameServer` - -该目录用于承载： - -- `package.json` -- `README.md` -- `CHANGELOG.md` -- `Documentation~` -- `Runtime` -- `Samples~` - -## 同步步骤 - -在准备发布分支或发布 tag 前，执行： - -```powershell -./Tools/Sync-BriskPackage.ps1 -``` - -脚本会自动： - -1. 从 `Assets/BriskSdk/Runtime` 同步到 `PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime` -2. 从 `Assets/BriskSdk/Samples/QuickStart` 同步到 `PackageSource/com.foldcc.cc-framework.BriskGameServer/Samples~/QuickStart` -3. 把 `Assets/Scenes/BriskQuickStartScene.unity` 一并复制到 package sample 目录 - -## 分支与 Tag 规范 - -建议采用以下命名： - -- 日常开发分支： - - `feature/...` - - `fix/...` -- 对外发包分支： - - `release/upm-vX.Y.Z` -- 对外发包 tag： - - `upm/vX.Y.Z` - -示例： - -- `release/upm-v0.1.0` -- `upm/v0.1.0` - -## 推荐发布动作 - -每次准备发版时，建议严格按以下顺序执行： - -1. 在开发分支完成 SDK 功能与测试 -2. 更新 `Assets` 下源码与示例场景 -3. 运行 `./Tools/Sync-BriskPackage.ps1` -4. 检查 `PackageSource/com.foldcc.cc-framework.BriskGameServer` 输出结果 -5. 更新 `package.json` 版本号 -6. 更新 `CHANGELOG.md` -7. 创建发布分支 `release/upm-vX.Y.Z` -8. 提交发布目录改动 -9. 打 tag `upm/vX.Y.Z` -10. 推送发布分支与 tag - -## 外部项目接入示例 - -外部项目通过 Git Package Manager 接入时，建议固定到 tag： - -```text -http://private.lightyears.ltd:18650/foldcc/CC-Framework.BriskGameServer.git?path=/PackageSource/com.foldcc.cc-framework.BriskGameServer#upm/v0.1.0 -``` - -这样做的好处： - -- 外部项目不会直接依赖整个 Unity 开发工程 -- 接入版本稳定，可回滚 -- package 内容和开发态源码解耦 - -## 当前注意事项 - -当前 `package.json` 中的包名仍然沿用既定命名： - -- `com.foldcc.cc-framework.BriskGameServer` - -这符合当前项目命名诉求，但从 UPM / npm 生态习惯看，正式大范围外发前，建议再确认一次是否需要改成全小写形式，以避免潜在兼容性问题。 - -## 建议发布流程 - -1. 在开发分支完成功能 -2. 运行 `./Tools/Sync-BriskPackage.ps1` -3. 检查 `PackageSource/com.foldcc.cc-framework.BriskGameServer` 内容 -4. 切到对外发布分支，或基于当前提交创建发布分支 -5. 只保留 package 所需目录，或以该子目录作为 git package 子路径 -6. 更新 `package.json` 版本号与 `CHANGELOG.md` -7. 打 tag 给外部项目接入 diff --git a/Brisk Unity SDK 实施计划.md b/Brisk Unity SDK 实施计划.md deleted file mode 100644 index 9561b32..0000000 --- a/Brisk Unity SDK 实施计划.md +++ /dev/null @@ -1,202 +0,0 @@ -# Brisk Unity SDK 实施计划 - -本文档用于记录 Brisk Unity SDK 的分阶段实施步骤，作为当前项目的实现路线图。 - -## 阶段 1：骨架与约束 - -目标： - -- 固定 SDK 的公开外形 -- 固定目录结构与命名 -- 建立可编译的基础代码骨架 - -范围： - -- 创建并完善 `Assets/BriskSdk/Runtime` 开发结构 -- 创建顶层入口 `Brisk` -- 创建基础对象： - - `BriskOptions` - - `BriskContext` - - `BriskSession` - - `BriskIdentity` -- 创建模块入口占位： - - `Brisk.Auth` - - `Brisk.Player` - - `Brisk.Config` - - `Brisk.Announcements` - - `Brisk.Leaderboard` - - `Brisk.Archive` - - `Brisk.Space` -- 创建基础异常与核心接口占位 -- 固定首版方法签名 -- 对齐新版后端身份模型： - - 初始化不再要求 `channel / platform` - - 登录改为 `login_provider / login_user_id / code` - -阶段完成标准： - -- Unity 工程内存在完整 SDK 运行时骨架 -- 代码可编译 -- 对外 API 入口已固定为 `Brisk.xxx` - -## 阶段 2：初始化与会话基础 - -目标： - -- 打通 SDK 生命周期入口 -- 打通 bootstrap 与本地会话恢复 - -范围： - -- 实现 `Brisk.InitializeAsync` -- 规范化 `BaseUrl` -- 调用 `GET /client/bootstrap` -- 缓存 bootstrap 结果 -- 接入本地 token 存储 -- 初始化时恢复本地会话 -- 可选调用 `player/me` 校验旧会话有效性 - -阶段完成标准： - -- SDK 能完成初始化 -- 能缓存 bootstrap 信息 -- 能恢复本地登录态 - -## 阶段 3：网络底层与严重错误处理 - -目标： - -- 打稳底层请求能力 -- 只统一接管严重错误 - -范围： - -- 实现 `BriskHttpClient` -- 实现统一 JSON 解包 -- 实现异常体系 -- 实现严重错误识别： - - 维护中 - - 封号 - - 登录态失效 -- 接入默认错误展示器 -- 支持项目方自定义严重错误展示 UI - -阶段完成标准： - -- 请求层可用 -- 严重错误可由 SDK 默认 UI 处理 -- 普通错误继续交由调用方自行处理 - -## 阶段 4：登录与玩家基础模块 - -目标： - -- 打通玩家态核心链路 - -范围： - -- 实现 `Brisk.Auth.LoginAsync` -- 或更明确地实现： - - `Brisk.Auth.LoginWithUserIdAsync` - - `Brisk.Auth.LoginWithCodeAsync` -- 实现 `Brisk.Auth.LogoutAsync` -- 实现 `Brisk.Player.GetMeAsync` -- 自动附加 Bearer Token -- 管理登录态与相关事件 - -阶段完成标准： - -- 初始化后可完成登录 -- 可获取当前玩家信息 - -## 阶段 5：首批高频业务模块 - -目标： - -- 覆盖首版最高频使用场景 - -范围： - -- `Brisk.Config` -- `Brisk.Announcements` -- `Brisk.Leaderboard` - -排行榜首版接口： - -- `GetTopAsync` -- `GetMeAsync` -- `GetAroundMeAsync` -- `SubmitScoreAsync` -- `GetCurrentSeasonAsync` -- `GetSeasonHistoryAsync` -- `GetSeasonHistoryDetailAsync` - -阶段完成标准： - -- SDK 已具备主要交付价值 -- 排行榜体验可用于首轮接入 - -## 阶段 6：差异化模块 - -目标： - -- 补齐 Brisk 的差异化能力 - -范围： - -- `Brisk.Archive` - - 槽位列表 - - 元信息 - - 上传 - - 下载 - - 版本冲突处理 - - 校验值处理 -- `Brisk.Space` - - 按 `player_id` 查询 - - 按 `login_provider + login_user_id` 查询 - - 点赞与取消点赞 - - 更新自己的空间 - - 我的访客 - -阶段完成标准： - -- 云存档和空间模块可实际使用 - -## 阶段 7：收尾与交付增强 - -目标： - -- 让 SDK 达到可交付、可接入状态 - -范围： - -- 默认本地存储实现 -- 默认错误展示 UI 完善 -- 日志开关与调试信息 -- 示例代码 -- Sample Scene -- 文档补充 -- 自测清单 - -补充约束： - -- 当前仓库作为 Unity 原始开发工程，活代码放在 `Assets/BriskSdk` -- 正式对外发包时，再从发布分支整理出 `PackageSource/com.foldcc.cc-framework.BriskGameServer` 子目录作为 UPM 包 - -阶段完成标准： - -- SDK 可以给外部开发者试接入 - -## 暂缓项 - -以下内容不阻塞首版主线： - -- 弱网模式与标准模式双策略 -- 更复杂的自动重试策略 -- 多套默认 UI 风格 -- 管理后台 SDK - -建议： - -- 首版先完成标准模式 -- 主线可用后再评估弱网模式 diff --git a/Brisk Unity SDK 快速开始.md b/Brisk Unity SDK 快速开始.md deleted file mode 100644 index 4ac7889..0000000 --- a/Brisk Unity SDK 快速开始.md +++ /dev/null @@ -1,159 +0,0 @@ -# Brisk Unity SDK 快速开始 - -本文档用于说明当前仓库内这套 Brisk Unity SDK 的最小接入方式。 - -## 1. 当前能力 - -当前 SDK 已经打通以下主链路： - -- 初始化 `Brisk.InitializeAsync` -- 本地会话恢复 -- 登录与登出 -- 玩家信息 -- 动态配置 -- 公告 -- 排行榜 -- 云存档 -- 玩家空间 - -当前主要源码位于： - -- `Assets/BriskSdk/Runtime` - -最小示例脚本位于： - -- `Assets/BriskSdk/Samples/QuickStart/BriskQuickStartSample.cs` - -## 2. 最小初始化 - -```csharp -await Brisk.InitializeAsync(new BriskOptions -{ - BaseUrl = "https://brisk.lightyears.ltd", - GameKey = "demo-game", - ClientVersion = Application.version, - DeviceId = SystemInfo.deviceUniqueIdentifier -}); -``` - -说明： - -- `BaseUrl` 必填 -- `GameKey` 必填 -- `ClientVersion` 可选但强烈建议传 -- `DeviceId` 可选但建议传 - -## 3. 登录示例 - -按稳定用户 ID 登录： - -```csharp -await Brisk.Auth.LoginWithUserIdAsync("tap", "tap_user_10001", new BriskProfile -{ - Nickname = "Player One" -}); -``` - -按 code 登录： - -```csharp -await Brisk.Auth.LoginWithCodeAsync("tap", "third-party-code"); -``` - -## 4. 常用调用示例 - -读取当前玩家： - -```csharp -var me = await Brisk.Player.GetMeAsync(); -``` - -读取动态配置： - -```csharp -var config = await Brisk.Config.GetCurrentAsync(); -``` - -读取排行榜： - -```csharp -var top = await Brisk.Leaderboard.GetTopAsync("season-score", 20); -var meRank = await Brisk.Leaderboard.GetMeAsync("season-score"); -await Brisk.Leaderboard.SubmitScoreAsync("season-score", 128); -``` - -上传云存档： - -```csharp -var bytes = System.Text.Encoding.UTF8.GetBytes("{\"save\":1}"); -await Brisk.Archive.UploadAsync(1, bytes); -``` - -读取玩家空间： - -```csharp -var space = await Brisk.Space.GetByLoginIdentityAsync("tap", "tap_user_10001"); -``` - -## 5. 默认错误 UI - -当前 SDK 已内置默认错误展示器： - -- 维护中 -- 封号 -- 登录态失效 - -如果未自定义 `ErrorPresenter`，SDK 会自动使用默认 IMGUI 弹窗进行展示。 - -如需替换： - -```csharp -Brisk.SetErrorPresenter(myPresenter); -``` - -接口为： - -```csharp -public interface IBriskErrorPresenter -{ - void ShowBlockingError(BriskBlockingException exception); - void ShowAuthExpired(BriskAuthExpiredException exception); -} -``` - -如需在阻断错误确认后执行你自己的退出逻辑： - -```csharp -await Brisk.InitializeAsync(new BriskOptions -{ - BaseUrl = "...", - GameKey = "...", - ExitHandler = () => Application.Quit() -}); -``` - -## 6. 示例脚本使用方式 - -当前项目已提供： - -- `Assets/BriskSdk/Samples/QuickStart/BriskQuickStartSample.cs` -- `Assets/Scenes/BriskQuickStartScene.unity` - -使用方式： - -1. 当前仓库是原始 Unity 开发工程，可直接打开 `Assets/Scenes/BriskQuickStartScene.unity` -2. 运行后会看到一个 IMGUI 调试面板，可直接测试初始化、登录、玩家、配置、公告、排行榜、云存档、空间等完整流程 -3. 勾选 `AutoRunOnStart` -4. 如需更换环境参数，可在 Inspector 里修改 `BaseUrl`、`GameKey`、`LoginProvider`、`LoginUserId` 等字段后再运行 - -也可以在组件右键菜单里执行： - -- `Run Brisk Sample` - -## 7. 当前实现状态 - -当前 SDK 已实现主流程，但还建议后续继续补： - -- 更细粒度的业务异常类型 -- 弱网策略 -- 更完整的接入文档与注释 diff --git a/Brisk Unity SDK 设计草案.md b/Brisk Unity SDK 设计草案.md deleted file mode 100644 index 0eeb0ce..0000000 --- a/Brisk Unity SDK 设计草案.md +++ /dev/null @@ -1,600 +0,0 @@ -# Brisk Unity SDK 设计草案 - -本文档用于沉淀当前 Brisk Unity SDK 的首版设计方向，目标是： - -- 对开发者极简易用 -- 初始化一次后，各模块可直接调用 -- 保持内部结构清晰，便于后续扩展 -- 优先围绕当前服务端已实现接口设计，不预埋过多未来能力 - -参考资料： - -- `服务参考_临时/Brisk Unity SDK接入文档.md` -- `服务参考_临时/Brisk API接口与示例文档.md` -- `服务参考_临时/Brisk 错误码文档（内部实施版）.md` -- `服务参考_临时/openapi.yaml` -- TapTap 官方 Unity 集成与排行榜文档 - -## 1. 设计目标 - -首版 SDK 对外遵循以下原则： - -- 对外统一使用 `Brisk.xxx` -- 模块能力统一使用 `Brisk.模块.xxx` -- 不暴露底层 HTTP、Envelope、Token 注入等细节 -- 初始化参数只保留项目级与设备级信息 -- 登录模型统一围绕 `login_provider / login_user_id / code` -- 初始化完成后，模块可直接调用 -- 错误码统一在 SDK 内部识别和分发 - -示例目标用法： - -```csharp -await Brisk.InitializeAsync(new BriskOptions -{ - BaseUrl = "https://brisk.lightyears.ltd", - GameKey = "demo-game", - ClientVersion = Application.version, - DeviceId = SystemInfo.deviceUniqueIdentifier -}); - -await Brisk.Auth.LoginWithUserIdAsync("tap", "tap_user_10001"); - -var me = await Brisk.Player.GetMeAsync(); -var top = await Brisk.Leaderboard.GetTopAsync("season-score", 20); -await Brisk.Leaderboard.SubmitScoreAsync("season-score", 128); -``` - -## 2. 对外 API 结构 - -首版建议公开如下 API 树： - -```csharp -Brisk.InitializeAsync(BriskOptions options) -Brisk.Shutdown() - -Brisk.IsInitialized -Brisk.IsLoggedIn -Brisk.AccessToken -Brisk.PlayerId -Brisk.Identity -Brisk.Options -Brisk.Bootstrap - -Brisk.Auth.LoginWithUserIdAsync(string loginProvider, string loginUserId, BriskProfile profile = null) -Brisk.Auth.LoginWithCodeAsync(string loginProvider, string code, BriskProfile profile = null) -Brisk.Auth.LogoutAsync() - -Brisk.Player.GetMeAsync() - -Brisk.Config.GetCurrentAsync() -Brisk.Config.RefreshAsync() - -Brisk.Announcements.GetListAsync() -Brisk.Announcements.MarkReadAsync(long id) - -Brisk.Leaderboard.GetTopAsync(string rankKey, int limit = 20) -Brisk.Leaderboard.GetMeAsync(string rankKey) -Brisk.Leaderboard.GetAroundMeAsync(string rankKey, int range = 10) -Brisk.Leaderboard.SubmitScoreAsync(string rankKey, long score) -Brisk.Leaderboard.GetCurrentSeasonAsync(string rankKey) -Brisk.Leaderboard.GetSeasonHistoryAsync(string rankKey, int limit = 20) -Brisk.Leaderboard.GetSeasonHistoryDetailAsync(string rankKey, string seasonId, int limit = 20) - -Brisk.Archive.GetSlotsAsync() -Brisk.Archive.GetMetaAsync(int slotNo) -Brisk.Archive.UploadAsync(int slotNo, byte[] bytes, int? baseVersion = null, string checksum = null) -Brisk.Archive.DownloadAsync(int slotNo) - -Brisk.Space.GetByPlayerIdAsync(string playerId) -Brisk.Space.GetByLoginIdentityAsync(string loginProvider, string loginUserId) -Brisk.Space.GetStatsByPlayerIdAsync(string playerId) -Brisk.Space.GetStatsByLoginIdentityAsync(string loginProvider, string loginUserId) -Brisk.Space.LikeByPlayerIdAsync(string playerId) -Brisk.Space.UnlikeByPlayerIdAsync(string playerId) -Brisk.Space.LikeByLoginIdentityAsync(string loginProvider, string loginUserId) -Brisk.Space.UnlikeByLoginIdentityAsync(string loginProvider, string loginUserId) -Brisk.Space.UpdateMyAsync(object payload) -Brisk.Space.GetMyVisitsAsync() -``` - -说明： - -- `bootstrap` 不单独暴露成模块入口，直接并入 `Brisk.InitializeAsync` -- `Brisk` 根节点只负责全局状态、生命周期、事件和模块入口 -- 具体业务能力放在 `Brisk.Auth`、`Brisk.Leaderboard` 等模块下 - -## 3. BriskOptions 设计 - -`BriskOptions` 只保留当前服务端确实需要的参数，并区分必填与推荐字段。 - -### 3.1 必填字段 - -根据当前服务端文档，以下字段应为初始化必填： - -```csharp -public sealed class BriskOptions -{ - public string BaseUrl; - public string GameKey; - public string ClientVersion; -} -``` - -原因： - -- `BaseUrl` - - SDK 所有接口的基础地址 - - 推荐直接传 API Base，例如 `https://host/api` -- `GameKey` - - `bootstrap`、`config/current`、`auth/login/exchange` 都需要 -- `ClientVersion` - - 当前服务端接口中为可选，但强烈建议传入 - - 会影响最低版本校验与动态配置命中 - -### 3.2 推荐字段 - -这些字段不是所有场景必填，但推荐在初始化时一次传入，后续由 SDK 自动复用： - -```csharp -public sealed class BriskOptions -{ - public string BaseUrl; - public string GameKey; - public string ClientVersion; - public string DeviceId; - public bool EnableLog = false; - public bool ValidateSessionOnInitialize = true; - public IBriskTokenStore TokenStore; - public IBriskErrorPresenter ErrorPresenter; - public Action ExitHandler; -} -``` - -说明： - -- `ClientVersion` - - `bootstrap`、`config/current`、`login` 推荐传入 - - 后续可用于最低版本校验 -- `DeviceId` - - `bootstrap`、`config/current`、`login` 推荐传入 - - 便于服务端做环境识别与问题排查 -- `EnableLog` - - 是否输出 SDK 调试日志 -- `ValidateSessionOnInitialize` - - 初始化时如果本地有 token，是否自动调用 `player/me` 校验有效性 -- `TokenStore` - - 登录态持久化存储接口 -- `ErrorPresenter` - - 默认错误弹窗展示接口 -- `ExitHandler` - - 遇到需要默认退出的阻断错误时，由宿主游戏接管实际退出逻辑 - -### 3.3 首版初始化建议 - -为了保持易用，首版建议如下： - -- 调用方最少只需要传 `BaseUrl`、`GameKey` -- `ClientVersion` 强烈建议传 -- `DeviceId` 建议有就传 -- 如果不传 `TokenStore`，SDK 使用默认本地实现 -- 如果不传 `ErrorPresenter`，SDK 使用默认实现或仅触发事件 -- 如果不传 `ExitHandler`，SDK 不直接强制退出，而是交给项目层自行处理 - -## 4. 初始化生命周期 - -`Brisk.InitializeAsync` 的建议流程如下： - -### 4.1 标准流程 - -```txt -1. 校验 BriskOptions -2. 规范化 BaseUrl -3. 初始化 Core 运行时对象 -4. 调用 GET /client/bootstrap -5. 缓存 bootstrap 结果 -6. 根据 bootstrap 检查维护状态与最低版本 -7. 初始化各模块入口 -8. 从 TokenStore 恢复本地 token -9. 如果配置了 ValidateSessionOnInitialize 且存在 token，则调用 GET /player/me 验证会话 -10. 进入可用状态 -``` - -### 4.2 具体建议 - -- `BaseUrl` 允许调用方传： - - `https://host/api` - - 或 `https://host` -- SDK 内部统一规范化为最终 API Base -- 初始化阶段不依赖 `login_provider / login_user_id` -- `bootstrap` 结果建议缓存到： - - `Brisk.Bootstrap` -- 如果初始化阶段检测到以下情况，直接触发全局阻断错误： - - 项目维护中 - - 最低版本不满足 - - 本地恢复到的账号已失效或已封禁 - -### 4.3 不建议的行为 - -首版不建议做以下事情： - -- 不自动静默重新登录 - - 当前服务端没有 refresh token 机制 -- 不在初始化中自动执行第三方平台登录 - - 第三方登录由游戏侧完成，Brisk 只负责兑换 Brisk 会话 -- 不把所有模块的预加载都塞进初始化 - - 公告、排行榜、空间等业务数据由调用方按需拉取 - -## 5. 登录态设计 - -首版登录核心模型： - -```txt -login_provider + login_user_id -> POST /auth/login/exchange -> Brisk access_token -或 -login_provider + code -> POST /auth/login/exchange -> Brisk access_token -``` - -身份建议分为两层： - -- 外部身份 - - `login_provider` - - `login_user_id` -- 内部身份 - - `player_id` - - `project_account_id` - -推荐登录行为： - -```txt -1. 游戏先完成第三方平台登录 -2. 游戏拿到 `login_provider` -3. 再拿到 `login_user_id` 或 `code` -4. 调用 `Brisk.Auth.LoginWithUserIdAsync(...)` 或 `Brisk.Auth.LoginWithCodeAsync(...)` -5. SDK 保存 token、过期时间、player_id、project_account_id -6. 后续玩家态接口自动附带 Bearer Token -``` - -## 6. 错误处理总设计 - -首版错误处理原则改为： - -- SDK 只统一接管严重阻断错误 -- 普通接口错误不走全局监听 -- 普通接口错误由调用方在调用处自行处理 -- SDK 默认提供一套阻断错误弹窗 UI -- 开发者可以替换默认 UI 或自行接管严重错误 - -内部处理链路建议如下： - -```txt -BriskHttpClient --> BriskResponseParser --> BriskErrorClassifier --> 严重错误进入 SDK 全局处理 --> 普通错误直接返回给当前调用方 -``` - -职责划分： - -- `BriskHttpClient` - - 发请求、收响应、拿到 HTTP 状态码 -- `BriskResponseParser` - - 解析 `code/message/data` -- `BriskErrorClassifier` - - 把错误码映射成 SDK 语义错误 -- 严重错误全局处理 - - 只处理维护、封号、登录态失效等阻断错误 -- 普通错误调用点处理 - - 由调用方 `try/catch` - - 或由调用方传入当前接口自己的回调处理 - -## 7. 错误分级 - -首版建议将错误分为以下几类： - -```csharp -public enum BriskErrorKind -{ - Retryable, - Business, - AuthExpired, - GlobalBlocking, - Fatal -} -``` - -说明： - -- `Retryable` - - 超时、网络抖动、429、临时服务不可用 -- `Business` - - 普通业务失败，例如存档冲突、参数不合法 - - 不进入 SDK 全局错误处理 -- `AuthExpired` - - 登录态失效，需要清理会话 - - 属于 SDK 全局接管范围 -- `GlobalBlocking` - - 封号、维护中、强制更新等，需要阻断当前玩家继续操作 - - 属于 SDK 全局接管范围 -- `Fatal` - - SDK 未初始化、关键配置错误、内部不可恢复异常 - - 只用于真正不可恢复的框架级错误 - -## 8. 错误码映射建议 - -根据当前错误码文档，首版建议如下处理： - -### 8.1 AuthExpired - -- `10001` 缺少 token -- `10002` token 无效 -- `10023` 缺少会话 - -默认行为： - -- 清空本地 token -- 更新 `Brisk.IsLoggedIn = false` -- 触发 `Brisk.OnAuthExpired` -- 默认弹出登录态失效提示 UI -- 抛出 `BriskAuthExpiredException` - -### 8.2 GlobalBlocking - -- `10003` 项目维护中 -- `10004` 玩家已封禁 -- `10005` 访问校验失败 -- `10025` 项目维护中 -- `10026` 玩家已封禁 - -默认行为： - -- 触发 `Brisk.OnBlockingError` -- 使用 SDK 默认 UI 弹出阻断提示 -- 如果开发者自定义了 `ErrorPresenter`，则由开发者 UI 接管展示 -- 是否退出程序由 `ExitHandler` 决定，不在网络底层写死 - -进一步建议： - -- `10003`、`10025` -> `Maintenance` -- `10004`、`10026` -> `AccountBanned` -- `10005` -> `AccessDenied` - -### 8.3 Retryable - -- `80001` 请求过于频繁 -- `80002` 限流服务不可用 - -默认行为： - -- 短退避重试 -- 超过最大次数后抛出异常 -- 不触发全局 UI - -### 8.4 Business - -- `60016` 存档版本冲突 -- `60017` 校验值不匹配 -- `60018` 存档超出大小限制 -- `60021` 存档不存在 -- `70011` 玩家不存在 -- `70017` 玩家不存在 -- `70020` 玩家不存在 - -默认行为： - -- 不做系统级强拦截 -- 不走全局错误监听 -- 抛出对应业务异常，由调用方决定如何提示 -- 如果未来个别接口希望提供便利用法，可在该接口额外支持传入当前调用专属回调 - -## 9. 异常类命名建议 - -首版建议使用以下异常层次： - -```csharp -BriskException -BriskNetworkException -BriskHttpException -BriskApiException -BriskBusinessException -BriskAuthExpiredException -BriskBlockingException -BriskMaintenanceException -BriskAccountBannedException -BriskRateLimitException -BriskArchiveConflictException -BriskArchiveChecksumException -BriskArchiveTooLargeException -BriskNotInitializedException -``` - -说明： - -- `BriskException` - - SDK 所有异常的统一基类 -- `BriskApiException` - - 已成功收到接口响应，但 `code != 0` -- `BriskBusinessException` - - 普通业务错误 -- `BriskAuthExpiredException` - - 登录态失效 -- `BriskBlockingException` - - 全局阻断错误的公共基类 -- `BriskMaintenanceException` - - 维护中 -- `BriskAccountBannedException` - - 账号封禁 -- `BriskNotInitializedException` - - 未初始化即调用模块接口 - -## 10. 全局事件命名建议 - -首版建议 `Brisk` 根节点提供以下全局事件： - -```csharp -Brisk.OnInitialized -Brisk.OnLoggedIn -Brisk.OnLoggedOut -Brisk.OnAuthExpired -Brisk.OnBlockingError -``` - -建议语义： - -- `OnInitialized` - - SDK 初始化完成 -- `OnLoggedIn` - - 登录成功 -- `OnLoggedOut` - - 主动登出完成 -- `OnAuthExpired` - - 登录态失效 -- `OnBlockingError` - - 维护、封号、访问阻断等全局错误 - -可选接管接口： - -```csharp -Brisk.SetErrorPresenter(IBriskErrorPresenter presenter) -Brisk.SetExitHandler(Action exitHandler) -``` - -## 11. 关于“底层直接弹窗并退出程序”的建议 - -这个方向本身是合理的，但不建议把“弹窗”和“退出程序”都硬编码在网络底层。 - -更推荐的做法是： - -```txt -网络底层识别错误 --> 严重错误交给 SDK 核心处理 --> 默认错误展示器弹窗 --> 是否退出由宿主游戏或 ExitHandler 决定 -``` - -这样做的好处： - -- 设计更常规 -- 便于项目方接管 UI 风格 -- 便于区分“该回登录页”还是“该退出程序” -- 避免网络层和游戏表现层耦合过深 -- 避免普通接口错误被 SDK 过度吞掉或误处理 - -具体建议： - -- `登录态失效` - - 默认不退出程序 - - 默认弹窗提示后清会话并回登录流程 -- `账号封禁` - - 默认弹窗提示后由项目方决定回登录页或退出 -- `维护中` - - 默认阻断流程并提示 -- `Fatal` - - 可以作为最接近“提示后退出”的类型 - -## 12. 可选扩展：标准模式与弱网模式 - -这项需求合理，但优先级建议放在首版正常逻辑之后。 - -后续可以考虑增加： - -```csharp -public enum BriskNetworkMode -{ - Standard, - WeakNetwork -} -``` - -两者差异可以主要体现在： - -- 重试次数 -- 超时时间 -- 429 退避策略 -- 是否对部分只读接口自动重试 - -建议首版先只做： - -- 一个默认标准策略 -- 策略入口预留在 `BriskOptions` - -例如： - -```csharp -public sealed class BriskOptions -{ - public BriskNetworkMode NetworkMode = BriskNetworkMode.Standard; -} -``` - -但首版实现只落 `Standard` 即可。 - -## 13. 首版内部结构建议 - -```txt -Assets/ - BriskSdk/ - Runtime/ - Core/ - Brisk.cs - BriskOptions.cs - BriskContext.cs - BriskSession.cs - BriskHttpClient.cs - BriskModuleExecutor.cs - BriskErrorClassifier.cs - Auth/ - Player/ - Config/ - Announcement/ - Leaderboard/ - Archive/ - Space/ - Models/ - Storage/ - Exceptions/ - Samples/ - QuickStart/ - Scenes/ - BriskQuickStartScene.unity - -PackageSource/ - com.foldcc.cc-framework.BriskGameServer/ - package.json - README.md - CHANGELOG.md - Documentation~/ -``` - -对外尽量只暴露： - -- `Brisk` -- `BriskOptions` -- 各模块入口类 -- 结果数据结构 -- 必要异常类 - -## 14. 当前阶段结论 - -当前已明确的设计结论： - -- 对外统一使用 `Brisk.xxx` -- 初始化完成后各模块直接可用 -- 初始化参数不再包含 `channel / platform` -- 登录模型统一为 `login_provider / login_user_id / code` -- `BriskOptions` 最少只要求 `BaseUrl`、`GameKey` -- `ClientVersion` 为可选但强烈建议传入 -- 网络底层负责识别错误，不直接写死 UI 和退出行为 -- SDK 核心负责全局错误策略、全局事件和默认表现 -- “弱网模式”作为后续扩展项预留，不阻塞首版实现 - -## 15. 下一步建议 - -建议按以下顺序继续推进： - -1. 先搭 SDK 骨架与目录结构 -2. 先实现 `Brisk.InitializeAsync` -3. 先打通 `Auth`、`Player`、`Leaderboard` -4. 再接入 `Archive` 的二进制上传下载 -5. 最后补充全局错误展示器与默认本地存储实现 diff --git a/README.md b/README.md new file mode 100644 index 0000000..de8f10a --- /dev/null +++ b/README.md @@ -0,0 +1,127 @@ +# BriskGameServer + +Brisk Unity SDK 原始开发工程。 + +这个仓库本身是 Unity 工程，用于日常开发、测试、联调和后续迭代；对外发布的 UPM package 不直接使用整个仓库，而是从子目录产出。 + +## 当前状态 + +当前 SDK 已完成主流程能力： + +- SDK 初始化与 bootstrap +- 本地会话恢复 +- 按 `login_user_id` 登录 +- 按 `code` 登录 +- 玩家信息 +- 动态配置 +- 公告 +- 排行榜 +- 云存档 +- 玩家空间 +- 严重错误默认 IMGUI 提示 + +静态入口保持为： + +- `Brisk.xxx` +- `Brisk.Auth.xxx` +- `Brisk.Leaderboard.xxx` + +## 工程结构 + +开发态源码与样例位于： + +- `Assets/BriskSdk/Runtime` +- `Assets/BriskSdk/Samples/QuickStart` +- `Assets/Scenes/BriskQuickStartScene.unity` + +其中： + +- `Runtime` 是 SDK 活代码 +- `Samples/QuickStart` 是示例脚本与样例程序集 +- `BriskQuickStartScene.unity` 是中文 IMGUI 测试场景 + +服务端参考文档位于： + +- `服务参考_临时` + +## 测试场景 + +直接打开： + +- `Assets/Scenes/BriskQuickStartScene.unity` + +运行后会看到一个中文 IMGUI 调试面板，可直接测试： + +- 初始化与重新初始化 +- 按用户 ID 登录 +- 按 code 登录 +- 玩家信息与配置 +- 公告读取与已读 +- 排行榜读取、提交分数、赛季查询 +- 云存档上传下载 +- 玩家空间读取、点赞、更新、访客 +- 全局事件日志与最近一次结果输出 + +## 发布结构 + +对外 package 发布目录位于： + +- `PackageSource/com.foldcc.cc-framework.BriskGameServer` + +该目录承载： + +- `package.json` +- `README.md` +- `CHANGELOG.md` +- `Documentation~` +- `Runtime` +- `Samples~` + +外部项目应通过这个子目录接入，而不是直接依赖整个 Unity 工程。 + +## 同步 package + +从开发态源码同步到发布目录时，执行： + +```powershell +./Tools/Sync-BriskPackage.ps1 +``` + +脚本会自动把以下内容同步到 package 子目录： + +1. `Assets/BriskSdk/Runtime` -> `PackageSource/com.foldcc.cc-framework.BriskGameServer/Runtime` +2. `Assets/BriskSdk/Samples/QuickStart` -> `PackageSource/com.foldcc.cc-framework.BriskGameServer/Samples~/QuickStart` +3. `Assets/Scenes/BriskQuickStartScene.unity` -> package sample 目录 + +## 发布规范 + +建议分支与 tag 约定如下： + +- 开发分支：`feature/...`、`fix/...` +- 发包分支：`release/upm-vX.Y.Z` +- 发包 tag：`upm/vX.Y.Z` + +推荐发布步骤： + +1. 在开发分支完成功能与测试 +2. 运行 `./Tools/Sync-BriskPackage.ps1` +3. 检查 `PackageSource/com.foldcc.cc-framework.BriskGameServer` +4. 更新 `package.json` 版本号与 `CHANGELOG.md` +5. 创建发布分支 `release/upm-vX.Y.Z` +6. 打 tag `upm/vX.Y.Z` +7. 推送发布分支与 tag + +外部项目 Git Package 接入示例： + +```text +http://private.lightyears.ltd:18650/foldcc/CC-Framework.BriskGameServer.git?path=/PackageSource/com.foldcc.cc-framework.BriskGameServer#upm/v0.1.0 +``` + +## 文档位置 + +仓库根目录只保留这一份总 README。 + +对外接入文档请看： + +- `PackageSource/com.foldcc.cc-framework.BriskGameServer/README.md` +- `PackageSource/com.foldcc.cc-framework.BriskGameServer/Documentation~/QuickStart.md`