基址：http://localhost:3000，子路径部署示例：https://your-host/rizline。
| 项目 | 规则 |
|---|---|
| 鉴权 | /api/* 携带 api-key；/web/* 供网页匿名调用 |
| 请求格式 | POST 使用 JSON；图片接口同时接受 GET 查询参数 |
| 限流 | API 按 Key 和接口分别计数；网页按接口全局计数 |
| API 登录开关 | rizline.allowApiLogin=true 时开放 /api/login/* |
| 凭证 | rizToken；亦接受参数别名 token 和裸 JWT |
| 样例凭证 | test、demo、sample |
rizToken 为 base64url(JSON.stringify({t,d,c}))，分别包含 JWT、device ID、channel ID。推荐通过 POST 请求体传递。
以下接口均提供 /api 与 /web 两种前缀。
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /api/session |
查询成绩报告 |
| GET / POST | /api/image |
生成成绩图 |
| POST | /api/login/check |
创建登录会话并判断登录方式 |
| POST | /api/login/code |
发送短信验证码 |
| POST | /api/login/submit |
提交密码或验证码 |
POST /api/session
| 参数 | 类型 | 必填 | 含义 |
|---|---|---|---|
rizToken |
string | 是 | 登录凭证 |
成功返回 200，JSON 字段如下：
| 字段 | 内容 |
|---|---|
user |
userId、nickname、称号和 rizcard 名片数据 |
summary |
totalRks、computedRks、displayRks、计分数量、空槽及完成度统计 |
best |
fc5、b35 两组成绩 |
slots |
按 FC5、B35 排列的 40 个槽位；空槽含 empty: true、group、rank |
difficultyColors |
各难度的显示颜色 |
comparison |
历史对比状态、变化数量及总 RKS 差值 |
generatedAt |
报告生成时间 |
| 成绩项字段 | 含义 |
|---|---|
id / name / artist / disc |
曲目 ID、名称、曲师、系列 |
level / constant / designer |
难度类别、定数、谱师 |
score / completeRate / fc / clear |
分数、完成率百分比、全连、通关状态 |
rks |
云存档提供的精确单谱 RKS |
rksCeiling / rksRoom |
单谱理论上限与提升空间 |
illustrationUrl / difficultyColor |
曲绘路径与难度颜色 |
change |
新增或提升时提供变化详情 |
change 包含 isNew、isImproved、promoted、scoreDelta、completeRateDelta、rksDelta 和 rksContribution。历史对比以同一玩家的上一版存档为基准。
summary.totalMismatch 有值时表示存档总 RKS 与汇总结果存在差异；comparison.unavailable=true 表示历史对比暂时不可用。资源路径相对于服务根目录。
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,...，slotCount 为 40。
POST /api/login/check
| 参数 | 类型 | 必填 | 含义 |
|---|---|---|---|
phone |
string | 是 | 6–15 位数字手机号 |
返回 { "loginId": "...", "mode": "code", "needsCode": true }。
mode 为 password 或 code。loginId 有效期 10 分钟，后续请求携带同一 ID 和手机号。
POST /api/login/code，参数为 loginId、phone，均为必填字符串。
成功返回 { "sent": true, "cooldownSeconds": 60 }。
| 短信限制 | 默认值 |
|---|---|
| 同号冷却 | 60 秒，配置下限 30 秒 |
| 同号次数 | 每 24 小时 5 次 |
| 同 IP 次数 | 每小时 10 次 |
短信额度与接口 RPM 同时生效，计数在进程内存中维护。
POST /api/login/submit
| 参数 | 类型 | 必填 | 含义 |
|---|---|---|---|
loginId |
string | 是 | 登录会话 ID |
phone |
string | 是 | 手机号 |
code |
string | 二选一 | 短信验证码 |
password |
string | 二选一 | 账号密码 |
成功返回 { "ok": true, "rizToken": "...", "userId": "...", "expiresAt": "..." }，随后该会话结束。
业务失败返回 200，内容为 { "ok": false, "needsCode": false, "message": "..." }；needsCode=true 时改用验证码。有效期内可继续使用原会话重试。
错误响应为 { "error": "错误说明" }。
| HTTP 状态 | 含义 |
|---|---|
| 400 | 参数、凭证格式或登录会话错误 |
| 401 | API Key 校验失败 |
| 403 | 凭证过期或 API 登录开关关闭 |
| 409 | 同一登录会话已有请求正在处理 |
| 413 | 请求体超过配置上限 |
| 429 | 接口或短信限流 |
| 500 | 服务或上游处理失败 |
| 503 | 服务尚未配置 API Key |
429 携带 Retry-After；接口 RPM 限流另带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset，时间值以秒计。登录及成绩响应使用 Cache-Control: no-store。