CC-Framework.BriskGameServer/服务参考_临时/Brisk Unity SDK接入文档.md

# Brisk Unity SDK接入文档

## 1. 这份文档适合做什么

这份文档用于说明当前 Brisk Unity SDK 的接入结构与推荐调用方式。

当前 SDK 已采用静态总入口：

- `Brisk.InitializeAsync(...)`
- `Brisk.Auth.xxx`
- `Brisk.Player.xxx`
- `Brisk.Config.xxx`
- `Brisk.Announcements.xxx`
- `Brisk.Leaderboard.xxx`
- `Brisk.Archive.xxx`
- `Brisk.Space.xxx`

## 2. 初始化模型

Unity 客户端初始化建议持有：

- `baseUrl`
- `gameKey`（必填）
- `clientVersion`（推荐传入；服务端接口当前可选，但会影响版本命中）
- `deviceId`（推荐传入；`bootstrap` 接口当前可选）

不再需要项目级 `channel / platform`。

示例：

```csharp
var options = new BriskOptions {
    BaseUrl = "https://brisk.lightyears.ltd",
    GameKey = "demo-game",
    ClientVersion = Application.version,
    DeviceId = SystemInfo.deviceUniqueIdentifier
};
```

## 3. 登录模型

登录属于独立模块，不属于初始化参数。

Unity 登录接口建议统一成：

```csharp
Task<LoginResult> LoginAsync(
    string loginProvider,
    string loginUserId = null,
    string code = null,
    string nickname = null,
    string avatarUrl = null,
    Dictionary<string, object> profileJson = null
)
```

说明：

- `loginProvider`：如 `tap`
- `loginUserId`：平台返回的稳定唯一用户 ID
- `code`：如果平台走 code 兑换模式则传这个
- `loginUserId` 和 `code` 二选一
- `nickname / avatarUrl / profileJson` 为可选同步资料

## 4. 推荐接入顺序

1. `BootstrapAsync()`
2. 从第三方 SDK 获取：
   - `loginProvider`
   - `loginUserId` 或 `code`
   - 可选昵称、头像、扩展资料
3. `LoginAsync(...)`
4. 保存 `accessToken`
5. 拉取：
   - `GetMeAsync()`
   - `GetCurrentConfigAsync()`
   - `ListAnnouncementsAsync()`
6. 进入业务模块

## 5. 身份模型建议

Unity SDK 内建议同时保存两套身份：

- 外部身份：
  - `LoginProvider`
  - `LoginUserId`
- 内部身份：
  - `PlayerId`
  - `ProjectAccountId`

原因：

- 跨系统跳转、和第三方 SDK 共存时，外部身份更方便
- 游戏内高频接口仍以内部 `player_id` 为主更自然

## 6. 空间跳转建议

如果排行榜头像点击来自第三方平台，推荐直接支持：

```csharp
Task<SpaceInfo> GetSpaceByLoginIdentityAsync(string loginProvider, string loginUserId)
Task<SpaceStats> GetSpaceStatsByLoginIdentityAsync(string loginProvider, string loginUserId)
Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId)
```

这样可以避免 Unity 侧先做一次平台 ID 到 Brisk `player_id` 的映射查询。

## 7. 排行榜模块建议

客户端侧建议封装：

- `GetRankTopAsync(rankKey, limit)`
- `GetRankMeAsync(rankKey)`
- `GetRankAroundMeAsync(rankKey, range)`
- `SubmitScoreAsync(rankKey, score)`
- `GetCurrentSeasonAsync(rankKey)`
- `GetSeasonHistoryAsync(rankKey, limit)`
- `GetSeasonHistoryDetailAsync(rankKey, seasonId, limit)`

榜单项需要暴露：

- `Rank`
- `PlayerId`
- `ProjectAccountId`
- `LoginProvider`
- `LoginUserId`
- `Score`
- `Nickname`
- `AvatarUrl`

## 8. 云存档模块建议

云存档适合承载真实游戏数据。

原因：

- 上传下载是二进制流
- 天然适配 bytes
- 可直接存：
  - JSON bytes
  - protobuf bytes
  - msgpack bytes
  - 压缩后的存档二进制

当前 SDK 已提供：

