写入格式（建档 / 推成绩）

本页是写入侧的统一契约。读侧（返回什么）见游戏数据格式总览； 每个游戏的具体字段表与可直接抄的 JSON见各游戏格式页的「写入（第三方）」一节。

两个写入端点：

两者都是 application/json、Bearer 鉴权、v1 envelope；写操作需要 game:write（覆盖 game:read）。

不确定该传 RankHub 字段还是游戏原生数据？先看怎么传数据（速查）。

1. 建档请求体复制标题链接

{
  "player": { "name": "Player", "friendCode": "1234567890123" },
  "idempotencyKey": "b4c0f0d6-8f6f-4d6a-a0d3-3c6f0c4a11"
}

1.1 player 是超集：字段按游戏生效复制标题链接

身份字段（10 个游戏）：

建档只写 player（身份字段）与可选 scores；建档后的档案 syncCapable: false， 之后靠你推成绩更新。

2. 推成绩请求体复制标题链接

{
  "scores": [
    {
      "songId": "1234",
      "difficulty": "IN",
      "score": 1000000,
      "accuracy": 100,
      "rating": 15.2,
      "playTime": "2026-10-20T12:00:00Z"
    }
  ],
  "idempotencyKey": "0b6f0f1e-2f3a-4c5d-8e9f-1a2b3c4d5e6f",
  "confirmationToken": "（仅 428 重放时带）"
}

2.1 scores[] 共享字段复制标题链接

字段是超集：按游戏生效，不适用的字段被忽略。每个游戏"哪几个必须给"见各游戏页的速查表。

缺省值说明：计数类字段"缺省 0"是有意的诚实默认（未知就是 0），不是服务端帮你补全。 需要准确分数时请把真实值给全。

2.2 原生数据（native）复制标题链接

手里已经是游戏原生对象时，整块放进 native 即可（建档 player.native、成绩 scores[].native）， 服务端按该游戏唯一一套换算规则归一；native 优先于顶层同名字段，不合法 ⇒ 400 common.invalidArgument。

• 哪些游戏支持 native 建档 / native 成绩、每个游戏必给什么：见怎么传数据（速查）；
• 每游戏的 native 字段表：见对应游戏格式页；
• 机器可读版本：GET /v1/games/{game}/format 的 profile.nativeFields / score.nativeFields。

3. 响应复制标题链接

3.1 建档 → 一张档案复制标题链接

data 与 GET /v1/games/{game}/profiles/{profileId} 完全相同（见总览 §2）。 第三方建的档案会带 origin: "app"、createdByClientId、syncCapable: false。

3.2 推成绩 → 写入结果复制标题链接

{
  "code": "common.ok",
  "data": {
    "rating": { "before": { "total": 15100 }, "after": { "total": 15234 }, "delta": 134 },
    "applied": [ { "songId": "1234", "improved": true, "currentAchievements": 100.5125 } ],
    "ignored": [ { "songId": "5678", "reason": "notImproved" } ]
  }
}

rating.before / after 的键集合随游戏：maimai 是 total/latest/archive， arcaea 是 potential/b30Avg/b50Avg（没有 total，delta 是 potential 差）， 其余多为 total。applied[].currentAchievements 对 arcaea 装的是分数 score、 本地游戏（chunithm/orzmic）恒为 null；ignored[].reason 本地游戏是 not-improved（带连字符）。

一条成绩可能同时出现在 applied（improved: false）与 ignored 里，便于两条流都渲染。

4. 常见 400 文案复制标题链接

5. 批量与限流复制标题链接

• scores 不能为空（ArrayNotEmpty）；单批上限按应用档位配置，默认 500，DTO 硬上限 2000；
• 超限 → 400 common.invalidArgument，不会部分写入；
• 批量写入限流按 tier（见业务 API 总览）。

6. 428 确认与 403 停写复制标题链接

写入守卫会对可疑写入返回 428 game.writeConfirmationRequired（需要用户确认后原样重放）或 403 game.writeSuspended（应用写权限被暂停）。两种语义、payload 与重放规则见 成绩读取与写入 · 428 / 403。

7. 幂等复制标题链接

8. 相关复制标题链接

• 游戏数据格式总览：读侧统一字段与 10 游戏索引
• 游戏档案：档案读取、来源标记、删除申请
• 成绩读取与写入：成绩读取、排序、最佳成绩
• 错误码