foldcc/CC-Framework.BriskGameServer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Consolidate root documentation

Browse Source
This commit is contained in:
CORE-FOLDCC\Core
2026-04-10 22:53:42 +08:00
parent ea5b96507d
commit e07a9086b1
5 changed files with 127 additions and 1071 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
Brisk Package 发布流程.md
View File

@@ -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 给外部项目接入

202
Brisk Unity SDK 实施计划.md
View File

@@ -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
建议：
- 首版先完成标准模式
- 主线可用后再评估弱网模式

159
Brisk Unity SDK 快速开始.md
View File

@@ -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 已实现主流程，但还建议后续继续补：
- 更细粒度的业务异常类型
- 弱网策略
- 更完整的接入文档与注释

600
Brisk Unity SDK 设计草案.md
View File

@@ -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. 最后补充全局错误展示器与默认本地存储实现

127
README.md Normal file
View File

@@ -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`