概念：档案、成绩与最佳成绩桶

本页讲概念，不讲每个端点的字段细则（那些在游戏档案与成绩读取与写入）。

先记住一句话：平台只归一"形状"和"翻页/排序协议"，不归一"数值语义"。 rating 在每个游戏里都叫 rating，但它是各游戏自己的分 —— 不能跨游戏比大小，也不能相加。

三层，各回答一个问题

三层都套在 v1 envelope 里（{ code, message, description, data, requestId }），时间 RFC3339、字段 camelCase。

档案（profile）

一条档案 = 一个 RankHub 用户在一个游戏上的一张档案。它的 id 是 profileId（uuid）， 这是 RankHub 的标识，游戏平台不认识它。

游戏原生标识放在 player.source 里，两套东西没有换算关系：

一个用户在同一游戏上可能有多张档案（换过账号、或用不同标识各建过一张），所以列表接口才是列表。

字段

{
  "profileId": "8d1f4a0e-6c2b-4a1e-9d3f-2b7c5e9a0f11",
  "game": "maimai",
  "player": { "name": "Player", "rating": 15234, "source": { "userId": 12345678 } },
  "isPublic": true,
  "origin": "app",
  "createdByClientId": "cli_7Q2…",
  "syncCapable": false,
  "lastSyncedAt": null,
  "createdAt": "2026-10-21T18:40:00Z",
  "updatedAt": "2026-10-21T18:40:00Z"
}

syncCapable 与 origin 是两件事

syncCapable 的判据是用户是否在 RankHub 里完成了这个游戏的账号/凭据绑定 —— 不是"这张档案是谁建的"：

• 你的应用建的档案只落库、不带凭据 ⇒ 建号时 syncCapable: false（用户还没绑定）；
• 之后这条档案只能靠你的应用推成绩来更新（推成绩）， 平台不会替你去游戏平台抓数据；
• 用户之后在 RankHub App 里完成绑定 ⇒ 才变成 syncCapable: true，那时由 RankHub 同步；
• 有的游戏没有"可长期持有的凭据"（导入是一次性动作），这类档案的 syncCapable 恒为 false —— 那只是"没有自动同步这条路"，不代表档案不能更新。

所以：origin: "app" 不蕴含 syncCapable: false；也不要拿 syncCapable 当"能不能写"的判据 —— syncCapable: false 的档案恰好就是"只能靠推成绩更新"的那一类。

「未解绑」与「删除申请」是两件事

读接口对"不存在 / 不是你的 / 已解绑"统一返回 404 common.notFound，刻意不区分 —— 不要用 404 反推档案是被删了还是解绑了。

成绩（score）

一条成绩 = 一张谱面 + 一次（或最佳一次）游玩结果。平台把跨游戏共有的部分提成顶层字段， 游戏特异的部分一律留在 source：

几个对照（避免"按字段名猜")：

最佳成绩桶（bucket）

旧接口按游戏分成 best50 / best30 / b40 / best100 / best……现在一个端点、一个形状：

{
  "game": "maimai",
  "computedAt": "2026-10-24T02:10:00Z",
  "totals": { "total": 15234, "latest": 7234, "archive": 8000 },
  "buckets": [
    { "key": "latest",  "label": "当期", "total": 7234, "items": [ /* 与 scores 的 items 同形状 */ ] },
    { "key": "archive", "label": "往期", "total": 8000, "items": [ /* … */ ] }
  ]
}

各游戏的桶（由服务端切，客户端不要重算）

跨游戏归一化的边界

这一节是"别误用"的清单。

rating 同名，但语义各游戏独立

可以做：同一游戏内的排序与比较、同一游戏内的桶求和。 不要做：跨游戏的 rating 排行榜、跨游戏求和/平均、把不同游戏的 rating 放进同一个量纲。

想表达"玩家水平"跨游戏时，请用游戏内的相对位置（如段位、百分位）并明确标注是哪个游戏。

排序只在服务端

scores 的 sortBy 只有 playTime | achievements | rating 三键（order 为 asc/desc）。

• 三项是"跨游戏同名"的最小交集，不是所有游戏都完整支持；值为 null 的条目不参与比较、排在最后；
• 不传 sortBy ⇒ 用各游戏的原生默认顺序（不要假设它是 rating 降序）；
• 排序只作用于单张档案的成绩列表 —— 跨游戏混排没有服务端实现，也不要在客户端拼。

