公开接口总参考
本页按公开 Web 客户端实际使用的接口整理快速参考。它适合查“某个动作应该调用哪个接口”，详细字段和示例仍以各专题页、公开数据模型、公开字段目录和公开 API 工作流示例为准。
统一请求规则
BASE = https://xn--9er778cb3e.xn--igrr70arr3c.vip/zundalink/api/v0- JSON 写入统一使用
Content-Type: application/json； - 除地区聚合外，本文列出的接口通常使用
POST； - Token 放在 JSON 请求体中；
- 不要把 Token、密码、访问码、机台标识或完整响应写入 URL、日志和截图；
- HTTP 状态和业务字段必须同时判断；
- 失败消息中的
msg应保留给用户，但不应原样上传到第三方日志。
通用成功封装通常类似：
{
"success": true,
"msg": "success"
}验证接口可能使用 valid 而不是 success；文件接口成功时可能返回二进制而不是 JSON。
接口索引
| 分组 | 接口 |
|---|---|
| 会话 | /token/get、/token/reg、/token/validate、/token/bind、/token/logout |
| 访问码 | /aimedb/reg、/aimedb/reg-temp、/aimedb/reg-token |
| 配方 | /forward/get、/forward/add、/forward/del |
| 相片 | /photo/get、/photo/get-file、/photo/del-file、/photo/del |
| 缓存 | /cache/backup、/cache/restore |
| 上传缓存 | /upload-cache/get、/upload-cache/upload、/upload-cache/get-file、/upload-cache/del |
| 用户成绩 | /user/music/get、/playlog/get |
| 成绩互动 | /chart/social/get、/chart/reaction、/chart/comment/add、/chart/comment/del、/chart/comment/reaction |
| 内容反馈 | /chart/review/request、/chart/review/withdraw、/chart/review/list、/chart/review/history、/chart/review/decision |
| 机台统计 | /player/queue/get、/usage/get、/region/get |
会话接口
POST /token/get
取得会话 Token。请求可以使用二维码文本，或使用用户名/密码组合：
{ "qrcode": "<QR_TEXT>" }{ "username": "<USERNAME>", "password": "<PASSWORD>" }可选的 customAimeUrl 只在管理员明确要求时填写。成功结果通常包含：
| 字段 | 说明 |
|---|---|
success | 请求是否成功 |
msg | 面向用户的结果说明 |
token | 当前会话凭据 |
isMachine | 账号类型提示 |
登录按钮进入处理中后不要重复点击。二维码失败时优先重新生成，不要把同一张截图连续提交。
POST /token/reg
注册用户会话，需要 username、password 和页面提供的人机验证值 cf_token。这是账号创建动作，客户端应：
- 在本地校验必填字段；
- 不保存明文密码到日志；
- 注册成功后只在受保护状态中保存返回 Token；
- 失败后展示
msg，不要自动重复注册。
POST /token/validate
验证已有 Token：
{ "token": "<TOKEN>" }结果使用 valid，可能附带 expires_at、expired 或新的 Token。valid: false 时停止后台刷新和写入操作，要求用户重新登录。
POST /token/bind
为当前 Token 绑定或更新用户名密码：
{
"token": "<TOKEN>",
"username": "<USERNAME>",
"old_password": "<OLD_PASSWORD>",
"new_password": "<NEW_PASSWORD>"
}首次绑定时旧密码可能为空；修改已有密码时按页面提示填写。成功后必须做一次退出/重新登录验收，不要只依赖本地成功提示。
POST /token/logout
结束当前会话：
{ "token": "<TOKEN>" }无论网络响应是否返回，客户端都应清理内存 Token，并停止轮询。浏览器本地账号条目是否删除由用户选择。
访问码接口
POST /aimedb/reg
生成长期访问码。请求只需要当前 Token，响应通常包含 accessCode。长期码属于高敏感凭据，不能展示在公共日志或 URL 中。
POST /aimedb/reg-temp
生成一次性访问码。一次性码适合临时登录和测试；客户端应显示有效期提示，过期后重新生成，不要缓存成长期凭据。
POST /aimedb/reg-token
把网页侧的访问码、机台标识和验证信息绑定到登录流程。常见请求字段包括：
| 字段 | 说明 |
|---|---|
SGWCMAID | 页面要求的访问码/二维码文本 |
clientId | 已授权的机台标识 |
token | 当前网页会话 |
cf_token | 页面要求的人机验证值 |
customAimeUrl | 可选自定义地址 |
只有机台账号在页面明确显示对应目标和权限时，才提交机台标识。普通用户客户端不应凭猜测加入机台字段。
配方接口
POST /forward/get
读取当前账号可见的配方映射：
{ "token": "<TOKEN>" }机台账号在明确选择目标机台时，可能额外提交目标标识和凭据。响应中的 forwardData 是由配置名映射到 { enable, value } 的对象。未知配置名必须保留。
POST /forward/add
修改一项配置：
{
"token": "<TOKEN>",
"rule": "<VISIBLE_RULE>",
"enable": true,
"value": "<VALUE>"
}value 按页面约定传文本，即使它看起来是数字、列表或 JSON。保存后重新调用 forward/get，必要时按页面提示重启。
POST /forward/del
删除或清理当前账号可见的配置。该接口属于写入/删除风险操作，调用前保存原始配置，成功后重新读取并确认目标字段确实消失。不要用它清理未知字段。
相片接口
POST /photo/get
返回当前账号的文件名列表：
{ "token": "<TOKEN>" }空数组表示当前没有可见文件，不等于网络失败。
POST /photo/get-file
按 fileName 读取单个文件：
{ "token": "<TOKEN>", "fileName": "<FILE_NAME>" }成功时可能返回图片二进制；失败时可能返回 JSON。先读取 Content-Type，不要无条件调用 JSON 解析。
POST /photo/del-file
删除单个文件：
{ "token": "<TOKEN>", "fileName": "<FILE_NAME>" }文件名应来自列表接口或用户明确确认。删除前二次确认，超时后先读取列表再决定是否重试。
POST /photo/del
删除当前账号全部相片：
{ "token": "<TOKEN>" }这是高风险不可逆操作，客户端必须明确显示“全部相片”并要求二次确认，不能把它实现成单张删除循环。
账号缓存接口
POST /cache/backup
生成当前账号备份：
{ "token": "<TOKEN>" }data 是可演进对象。保存时保留完整对象、导出时间和账号别名，不要只挑选当前 UI 看见的字段。
POST /cache/restore
恢复 JSON 备份：
{
"token": "<TOKEN>",
"data": { "...": "<BACKUP_OBJECT>" }
}响应中的 count 只表示服务接受/处理的条目数量，不代表所有字段都已覆盖。恢复前先备份当前状态，恢复后重新读取记录、成绩和相片。
上传缓存接口
POST /upload-cache/get
取得快照索引：
{ "token": "<TOKEN>" }data 是索引名称数组。后续操作应使用服务返回的名称，不要由用户任意拼接。
POST /upload-cache/upload
上传指定快照：
{
"token": "<TOKEN>",
"indexName": "<INDEX_NAME>",
"SGWCMAID": "<QR_TEXT>",
"customAimeUrl": ""
}这是写入操作。响应可能包含 data、music 和 msg；客户端应展示消息并重新读取状态。
POST /upload-cache/get-file
下载快照对象：
{ "token": "<TOKEN>", "indexName": "<INDEX_NAME>" }返回的 data 结构可能随版本变化，客户端应按 JSON 保存，不要丢弃未知字段。
POST /upload-cache/del
删除快照：
{ "token": "<TOKEN>", "indexName": "<INDEX_NAME>" }调用前先下载留档并二次确认。超时后重新取列表，避免把已成功删除的请求再次提交。
用户乐曲与记录接口
POST /user/music/get
读取当前账号的乐曲成绩索引。返回结构通常为 data.userMusicList[].userMusicDetailList[]，行项目包含曲目编号、难度、游玩次数、达成率、连击状态、同步状态、最高分和扩展数字字段。
达成率是放大整数，状态字段是索引值；客户端不能把网页显示百分比再乘一次 100。
POST /playlog/get
按范围取得记录：
{ "token": "<TOKEN>", "start": 0, "end": 50 }范围是 [start, end)。下一页应使用实际返回数组长度推进，而不是盲目加请求大小。响应包含 total 和 playlogList。
记录可能包含地点、用户、对手、伙伴和详细判定，公开展示前必须脱敏。
成绩互动接口
POST /chart/social/get
读取曲目互动汇总和评论：
{
"token": "<TOKEN>",
"musicIds": [10001, 10002],
"includeReviews": false
}musicIds 可省略或传少量编号。大批量读取应分批并限频。
POST /chart/reaction
对曲目点赞/点踩：
{ "token": "<TOKEN>", "musicId": 10001, "action": "like" }action 使用 like 或 dislike。成功后以响应中的 social 刷新数量，不要只在本地加一。
POST /chart/comment/add
发表评论或回复：
{
"token": "<TOKEN>",
"musicId": 10001,
"parentId": "",
"content": "<COMMENT>"
}parentId 为空表示新评论，填写已有评论 ID 表示回复。提交前禁用按钮，响应丢失时先重新读取评论。
POST /chart/comment/del
删除评论：
{ "token": "<TOKEN>", "musicId": 10001, "commentId": "<COMMENT_ID>" }只应为当前用户拥有删除权限的评论显示按钮。删除前二次确认。
POST /chart/comment/reaction
对评论点赞/点踩：
{
"token": "<TOKEN>",
"musicId": 10001,
"commentId": "<COMMENT_ID>",
"action": "like"
}成功后使用返回的评论组更新页面。未知评论状态应保留原文。
内容反馈接口
POST /chart/review/request
提交内容反馈：
{ "token": "<TOKEN>", "musicId": 10001, "reason": "<REASON>" }反馈内容应包含曲目编号、难度、现象和复现条件，不要包含 Token、二维码或原始日志。
POST /chart/review/withdraw
撤回自己的反馈：
{
"token": "<TOKEN>",
"musicId": 10001,
"commentId": "<REPORT_COMMENT_ID>"
}只处理当前用户创建的反馈关联项，响应后重新读取互动数据。
POST /chart/review/list
读取审核列表，可选传入 status。该入口只在账号明确拥有审核权限时使用；普通客户端不应把它当作公开内容列表。
POST /chart/review/history
读取审核历史。返回项目可能包含操作者、时间、原因和结果，展示时按管理员隐私要求脱敏。
POST /chart/review/decision
提交审核决策：
{
"token": "<TOKEN>",
"musicId": 10001,
"action": "hide",
"note": "<NOTE>"
}action 使用页面允许的值。决策前显示目标曲目和当前状态，成功后重新读取审核列表和内容状态。
统计接口
GET /region/get
取得地区聚合列表。接口没有个人明细，空数组应显示为空状态，不应触发无限重试。
POST /usage/get
读取服务级聚合统计：
{ "token": "<TOKEN>" }结果是时间点快照，不应当用于精确计费或推断个人行为。
POST /player/queue/get
读取已授权机台的在线和会话统计：
{ "token": "<TOKEN>", "clientId": "<MACHINE_ID>" }响应可能包含在线用户、近期记录、会话时长和频率分析。多机台客户端必须保留来源机台和生成时间，不要把完整响应写入公共日志。
幂等、重试与限频
可以有限重试的读取
Token 验证、列表读取、地区统计和只读成绩请求，在网络断开或暂时性 5xx 时可以有限重试。建议使用指数退避并设置上限。
不应自动重试的写入
以下操作可能已经成功但响应丢失，不应盲目自动重试：
- 删除相片；
- 删除上传缓存；
- 恢复账号缓存；
- 修改配方；
- 上传快照；
- 发布评论；
- 提交审核决策。
先重新读取状态，再由用户决定是否重试。
推荐失败记录
客户端可以记录以下非敏感上下文：接口路径、HTTP 状态、业务消息、发生时间、账号本地别名、是否已经显示成功、是否可以安全重试。不要记录 Token、密码、访问码、机台私密配置和完整响应。