foldcc/CC-Framework.BriskGameServer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9c57faa16cb1c7b7de0d6415a3375f8f57eea520
CC-Framework.BriskGameServer/服务参考_临时/Brisk API接口与示例文档.md

10 KiB
Raw Blame History

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/time
  2. GET /api/client/bootstrap
  3. POST /api/auth/login/exchange
  4. 带 Bearer access_token 调用：
    • GET /api/player/me
    • GET /api/announcements
    • 排行榜、存档、空间等业务接口
  5. GET /api/config/current 为公开接口，登录前后都可调用

3. 初始化

3.1 获取平台时间

GET /api/client/time

说明：

  • 平台级匿名授时接口
  • 不需要 game_key
  • 不依赖任何项目配置
  • 返回 UTC 时间，适合客户端启动时做统一对时

示例：

curl "https://brisk.lightyears.ltd/api/client/time"

返回重点：

  • server_time
  • server_unix
  • server_unix_ms

3.2 获取初始化信息

GET /api/client/bootstrap

查询参数：

  • game_key：必填
  • client_version：可选，建议传入；不传时只会命中不设版本范围的配置
  • device_id：可选

示例：

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：可选对象

示例：

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

示例：

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}

提交分数示例：

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

上传示例：

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. 玩家空间

说明：

  • 空间主信息接口只返回元数据，不再内嵌内容本体
  • 空间内容本体通过独立 /content 接口上传和下载
  • 空间内容支持任意 bytes
  • 可以上传二进制、文本、JSON、protobuf、msgpack、压缩包等格式
  • 如果是多槽位私有主存档，仍优先走云存档模块；如果是空间自定义内容，可直接走空间内容接口

接口：

  • PUT /api/spaces/me/content
  • GET /api/spaces/{player_id}
  • GET /api/spaces/{player_id}/content
  • 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/content
  • GET /api/spaces/by-login/stats
  • GET /api/spaces/by-login/likes
  • POST /api/spaces/by-login/like
  • DELETE /api/spaces/by-login/like

主信息接口返回重点：

  • content_exists
  • content_version
  • content_type
  • content_size_bytes
  • content_checksum
  • like_count
  • today_like_count
  • liked_by_me
  • like_reset_at
  • visit_count
  • updated_at

点赞接口说明：

  • 点赞按 Asia/Shanghai 自然日分周期
  • 同一玩家对同一空间同一天重复点赞时：
    • 接口仍返回成功
    • created=false
    • like_count 与 today_like_count 不会继续增加
  • DELETE /like 只会撤销当前周期内的那一次点赞
  • 支持给自己的空间点赞

点赞列表说明：

  • GET /api/spaces/{player_id}/likes
  • GET /api/spaces/by-login/likes
  • 支持可选查询参数 scope
    • history：历史点赞记录，默认值
    • cycle：当前周期内的点赞记录
  • limit 最大返回 100

最近访问列表说明：

  • GET /api/spaces/me/visits
  • 支持可选查询参数 limit
  • 默认返回 50 条
  • 单次最大返回 100 条

上传表单字段：

  • base_version：用于乐观锁；首次上传可传 0
  • content_type：可选，建议传，例如 application/octet-stream、text/plain、application/json
  • checksum：可选；如果传入，服务端会校验 SHA-256
  • file：必传，内容本体

上传空间内容示例：

curl -X PUT "https://brisk.lightyears.ltd/api/spaces/me/content" \
  -H "Authorization: Bearer <token>" \
  -F "base_version=0" \
  -F "content_type=application/octet-stream" \
  -F "checksum=<sha256>" \
  -F "file=@space-content.bin"

下载空间内容示例：

curl "https://brisk.lightyears.ltd/api/spaces/by-login/content?login_provider=tap&login_user_id=tap_user_10001" \
  -H "Authorization: Bearer <token>" \
  --output space-content.bin

按第三方身份查看空间示例：

curl "https://brisk.lightyears.ltd/api/spaces/by-login?login_provider=tap&login_user_id=tap_user_10001" \
  -H "Authorization: Bearer <token>"

按第三方身份点赞示例：

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>"

按第三方身份查询当前周期点赞列表示例：

curl "https://brisk.lightyears.ltd/api/spaces/by-login/likes?login_provider=tap&login_user_id=tap_user_10001&scope=cycle&limit=20" \
  -H "Authorization: Bearer <token>"

点赞返回示例：

{
  "liked": true,
  "created": true,
  "liked_by_me": true,
  "like_count": 128,
  "today_like_count": 17,
  "like_reset_at": "2026-04-22T00:00:00+08:00"
}

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

10.5 空间管理

  • GET /api/admin/spaces/overview?project_id=...
  • GET /api/admin/spaces?project_id=...
  • GET /api/admin/spaces/{player_id}?project_id=...
  • GET /api/admin/spaces/{player_id}/content?project_id=...
  • GET /api/admin/spaces/{player_id}/likes?project_id=...
  • GET /api/admin/spaces/{player_id}/visits?project_id=...

说明：

  • 后台空间详情返回内容元数据
  • 如果需要查看空间内容本体，使用独立 /content 下载接口
  • 下载响应会返回：
    • Content-Type
    • X-Space-Version
    • X-Space-Checksum

11. OpenAPI

完整 OpenAPI 导出：

Reference in New Issue View Git Blame Copy Permalink