水鱼查分器

这一页写给已经接过水鱼查分器 API 的开发者：你熟悉的那套模型（Bearer 令牌、裸 JSON、/player/records、 update_records 裸数组）在 RankHub 里各对应什么，哪些必须改。字段的完整定义不在这里重复， 需要时跳 maimai 格式 / chunithm 格式。

你会的东西 vs RankHub复制标题链接

迁移只要四步复制标题链接

1. 换成 RankHub 的 OAuth 凭据（Authorization: Bearer，scope game:read / game:write）； OAuth 流程见授权码模式，JWT/device 流程见令牌。

2. 建档：POST /v1/games/{game}/profiles，给身份字段（maimai 好友码、chunithm 好友码）。 这一步替代水鱼的「QQ 绑定」。

3. 推成绩：POST /v1/games/{game}/profiles/{profileId}/scores，两种写法二选一：

   Copy Text

   { "scores": [ { "songId": "834", "type": "dx", "levelIndex": 3,
                   "achievements": 99.8144, "dxScore": 2500, "fc": "ap", "fs": "fs" } ] }

   如果你手里是机台/原生对象，也可以直接给 native（maimai 机台键： musicId / level / achievement / deluxscoreMax / comboStatus / syncStatus）， 服务端换算；见 maimai 原生数据。

4. 读回：/scores 或 /bests，分页用 cursor，按 sortBy=playTime|achievements|rating 排序。

必须改的五个点复制标题链接

1. 包络：不要再判断 status === 'error'；看 HTTP 状态 + code（common.invalidArgument 等）。
2. 「谁的数据」不再靠参数：RankHub 用 profileId 指定档案；没有 qq / username 参数。
3. 上传体是对象不是数组：{"scores":[…]}；单批默认上限 500（硬上限 2000）。
4. 字段名与枚举：水鱼 maimai 的 type 是 SD / DX，RankHub 是 standard / dx / utage； level_index → levelIndex；dxScore 同名；ra 不要传（maimai 服务端算）。 ❗ song_id 不能直接透传：水鱼的 DX 谱 song_id 是标准 id + 10000（例如 DX 的 song_id=1834 对应曲目 834）。RankHub 的 songId 是无偏移的曲目 id（标准 / DX 共用，靠 type 区分）， 迁移时要把 DX 的 song_id 减 10000，standard 保持不变。
5. achievements 是百分比（99.8144），不是 ×10000 的整数 —— 不要套机台编码； 机台编码请走 native（achievement: 998144）。

坑（来自水鱼文档的已知语义）复制标题链接

• 水鱼上传按 title 认曲、同名曲有特例（Link(CoF)）；RankHub 只认 songId，请你先做标题→id 的映射。
• DX 的 song_id 带 +10000 偏移：这是水鱼与落雪最容易被忽略的差异（落雪 id 无偏移）。直接透传会 写到不存在的谱面；映射公式：RankHub.songId = (type === 'DX') ? song_id - 10000 : song_id。
• 水鱼的 level_index 越界会静默跳过；RankHub 会报 400（不静默丢数据）。
• achievements 超过 101 水鱼会截断；RankHub 的普通谱上限 101、BUDDY/宴谱到 202，超界直接 400。
• 水鱼 Bearer 配额按自然日；RankHub 的限流见批量与限流。

下一步复制标题链接

• maimai 格式 / chunithm 格式（统一字段、原生字段、写入必填）
• 写入格式（两种写法、幂等、428 确认流）
• 怎么传数据（速查）