- `GetArchiveSlotsAsync()`
- `GetArchiveMetaAsync(slotNo)`
- `UploadAsync(slotNo, byte[], baseVersion, checksum)`
- `UploadTextAsync(slotNo, text, baseVersion, checksum)`
- `UploadJsonAsync(slotNo, payload, baseVersion, checksum)`
- `DownloadArchiveAsync(slotNo)`
- `DownloadTextAsync(slotNo)`
- `DownloadJsonAsync(slotNo)`

推荐上层使用策略：

- 文本存档：优先直接用 `UploadTextAsync / DownloadTextAsync`
- JSON 存档：优先直接用 `UploadJsonAsync / DownloadJsonAsync`
- 二进制存档：继续用 `UploadAsync / DownloadAsync`

其中：

- SDK 会自动计算上传用 `checksum`
- 手动传 `checksum` 时也可以带 `sha256:` 前缀，SDK 会自动归一化

## 9. 玩家空间模块建议

玩家空间适合承载公开展示数据或空间自定义内容，不再限制为 JSON。

推荐放：

- 简介文本
- 头像展示字段
- 成就展示摘要
- 公开资料卡
- 小型二进制空间内容
- 文本、JSON、protobuf、msgpack 等自定义格式

当前 SDK / 接口核心是：

- `UploadMySpaceContentAsync(baseVersion, contentType, checksum, byte[])`
- `DownloadSpaceContentByPlayerIdAsync(playerId)`
- `DownloadSpaceContentByLoginIdentityAsync(loginProvider, loginUserId)`
- `GetSpaceByPlayerIdAsync(playerId)`
- `GetSpaceByLoginIdentityAsync(loginProvider, loginUserId)`
- `LikeSpaceAsync(playerId)`
- `LikeSpaceByLoginIdentityAsync(loginProvider, loginUserId)`
- `GetMyVisitsAsync(limit)`

当前 SDK 额外提供了一个极简便捷入口：

- `Brisk.Space.UpdateMyAsync(payload, baseVersion, contentType, checksum)`

它的行为是：

- `payload` 为 `string` 时，自动按 `text/plain` 上传
- `payload` 为 `byte[]` 时，自动按 `application/octet-stream` 上传
- `payload` 为其他对象时，自动序列化为 JSON 并按 `application/json` 上传

建议 SDK 暴露两层模型：

- 空间主信息：
  - `ContentExists`
  - `ContentVersion`
  - `ContentType`
  - `ContentSizeBytes`
  - `ContentChecksum`
  - `LikeCount`
  - `VisitCount`
- 空间内容本体：
  - 原始 `byte[]`
  - 下载响应头中的 `X-Space-Version`
  - 下载响应头中的 `X-Space-Checksum`

如果上层业务追求最省事，可以直接用 `UpdateMyAsync(string)` 或 `UpdateMyAsync(object)`；
如果业务自己管理编码、压缩、protobuf、msgpack 等格式，则继续走 `byte[]` 上传下载接口。

## 10. 动态配置建议

动态配置拆为两层：

- `feature_flags`
  - 适合直接做开关或 key-value 判断
- `dynamic_config`
  - 适合结构化配置对象

Unity SDK 可以考虑：

- 把 `feature_flags` 映射成 `Dictionary<string, object>`
- 把 `dynamic_config` 保留原始 JSON，并允许上层自行反序列化

## 11. 错误与登录态处理

SDK 需要统一处理：

- HTTP 非 2xx
- 业务码非 0
- 401 / 登录态失效
- 维护模式
- 玩家被封禁
- 存档版本冲突

建议统一抛出：

```csharp
public sealed class BriskApiException : Exception {
    public int HttpStatus { get; }
    public int Code { get; }
    public string ServerMessage { get; }
}
```

## 12. Unity 侧最小落地清单

第一版 SDK 至少要覆盖：

1. 初始化
2. 登录换票
3. 登录态保存
4. 玩家信息读取
5. 动态配置读取
6. 公告读取与已读
7. 排行榜提交与读取
8. 云存档上传下载
9. 玩家空间读取、写入、点赞
10. 按 `login_provider + login_user_id` 访问空间

## 13. 配套文件

- API 总文档：
  - [Brisk API接口与示例文档.md](/F:/OtherWork/BriskGameSerivce/Brisk%20API%E6%8E%A5%E5%8F%A3%E4%B8%8E%E7%A4%BA%E4%BE%8B%E6%96%87%E6%A1%A3.md)
- OpenAPI：
  - [openapi.yaml](/F:/OtherWork/BriskGameSerivce/openapi.yaml)