diff --git a/Assets/Scenes/BriskQuickStartScene.unity b/Assets/Scenes/BriskQuickStartScene.unity index 3230947..a8727fe 100644 --- a/Assets/Scenes/BriskQuickStartScene.unity +++ b/Assets/Scenes/BriskQuickStartScene.unity @@ -259,7 +259,7 @@ MonoBehaviour: m_Name: m_EditorClassIdentifier: BaseUrl: https://brisk.lightyears.ltd - GameKey: briskh5verify + GameKey: game_a1faf5ee93d0 ClientVersion: 1.0.0 DeviceId: editor-device ValidateSessionOnInitialize: 1 @@ -268,7 +268,7 @@ MonoBehaviour: LoginCode: Nickname: "Unity\u793A\u4F8B\u73A9\u5BB6" AvatarUrl: - RankKey: h5-verify-rank-20260410034312-5cdd + RankKey: rank-20260411062004-2bce SubmitScoreValue: 128 LeaderboardLimit: 10 AroundMeRange: 5 diff --git a/服务参考_临时/Brisk API接口与示例文档.md b/服务参考_临时/Brisk API接口与示例文档.md index 7f9b60e..6455fde 100644 --- a/服务参考_临时/Brisk API接口与示例文档.md +++ b/服务参考_临时/Brisk API接口与示例文档.md @@ -19,17 +19,41 @@ ## 2. 客户端主流程 -1. `GET /api/client/bootstrap` -2. `POST /api/auth/login/exchange` -3. 带 `Bearer access_token` 调用： +1. 可选：`GET /api/client/time` +2. `GET /api/client/bootstrap` +3. `POST /api/auth/login/exchange` +4. 带 `Bearer access_token` 调用： - `GET /api/player/me` - `GET /api/announcements` - 排行榜、存档、空间等业务接口 -4. `GET /api/config/current` 为公开接口，登录前后都可调用 +5. `GET /api/config/current` 为公开接口，登录前后都可调用 ## 3. 初始化 -### 3.1 获取初始化信息 +### 3.1 获取平台时间 + +`GET /api/client/time` + +说明： + +- 平台级匿名授时接口 +- 不需要 `game_key` +- 不依赖任何项目配置 +- 返回 UTC 时间，适合客户端启动时做统一对时 + +示例： + +```bash +curl "https://brisk.lightyears.ltd/api/client/time" +``` + +返回重点： + +- `server_time` +- `server_unix` +- `server_unix_ms` + +### 3.2 获取初始化信息 `GET /api/client/bootstrap` diff --git a/服务参考_临时/Brisk Unity SDK接入文档.md b/服务参考_临时/Brisk Unity SDK接入文档.md index 686107b..58f0def 100644 --- a/服务参考_临时/Brisk Unity SDK接入文档.md +++ b/服务参考_临时/Brisk Unity SDK接入文档.md @@ -2,18 +2,18 @@ ## 1. 这份文档适合做什么 -这份文档用于说明当前 Brisk Unity SDK 的接入结构与推荐调用方式。 +这份文档用于在 Unity 侧封装 Brisk SDK。 -当前 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` +- `BriskTime` +- `BriskClient` +- `BriskAuth` +- `BriskConfig` +- `BriskAnnouncements` +- `BriskRanks` +- `BriskArchives` +- `BriskSpaces` ## 2. 初始化模型 @@ -26,6 +26,8 @@ Unity 客户端初始化建议持有： 不再需要项目级 `channel / platform`。 +如果只是做平台授时，不需要传 `gameKey`，可以单独调用时间接口。 + 示例： ```csharp @@ -64,18 +66,31 @@ Task LoginAsync( ## 4. 推荐接入顺序 -1. `BootstrapAsync()` -2. 从第三方 SDK 获取： +1. 可选：`SyncServerTimeAsync()` +2. `BootstrapAsync()` +3. 从第三方 SDK 获取： - `loginProvider` - `loginUserId` 或 `code` - 可选昵称、头像、扩展资料 -3. `LoginAsync(...)` -4. 保存 `accessToken` -5. 拉取： +4. `LoginAsync(...)` +5. 保存 `accessToken` +6. 拉取： - `GetMeAsync()` - `GetCurrentConfigAsync()` - `ListAnnouncementsAsync()` -6. 进入业务模块 +7. 进入业务模块 + +平台授时接口建议封装： + +```csharp +Task SyncServerTimeAsync() +``` + +建议返回： + +- `ServerTime` +- `ServerUnix` +- `ServerUnixMs` ## 5. 身份模型建议 @@ -142,27 +157,12 @@ Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId) - msgpack bytes - 压缩后的存档二进制 -当前 SDK 已提供： +Unity SDK 建议提供： - `GetArchiveSlotsAsync()` - `GetArchiveMetaAsync(slotNo)` -- `UploadAsync(slotNo, byte[], baseVersion, checksum)` -- `UploadTextAsync(slotNo, text, baseVersion, checksum)` -- `UploadJsonAsync(slotNo, payload, baseVersion, checksum)` +- `UploadArchiveAsync(slotNo, baseVersion, checksum, byte[])` - `DownloadArchiveAsync(slotNo)` -- `DownloadTextAsync(slotNo)` -- `DownloadJsonAsync(slotNo)` - -推荐上层使用策略： - -- 文本存档：优先直接用 `UploadTextAsync / DownloadTextAsync` -- JSON 存档：优先直接用 `UploadJsonAsync / DownloadJsonAsync` -- 二进制存档：继续用 `UploadAsync / DownloadAsync` - -其中： - -- SDK 会自动计算上传用 `checksum` -- 手动传 `checksum` 时也可以带 `sha256:` 前缀，SDK 会自动归一化 ## 9. 玩家空间模块建议 @@ -177,7 +177,7 @@ Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId) - 小型二进制空间内容 - 文本、JSON、protobuf、msgpack 等自定义格式 -当前 SDK / 接口核心是： +当前接口核心是： - `UploadMySpaceContentAsync(baseVersion, contentType, checksum, byte[])` - `DownloadSpaceContentByPlayerIdAsync(playerId)` @@ -188,16 +188,6 @@ Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId) - `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 暴露两层模型： - 空间主信息： @@ -213,8 +203,7 @@ Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId) - 下载响应头中的 `X-Space-Version` - 下载响应头中的 `X-Space-Checksum` -如果上层业务追求最省事，可以直接用 `UpdateMyAsync(string)` 或 `UpdateMyAsync(object)`； -如果业务自己管理编码、压缩、protobuf、msgpack 等格式，则继续走 `byte[]` 上传下载接口。 +如果上层业务实际保存的是文本或 JSON，建议仍按 `byte[]` 统一收发，再由业务层自己决定如何编码和反序列化。 ## 10. 动态配置建议 diff --git a/服务参考_临时/Brisk 错误码文档（内部实施版）.md b/服务参考_临时/Brisk 错误码文档（内部实施版）.md index e915f76..b06221f 100644 --- a/服务参考_临时/Brisk 错误码文档（内部实施版）.md +++ b/服务参考_临时/Brisk 错误码文档（内部实施版）.md @@ -1,7 +1,7 @@ # Brisk 错误码文档（内部实施版） -**版本**：v0.1 -**日期**：2026-04-08 +**版本**：v0.2 +**日期**：2026-04-11 **说明**：当前工程内已使用的错误码分组与含义。 --- @@ -45,6 +45,13 @@ ## 3. 当前已使用错误码 +补充说明： + +- `GET /api/client/time` 为平台匿名授时接口 +- 该接口当前没有新增专属业务错误码 +- 触发限流时仍使用通用限流错误码 `80001` +- 限流组件不可用时仍使用通用错误码 `80002` + | 错误码 | 接口/模块 | 含义 | |---|---|---| | `10001` | 客户端鉴权 | 缺少 token | diff --git a/服务参考_临时/README.md b/服务参考_临时/README.md index 4147d61..92e125a 100644 --- a/服务参考_临时/README.md +++ b/服务参考_临时/README.md @@ -4,6 +4,7 @@ Brisk 游戏服务端工程。 当前已实现模块： +- 平台授时 `time` - 客户端初始化 `bootstrap` - 登录换票 `auth` - 玩家信息 `player` @@ -20,6 +21,7 @@ Brisk 游戏服务端工程。 - 项目唯一标识只有 `game_key` - 项目级 `channel / platform` 已移除 - 初始化和动态配置只依赖 `game_key`，配置筛选只看 `client_version` +- 平台授时接口不依赖 `game_key`，可直接匿名获取 UTC 服务器时间 - 登录模块单独处理第三方身份： - `login_provider`：如 `tap` - `login_user_id`：该登录平台返回的稳定唯一用户 ID @@ -43,6 +45,7 @@ docker compose up --build - `GET /health` - `GET /api/ping` +- `GET /api/client/time` - `GET /openapi.yaml` 开发环境默认账号： @@ -54,6 +57,10 @@ docker compose up --build ## 接入说明 +- 平台授时： + - 匿名接口 `GET /api/client/time` + - 无需传 `game_key` + - 返回 `server_time`、`server_unix`、`server_unix_ms` - 客户端初始化： - 必填 `game_key` - 可选 `client_version` diff --git a/服务参考_临时/openapi.yaml b/服务参考_临时/openapi.yaml index a7be799..34b084d 100644 --- a/服务参考_临时/openapi.yaml +++ b/服务参考_临时/openapi.yaml @@ -1,11 +1,12 @@ openapi: 3.0.3 info: title: Brisk Game Service API - version: 0.1.0 + version: 0.2.0 description: Current implemented Brisk server API for internal integration. servers: - url: /api tags: + - name: time - name: bootstrap - name: auth - name: player @@ -51,6 +52,21 @@ components: type: string data: nullable: true + ClientTimePayload: + type: object + properties: + server_time: + type: string + format: date-time + example: 2026-04-11T08:12:30Z + server_unix: + type: integer + format: int64 + example: 1775895150 + server_unix_ms: + type: integer + format: int64 + example: 1775895150123 ExchangeRequest: type: object required: [game_key, login_provider] @@ -494,6 +510,28 @@ components: type: string format: date-time paths: + /client/time: + get: + tags: [time] + summary: Get platform server time + responses: + '200': + description: Current platform UTC time + content: + application/json: + schema: + type: object + properties: + code: + type: integer + example: 0 + message: + type: string + example: ok + data: + $ref: '#/components/schemas/ClientTimePayload' + '429': { description: Rate limited } + '500': { description: Rate limit unavailable } /client/bootstrap: get: tags: [bootstrap]