# 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 时间，适合客户端启动时做统一对时

示例：

```bash
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`：可选

示例：

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

说明：

- 空间主信息接口只返回元数据，不再内嵌内容本体
- 空间内容本体通过独立 `/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`：必传，内容本体

上传空间内容示例：

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

下载空间内容示例：

```bash
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
```

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

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

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

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

点赞返回示例：

```json
{
  "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 导出：

- [openapi.yaml](/F:/OtherWork/BriskGameSerivce/openapi.yaml)