Initial Brisk Unity SDK project

2026-04-10 22:04:51 +08:00
commit 47f9a8bafa
171 changed files with 11091 additions and 0 deletions
--- a/API接口与示例文档.md
+++ b/API接口与示例文档.md
@@ -0,0 +1,319 @@
+# Brisk API接口与示例文档
+
+## 1. 核心约定
+
+- 项目唯一标识：`game_key`
+- 项目级 `channel / platform` 已移除
+- 初始化与动态配置：
+  - 必填 `game_key`
+  - 可选 `client_version`
+- 登录身份：
+  - `login_provider`
+  - `login_user_id`
+- 登录成功后服务端返回内部身份：
+  - `player_id`
+  - `project_account_id`
+  - `access_token`
+- 需要跨系统跳转玩家时，空间模块与后台排行榜查询支持直接传：
+  - `login_provider + login_user_id`
+
+## 2. 客户端主流程
+
+1. `GET /api/client/bootstrap`
+2. `POST /api/auth/login/exchange`
+3. 带 `Bearer access_token` 调用：
+   - `GET /api/player/me`
+   - `GET /api/announcements`
+   - 排行榜、存档、空间等业务接口
+4. `GET /api/config/current` 为公开接口，登录前后都可调用
+
+## 3. 初始化
+
+### 3.1 获取初始化信息
+
+`GET /api/client/bootstrap`
+
+查询参数：
+
+- `game_key`：必填
+- `client_version`：可选，建议传入；不传时只会命中不设版本范围的配置
+- `device_id`：可选
+
+示例：
+
+```bash
+curl "https://brisk.lightyears.ltd/api/client/bootstrap?game_key=demo-game&client_version=1.0.0&device_id=device-001"
+```
+
+返回重点：
+
+- `project_name`
+- `server_time`
+- `maintenance_mode`
+- `maintenance_message`
+- `feature_flags`
+- `dynamic_config`
+- `min_client_version`
+
+## 4. 登录
+
+### 4.1 登录换票
+
+`POST /api/auth/login/exchange`
+
+请求体：
+
+- `game_key`：必填
+- `login_provider`：必填，例如 `tap`
+- `login_user_id`：与 `code` 二选一
+- `code`：与 `login_user_id` 二选一
+- `device_id`：可选
+- `client_version`：可选
+- `nickname`：可选
+- `avatar_url`：可选
+- `profile_json`：可选对象
+
+示例：
+
+```bash
+curl -X POST "https://brisk.lightyears.ltd/api/auth/login/exchange" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "game_key": "demo-game",
+    "login_provider": "tap",
+    "login_user_id": "tap_user_10001",
+    "device_id": "android-001",
+    "client_version": "1.0.0",
+    "nickname": "Tap Player",
+    "avatar_url": "https://example.com/avatar.png",
+    "profile_json": {
+      "region": "cn",
+      "source": "tap"
+    }
+  }'
+```
+
+返回重点：
+
+- `access_token`
+- `expires_in`
+- `player_id`
+- `project_account_id`
+- `is_new_player`
+- `profile.login_provider`
+- `profile.login_user_id`
+
+## 5. 玩家与动态配置
+
+### 5.1 获取当前玩家
+
+`GET /api/player/me`
+
+返回重点：
+
+- `player_id`
+- `project_account_id`
+- `login_provider`
+- `login_user_id`
+- `nickname`
+- `avatar_url`
+- `profile_json`
+
+### 5.2 获取动态配置
+
+`GET /api/config/current`
+
+查询参数：
+
+- `game_key`：必填
+- `client_version`：可选，建议传入；不传时只会命中不设版本范围的配置
+
+说明：
+
+- `feature_flags` 现在是标准 key-value 对象
+- `dynamic_config` 保持为自定义 JSON 对象
+- 命中规则只看 `client_version`
+- 该接口当前无需 `Bearer access_token`
+
+示例：
+
+```bash
+curl "https://brisk.lightyears.ltd/api/config/current?game_key=demo-game&client_version=1.0.0"
+```
+
+## 6. 公告
+
+### 6.1 获取公告列表
+
+`GET /api/announcements`
+
+### 6.2 标记已读
+
+`POST /api/announcements/{id}/read`
+
+## 7. 排行榜
+
+### 7.1 客户端接口
+
+- `GET /api/ranks/{rank_key}/top`
+- `GET /api/ranks/{rank_key}/me`
+- `GET /api/ranks/{rank_key}/around-me`
+- `POST /api/ranks/{rank_key}/score`
+- `GET /api/ranks/{rank_key}/season/current`
+- `GET /api/ranks/{rank_key}/history`
+- `GET /api/ranks/{rank_key}/history/{season_id}`
+
+提交分数示例：
+
+```bash
+curl -X POST "https://brisk.lightyears.ltd/api/ranks/season-score/score" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"score": 128}'
+```
+
+排行榜返回项重点：
+
+- `rank`
+- `player_id`
+- `project_account_id`
+- `login_provider`
+- `login_user_id`
+- `score`
+- `nickname`
+- `avatar_url`
+
+### 7.2 后台排行榜接口
+
+- `GET /api/admin/ranks`
+- `POST /api/admin/ranks`
+- `PUT /api/admin/ranks/{rank_key}`
+- `DELETE /api/admin/ranks/{rank_key}`
+- `DELETE /api/admin/ranks/{rank_key}/players/{player_id}`
+- `GET /api/admin/ranks/{rank_key}/leaderboard`
+- `POST /api/admin/ranks/{rank_key}/reset`
+- `GET /api/admin/ranks/{rank_key}/seasons`
+- `GET /api/admin/ranks/{rank_key}/seasons/{season_id}/logs`
+
+后台当前榜单查询支持参数：
+
+- `project_id`
+- `page`
+- `page_size`
+- `player_id`
+- `project_account_id`
+- `login_provider`
+- `login_user_id`
+
+## 8. 云存档
+
+说明：
+
+- 云存档是二进制上传/下载接口
+- 适合直接存 Unity 存档 bytes、protobuf、msgpack、压缩包等
+- 不限制为 JSON
+
+接口：
+
+- `GET /api/archives/slots`
+- `GET /api/archives/slot/{slot_no}/meta`
+- `POST /api/archives/slot/{slot_no}/upload`
+- `GET /api/archives/slot/{slot_no}/download`
+
+上传示例：
+
+```bash
+curl -X POST "https://brisk.lightyears.ltd/api/archives/slot/1/upload" \
+  -H "Authorization: Bearer <token>" \
+  -F "base_version=0" \
+  -F "checksum=<sha256>" \
+  -F "file=@save.dat"
+```
+
+## 9. 玩家空间
+
+说明：
+
+- 空间数据当前为 `payload_json`
+- 适合公开资料、展示文案、轻量个性化内容
+- 如果是游戏主存档，请优先走云存档模块
+
+接口：
+
+- `PUT /api/spaces/me`
+- `GET /api/spaces/{player_id}`
+- `GET /api/spaces/{player_id}/stats`
+- `GET /api/spaces/{player_id}/likes`
+- `POST /api/spaces/{player_id}/like`
+- `DELETE /api/spaces/{player_id}/like`
+- `GET /api/spaces/me/visits`
+- `GET /api/spaces/by-login`
+- `GET /api/spaces/by-login/stats`
+- `GET /api/spaces/by-login/likes`
+- `POST /api/spaces/by-login/like`
+- `DELETE /api/spaces/by-login/like`
+
+按第三方身份查看空间示例：
+
+```bash
+curl "https://brisk.lightyears.ltd/api/spaces/by-login?login_provider=tap&login_user_id=tap_user_10001" \
+  -H "Authorization: Bearer <token>"
+```
+
+按第三方身份点赞示例：
+
+```bash
+curl -X POST "https://brisk.lightyears.ltd/api/spaces/by-login/like?login_provider=tap&login_user_id=tap_user_10001" \
+  -H "Authorization: Bearer <token>"
+```
+
+## 10. 后台项目与配置
+
+### 10.1 项目
+
+- `GET /api/admin/projects`
+- `GET /api/admin/projects/{id}`
+- `POST /api/admin/projects`
+- `PUT /api/admin/projects/{id}`
+- `DELETE /api/admin/projects/{id}`
+- `POST /api/admin/projects/{id}/icon`
+- `GET /api/admin/projects/{id}/icon`
+
+说明：
+
+- 创建项目时只传项目信息，不再传 `channel / platform`
+- `game_key` 由服务端自动生成
+
+### 10.2 当前动态配置
+
+- `GET /api/admin/configs/current?project_id=...`
+- `PUT /api/admin/configs/current`
+
+### 10.3 公告
+
+- `GET /api/admin/announcements`
+- `GET /api/admin/announcements/{id}`
+- `POST /api/admin/announcements`
+- `PUT /api/admin/announcements/{id}`
+- `DELETE /api/admin/announcements/{id}`
+
+### 10.4 玩家
+
+- `GET /api/admin/players`
+- `GET /api/admin/players/{player_id}`
+- `POST /api/admin/players/{player_id}/ban`
+- `POST /api/admin/players/{player_id}/unban`
+
+玩家列表支持筛选：
+
+- `project_id`
+- `player_id`
+- `project_account_id`
+- `login_provider`
+- `login_user_id`
+
+## 11. OpenAPI
+
+完整 OpenAPI 导出：
+
+- [openapi.yaml](/F:/OtherWork/BriskGameSerivce/openapi.yaml)