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

# Brisk Unity SDK接入文档

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

这份文档用于在 Unity 侧封装 Brisk SDK。

建议把 SDK 拆成以下层次：

- `BriskTime`
- `BriskClient`
- `BriskAuth`
- `BriskConfig`
- `BriskAnnouncements`
- `BriskRanks`
- `BriskArchives`
- `BriskSpaces`

## 2. 初始化模型

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

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

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

如果只是做平台授时，不需要传 `gameKey`，可以单独调用时间接口。

示例：

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

平台授时接口建议封装：

```csharp
Task<ServerTimeResult> SyncServerTimeAsync()
```

建议返回：

- `ServerTime`
- `ServerUnix`
- `ServerUnixMs`

## 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
  - 压缩后的存档二进制

Unity SDK 建议提供：

- `GetArchiveSlotsAsync()`
- `GetArchiveMetaAsync(slotNo)`
- `UploadArchiveAsync(slotNo, baseVersion, checksum, byte[])`
- `DownloadArchiveAsync(slotNo)`

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

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

推荐放：

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

当前接口核心是：

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

建议 SDK 暴露两层模型：

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

如果上层业务实际保存的是文本或 JSON，建议仍按 `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)