difficulty 只是字符串

difficulty 是各游戏原生难度标识的透传（maimai 的 3、arcaea 的 2、phigros 的 IN…）， 平台不校验枚举：合法取值集合因游戏而异；传一个该游戏不存在的值通常是空列表，而不是 400。 （个别游戏原生不支持难度过滤，该参数会被忽略。）

分页是不透明游标

• 响应 { items, nextCursor, hasMore }；首页不传 cursor，之后把 nextCursor 原样传回；
• 游标对客户端不透明：不要解析它、不要自己拼、不要把它当 offset 算"第 N 页"；
• 换 sortBy / order / difficulty 必须从第一页重来（游标属于某一个具体排序结果）；
• 非法游标返回 400 common.invalidArgument（不会静默回退到第一页）。

limit

limit 默认 50、上限 100。超过上限是 400，不是自动截断。

没有"跨游戏总榜"

因为没有跨游戏可比的标尺：rating 量纲不同、achievements 口径不同（百分比 / 01 / 0100）、 难度集合不同、曲库完全不同。任何跨游戏排名都必须先由你定义换算规则，并在 UI 上说明。

写入：两个形状，问的是不同问题

建号需要的是"身份字段"，不是凭据（同一个请求体是"超集"，字段按游戏生效；name 必填）：

缺身份字段 ⇒ 400。具体字段名与错误文案以各游戏小节 / 错误信息为准 —— 不要凭本文猜必填项， 先看 GET /v1/games 的 pushProfile。

maimai / arcaea 沿用各自的既有建号语义，字段比其余游戏多：maimai 要 userId 或 friendCode， arcaea 还需要 character（搭档）非空。这两族以错误信息为准。

建档与更新是两条独立的路

这是本页最容易被读错的一条："能建号"和"能同步"是两件互不相关的事。

你建档（POST /profiles）
  ├─ 只落库：身份字段 + name（+ 同请求里可带的 scores）
  ├─ 不拉上游、不存凭据  ⇒ syncCapable = false
  └─ 之后这条档案靠
       ① 你推成绩（POST .../{profileId}/scores）   ← 10 个游戏都能用
       ② 用户在 RankHub App 里绑定账号             ← 绑定后才由 RankHub 同步

评分的两个来源

同一批字段名（scores[].rating），在两类游戏里含义完全不同：

三条纪律：

1. 别指望平台帮你把评分算对：那 8 个游戏里评分是你给的事实输入，平台只挡畸形值；
2. 本地游戏（chunithm / orzmic）用 scores[].raw 带上原始成绩对象，并用 scores[].bucket 指定落到哪个桶（缺省 best30；chunithm 还可 selection10 / new20，写错桶名 ⇒ 400）；
3. 本地游戏不改"玩家头部"：player / summary 属于"绑定后同步一次"的数据，第三方推成绩只补成绩与桶。

写入语义

删除：你只能申请

同一张档案、同一个应用已有待处理申请时，再次申请返回同一条（requestId 不变）， 但会轮换确认链接里的令牌（旧链接失效）—— 幂等的是申请，不是令牌。

能力矩阵：以服务端为准

不要把你需要的游戏写死。第一步永远是拉能力矩阵：

curl -sS https://api.rankhub.cc/v1/games -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "code": "common.ok",
  "data": { "games": [
    { "game": "maimai",  "read": true, "pushProfile": true, "pushScores": true, "deletionRequest": true },
    { "game": "phigros", "read": true, "pushProfile": true, "pushScores": true, "deletionRequest": true }
  ] }
}

三条纪律：

1. 别抄成本地常量：能力会变，路径与形状不变；按 false 优雅降级（把入口藏起来）；
2. 每列背后做的事不同：pushProfile 是"填字段建档"（身份字段见上），pushScores 是"推成绩" （评分值口径见上）；建号 ≠ 同步，建档后 syncCapable 仍是 false；
3. 能力是"按游戏"的，不是"按档案"的：pushScores: true 仍可能 404（不是你的档案）或 403（停写）。

下一步

• 游戏档案：读取、来源标记、建号、删除申请
• 成绩读取与写入：成绩列表、最佳成绩、批量写入与确认重试
• 错误与排障：game.* 业务码逐条解释