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`