AWMCNET Bot API

AWMCNET 是 QueryBot 的成绩镜像与查询服务。本文面向需要把成绩同步到 AWMCNET 的 Bot、查分器和服务端开发者。

服务地址

基准地址：https://net.wmc.pub

接口使用 Bot-Token 鉴权。该令牌只应放在服务端，不能下发到用户端或写入公开日志。

POST /api/bot/sync

同步玩家资料和成绩。首次同步会按 QQ 创建不公开的临时玩家，之后可通过对应的 QQ号@qq.com 认领到论坛账号。

请求头

Bot-Token: <shared-secret>
Content-Type: application/json

请求字段

字段	类型	说明
qq	integer	必填，QQ 号，范围 10000～999999999999
nickname	string	可选，玩家昵称
source	string	可选，数据来源，如 sega、divingfish
rating	integer	可选，当前 Rating
old_rating / new_rating	integer	可选，旧版本 / 新版本 Rating
play_count	integer	可选，游玩次数
records	array	成绩数组，单次最多 10000 条
full_snapshot	boolean	全量快照时设为 true；增量同步保持默认 false
snapshot_id	string	分块快照的标识，最多 64 个字符
snapshot_final	boolean	分块快照的最后一块设为 true

分块提交全量快照

一次性成绩过多可能导致请求超时。此时把同一个全量快照拆成多个请求：

1. 每一块都设置 full_snapshot: true，并复用同一个 snapshot_id。
2. 中间块省略 snapshot_final 或设置为 false，服务端返回 status: "partial"。
3. 最后一块设置 snapshot_final: true，服务端返回 status: "ok"，并清理本次快照中不存在的旧成绩。
4. 请求超时后，用相同的 snapshot_id 重试同一块；重复提交是幂等的。
5. 未完成的快照不能混用另一个 snapshot_id，否则返回 HTTP 409。

分块到达后，成绩会立即写入，但旧成绩只在最后一块到达时删除。因此上传未完成期间， 查询结果可能暂时包含上一份快照中的成绩。

中间块示例

curl -X POST 'https://net.wmc.pub/api/bot/sync' \
  -H 'Bot-Token: <shared-secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "qq": 123456789,
    "source": "sega",
    "full_snapshot": true,
    "snapshot_id": "qq-123456789-20260825-01",
    "snapshot_final": false,
    "records": [
      {
        "song_id": 1,
        "title": "Example Song",
        "type": "DX",
        "level_index": 3,
        "achievements": 100.1234,
        "dxScore": 2500,
        "fc": "fc",
        "fs": "fs"
      }
    ]
  }'

最后一块示例

请求体结构与中间块相同，只需继续使用相同的 snapshot_id，并设置：

{
  "full_snapshot": true,
  "snapshot_id": "qq-123456789-20260825-01",
  "snapshot_final": true,
  "records": [
    {"song_id": 2, "level_index": 3, "achievements": 99.8765}
  ]
}

最后一块不能提交空的有效快照；至少需要在本次快照的任意一块中提交一条有效成绩。

响应

{
  "status": "partial",
  "snapshot_id": "qq-123456789-20260825-01",
  "imported": 1,
  "updated": 0,
  "skipped": 0,
  "stored_records": 1,
  "errors": []
}

imported、updated、skipped 和 errors 反映当前请求这一块；stored_records 是 玩家当前已存储的成绩数量。最后一块以及同一 snapshot_id 的重复请求返回 status: "ok"。

GET /api/bot/player/{qq}

读取 AWMCNET 已合并的玩家资料、成绩和 B50/B15。需要同样的 Bot-Token 请求头。

GET /api/bot/player/{qq}/trend

读取玩家 Rating 趋势。可用 days 查询 1～365 天，默认 30 天。

数据来源

AWMCNET 接口只接收统一成绩数据，不接收 SGWCMAID、街机 UID 或第三方查分器 Token。