API 目前处于 Early Preview 阶段， 可能存在诸多不完善与错误之处，欢迎加群交流反馈：加入官方交流群（1073434398）
phi-plugin
从 phi-plugin（Phigros bot 插件）的数据模型迁到 RankHub v1：存档结构、单曲 rks、best27+φ3、难度枚举与推成绩字段。
这一页写给做过 phi-plugin 开发/二次开发的开发者： 你熟悉的那套 Phigros 数据（
Save/gameRecord/ 单曲rks/(φ3+best27)/30）怎么接到 RankHub v1。 字段细节见 phigros 格式，这里只讲「怎么搬」。
你会的东西 vs RankHub
phi-plugin（model/save/Save.js、model/game/*） | RankHub v1 |
|---|---|
玩家身份：云存档里的 userInfo.objectId + nickname | 建档 POST /v1/games/phigros/profiles，身份字段 objectId，展示名 name |
gameRecord[songId][0..4]：下标即难度（EZ/HD/IN/AT/LEGACY） | 成绩唯一键 songId(字符串) + difficulty（EZ/HD/IN/AT/Legacy） |
单条 score / acc / fc / rank / Rating / difficulty(定数) / rks | score / accuracy / fullCombo / rank / constant / rating（单曲） |
单曲 rks 自己算：acc==100 → 定数；acc<70 → 0；否则 定数×((acc−55)/45)² | 你可以自己算后放 rating；RankHub 不代算 phigros 的单曲分 |
总 rks = (φ3 + best27) / 30，LEGACY 不进桶 | GET .../bests 的 totals 是同一口径（φ3 + best27、LEGACY 排除） |
凭证：TapTap sessionToken（LeanCloud） | 凭证是 OAuth access token；sessionToken 不能当身份 |
bot 事件 (e, …)、Redis 绑定、渲染/发图 | 无 bot 层；纯 HTTP API |
建档：只需要两个值
{ "player": { "objectId": "12345678", "name": "Player" } }objectId就是 phi-pluginuserInfo.objectId（存档里的玩家 id，不是sessionToken）；name用nickname；- 可选
shortId；已有档案时重复建档会409，改展示名走PATCH /v1/games/phigros/profiles/{profileId}。
推成绩：字段一一对应
{
"scores": [
{
"songId": "996",
"difficulty": "IN",
"score": 998000,
"accuracy": 99.65,
"fullCombo": true,
"constant": 15.6,
"rating": 15.48,
"rank": "V"
}
]
}| phi-plugin 字段 | RankHub 字段 | 说明 |
|---|---|---|
id（songId） | songId | 必须字符串 |
rank（难度 EZ/HD/IN/AT/LEGACY） | difficulty | 枚举大小写：Legacy 不是 LEGACY |
score（0~1,000,000） | score | 比较值；只升不降 |
acc（0~100 百分数） | accuracy + achievements | 两个字段同值，避免消费者拿不到 |
fc（bool） | fullCombo（true 时同时 fc: "fc"） | |
difficulty（定数） | constant | 曲库定数；不传也能落库，但算不了分 |
rks（phi-plugin 自己算的） | rating | phigros 的 rating 由调用方给 |
Rating（ϕ/V/S/A/B/C/F） | rank | 注意 ϕ 是 U+03D5，不是 phi |
| — | playTime / artist | 可选 |
也可以直接给
native（phigros 原生键：song_id/difficulty/score/acc/constant/rks/fc/rating/artist），服务端换算，见 phigros 原生数据。
三个必须注意的差异
- 评级多两档：phi-plugin 的
Rating()会返回FC（低分但全连）和NEW（0 分），RankHub 没有这两档； 落库前请把FC归到V/F中合适的档，NEW视为 0 分不进榜。 ϕ的写法：RankHub 是ϕ（U+03D5）；phi-plugin 源码里用的是 ASCII'phi'，别原样透传。- LEGACY 不进总 rks：phi-plugin 的
Level = ['EZ','HD','IN','AT']与 RankHub 一致； 传Legacy成绩可以，但不参与最佳桶合计。
那些「搬不过来」的东西
- TapTap 云存档协议（LeanCloud
X-LC-Id/X-LC-Session、AES 解密）：RankHub 不接存档抓取， 它只收你已经解析好的成绩； - bot 层（
(e, …)事件、Redis 绑定、渲染发图、指令权限）：v1 是 HTTP API，没有这些概念； sessionToken是凭据不是身份，不要塞进objectId。
下一步
- phigros 格式（统一字段 / 原生字段 / 最佳桶 / 写入必填）
- 怎么传数据（速查）
- 写入格式（幂等、单批上限、428 确认流）
