API.md

Phigros API

约定

基址：http://localhost:3000，子路径部署示例：https://your-host/phigros。

项目	规则
鉴权	/api/* 携带 api-key 请求头
请求格式	POST 使用 JSON；GET 使用查询参数
网页入口	/web/session、/web/qr/start、/web/qr/{requestId}/status 供网页匿名调用
限流	API 按 Key 和接口分别计数；网页按接口全局计数
凭证	sessionToken；样例值为 session:test

推荐使用 POST 请求体传递凭证。

接口目录

方法	路径	用途
POST	/api/session	查询成绩报告
GET / POST	/api/image	生成成绩图
POST	/api/qr/start	创建 TapTap 登录二维码
GET	/api/qr/{requestId}/status	查询扫码状态

成绩报告

POST /api/session

参数	类型	必填	默认值	含义
sessionToken	string	是	—	云存档凭证
bCount	number	否	39	B 排名数量，范围 27–327；溢出数量为 bCount - 27

成功返回 200，JSON 字段如下：

字段	内容
user	nickname、objectId
summary	存档 RKS、computedRks、displayRks、bCount、存档时间与完成度
best	phi、b27、overflow 三组成绩
slots	按展示顺序排列的成绩项
comparison	历史对比状态、上一版时间及变化数量
generatedAt	报告生成时间

成绩项字段	含义
id / name / artist	曲目 ID、名称、曲师
level / constant	难度类别、定数
score / acc / fc	分数、准确率百分比、全连状态
rks	单谱 RKS
coverUrl / illustrationUrl	预览曲绘与原图路径
change	有变化时提供新增、提升、名次及数值差异

历史对比以同一玩家的上一版存档为基准。资源路径相对于服务根目录，子路径部署时加上对应前缀。

成绩图

GET /api/image 或 POST /api/image。接受成绩报告的全部参数，并增加：

参数	类型	默认值	含义
scale	number	2	分辨率倍率，支持 2、6
base64	boolean	false	返回 Data URL JSON

默认响应为 PNG 二进制，响应头包含 X-Image-Scale、X-Image-Width、X-Image-Height。

base64=true 的响应字段为 mime、width、height、scale、slotCount、image。其中 image 为 data:image/png;base64,...。

图片尺寸随 scale 和 bCount 变化，超出像素上限时返回 400。

扫码登录

创建二维码

POST /api/qr/start，请求体 {}。

响应字段	含义
requestId	登录请求 ID
qrImage	二维码 PNG Data URL
qrcodeUrl	TapTap 登录链接
interval	建议轮询间隔，秒
expiresIn	有效期，秒

查询状态

GET /api/qr/{requestId}/status，按 interval 轮询。

state	含义及附加字段
pending	等待扫码或确认
done	登录成功，返回 sessionToken
expired	已过期，返回 message
error	登录失败，返回 message

错误与限流

错误通常返回 { "error": "错误说明" }；扫码状态使用上表结构。

HTTP 状态	含义
400	参数错误或图片尺寸超限
401	API Key 校验失败
404	登录请求或资源未找到
413	请求体超过配置上限
429	请求限流
500 / 502	服务或上游处理失败
503	服务尚未配置 API Key

429 携带 Retry-After 和 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset；时间值以秒计。