CC-Framework.BriskGameServer/README.md

# BriskGameServer

Brisk Unity SDK 原始开发工程。

这个仓库本身是 Unity 工程，用于日常开发、测试、联调和后续迭代；对外发布的 UPM package 不直接使用整个仓库，而是从子目录产出。

## 当前状态

当前 SDK 已完成主流程能力：

- SDK 初始化与 bootstrap
- 本地会话恢复
- 按 `login_user_id` 登录
- 按 `code` 登录
- 玩家信息
- 动态配置
- 公告
- 排行榜
- 云存档
- 玩家空间
- 严重错误默认 IMGUI 提示

内容型接口当前默认推荐用法：

- 云存档：
  - `Brisk.Archive.UploadAsync(slotNo, bytes)` 直接传二进制
  - `Brisk.Archive.UploadTextAsync(slotNo, text)` 直接传文本
  - `Brisk.Archive.UploadJsonAsync(slotNo, payload)` 直接传对象
  - `Brisk.Archive.DownloadAsync(slotNo)` 获取原始 bytes + 元信息
  - `Brisk.Archive.DownloadTextAsync(slotNo)` 直接取文本
  - `Brisk.Archive.DownloadJsonAsync(slotNo)` 直接取 JSON 对象
- 玩家空间：
  - `Brisk.Space.UpdateMyAsync(string)` 可直接更新文本内容
  - `Brisk.Space.UpdateMyAsync(byte[])` 可直接更新二进制内容
  - `Brisk.Space.UpdateMyAsync(object)` 会自动转成 JSON 上传
  - `Brisk.Space.DownloadContentByPlayerIdAsync(playerId)` 获取原始 bytes
  - `Brisk.Space.LikeByPlayerIdAsync(playerId)` / `UnlikeByPlayerIdAsync(playerId)` 会返回累计点赞数、今日点赞数、当前周期是否创建了新点赞、重置时间
  - `Brisk.Space.GetLikesByPlayerIdAsync(playerId, limit, true)` 可只读取当前周期点赞列表
  - `Brisk.Space.GetMyVisitsAsync()` 默认读取最近 `50` 条访问记录，也可手动传入 `limit`

云存档上传补充约定：

- SDK 默认会自动计算上传文件的 `checksum`
- 当前服务端要求的是纯 SHA256 十六进制字符串
- 不应传 `sha256:xxxx` 这类带算法前缀的值
- 如果手动传入 `checksum`，SDK 也会自动去掉 `sha256:` 前缀再发送

静态入口保持为：

- `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 登录
- 玩家信息与配置
- 公告读取与已读
- 排行榜读取、提交分数、赛季查询
- 云存档上传下载
- 玩家空间读取、点赞、更新、访客
- 玩家空间今日点赞数、今日点赞状态、今日点赞重置时间
- 全局事件日志与最近一次结果输出

当前样例已经直接使用 `UploadTextAsync` / `DownloadTextAsync` 这类快捷接口；如果业务需要，也可以继续走原始 bytes 接口。

## 发布结构

对外 package 发布目录位于：

- `PackageSource/com.foldcc.cc-framework.brisk-game-server`

该目录承载：

- `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.brisk-game-server/Runtime`
2. `Assets/BriskSdk/Samples/QuickStart` -> `PackageSource/com.foldcc.cc-framework.brisk-game-server/Samples~/QuickStart`
3. `Assets/Scenes/BriskQuickStartScene.unity` -> package sample 目录

## 发布规范

建议分支与 tag 约定如下：

- 开发分支：`feature/...`、`fix/...`
- 发包分支：`release/upm-vX.Y.Z`
- 发包 tag：`vX.Y.Z`

推荐发布步骤：

1. 在开发分支完成功能与测试
2. 运行 `./Tools/Sync-BriskPackage.ps1`
3. 检查 `PackageSource/com.foldcc.cc-framework.brisk-game-server`
4. 更新 `package.json` 版本号与 `CHANGELOG.md`
5. 创建发布分支 `release/upm-vX.Y.Z`
6. 打 tag `vX.Y.Z`
7. 推送发布分支与 tag

外部项目 Git Package 接入示例：

```text
http://private.lightyears.ltd:18650/foldcc/CC-Framework.BriskGameServer.git?path=/PackageSource/com.foldcc.cc-framework.brisk-game-server#v0.4.1
```

## 如何引入到项目

当前 Git 仓库地址：

- `http://private.lightyears.ltd:18650/foldcc/CC-Framework.BriskGameServer`

推荐通过 Unity Package Manager 的 Git URL 方式引入。

方式一：在 Unity 编辑器中操作

1. 打开 `Window > Package Manager`
2. 点击左上角 `+`
3. 选择 `Add package from git URL...`
4. 输入：

```text
http://private.lightyears.ltd:18650/foldcc/CC-Framework.BriskGameServer.git?path=/PackageSource/com.foldcc.cc-framework.brisk-game-server#v0.3.0
```

方式二：直接修改项目的 `Packages/manifest.json`

```json
{
  "dependencies": {
    "com.foldcc.cc-framework.brisk-game-server": "http://private.lightyears.ltd:18650/foldcc/CC-Framework.BriskGameServer.git?path=/PackageSource/com.foldcc.cc-framework.brisk-game-server#v0.4.1"
  }
}
```

如果要跟随主分支最新代码，可把末尾的 `#v0.4.1` 改成 `#main`；正式项目仍建议固定到发布 tag。

## 文档位置

仓库根目录只保留这一份总 README。

对外接入文档请看：

- `PackageSource/com.foldcc.cc-framework.brisk-game-server/README.md`
- `PackageSource/com.foldcc.cc-framework.brisk-game-server/Documentation~/QuickStart.md`