ZundaLink 文档

Appearance

公开 API 按任务示例集 ​

本页把公开 API 按“用户想完成什么”重新排列。示例中的地址、账号、Token、访问码、文件名和编号均为占位符；请用当前页面返回的值替换，不要把真实值写进源码、日志或文档。

统一请求封装 ​

建议先实现一个只负责传输的函数，再在每个任务函数中做业务校验：

js
const BASE = '<PUBLIC_API_BASE>';

async function post(path, body) {
  const response = await fetch(`${BASE}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  const contentType = response.headers.get('content-type') || '';
  const payload = contentType.includes('application/json')
    ? await response.json()
    : await response.blob();

  return { response, payload };
}

传输层不应自动把所有失败请求重放。写入、删除、恢复、上传和机台动作要在上层确认状态后再决定是否重试。

任务一：使用二维码文本登录 ​

js
const { response, payload } = await post('/token/get', {
  qrcode: '<QR_TEXT>',
});

if (!response.ok || payload.success !== true) {
  throw new Error(payload.msg || '登录失败');
}

const token = payload.token;

验收：

  1. token 非空；
  2. 登录返回的账号类型符合预期；
  3. 立即调用验证接口；
  4. 不把二维码文本写入日志；
  5. 登录失败后不要连续提交同一张二维码。

任务二：使用用户名密码登录 ​

json
{
  "username": "<USERNAME>",
  "password": "<PASSWORD>"
}

用户名和密码需要一起提交。客户端应在发送前校验必填项，在内存中使用密码，成功后只保留受保护的 Token。失败时显示 msg，不要把密码加入错误对象或网络分析事件。

任务三：注册账号 ​

json
{
  "username": "<USERNAME>",
  "password": "<PASSWORD>",
  "cf_token": "<CHALLENGE_RESULT>"
}

注册是创建账号动作，不应自动循环重试。失败后先确认用户名是否已经被占用、人机验证是否过期和网络是否正常；不要在不确定结果时重复注册多个同名账号。

任务四：验证和退出 Token ​

验证：

json
{ "token": "<TOKEN>" }

客户端应判断 valid，并在可用时读取 expires_at/expired。如果 valid 为 false：

  • 停止轮询；
  • 停止上传、写入和删除；
  • 清理内存 Token；
  • 保留本地账号显示名；
  • 要求用户重新登录。

退出：

json
{ "token": "<TOKEN>" }

退出响应不明确时也应先清理本地会话状态，再通过账号选择器重新验证，不要继续用旧 Token 探测其它接口。

任务五：绑定或更新用户名密码 ​

json
{
  "token": "<TOKEN>",
  "username": "<USERNAME>",
  "old_password": "<OLD_PASSWORD>",
  "new_password": "<NEW_PASSWORD>"
}

首次绑定是否需要旧密码，以当前页面提示为准。成功后不要只相信成功消息，应退出并重新使用新凭据登录一次。新密码不得等于 Token、访问码或机台标识。

任务六：生成一次性或长期访问码 ​

生成长期码：

json
{ "token": "<TOKEN>" }

生成一次性码使用同一类请求，但生命周期不同。客户端应明确标注码的用途和有效期，复制按钮后清理剪贴板的长期保留风险。访问码只交给目标设备或本人，不要放在公开截图中。

任务七：绑定网页访问流程 ​

当页面明确显示目标机台和人机验证时，提交：

json
{
  "SGWCMAID": "<QR_TEXT>",
  "clientId": "<AUTHORIZED_MACHINE_ID>",
  "token": "<TOKEN>",
  "cf_token": "<CHALLENGE_RESULT>"
}

普通用户客户端不要自行加入机台字段。绑定前确认访问码来自本人或获得授权的设备；绑定后使用最小登录流程验收，失败时保留消息和时间而不是换一个随机机台标识重试。

任务八：读取和修改配方 ​

读取：

json
{ "token": "<TOKEN>" }

响应通常包含：

json
{
  "success": true,
  "msg": "success",
  "forwardData": {
    "<VISIBLE_RULE>": {
      "enable": true,
      "value": "<VALUE>"
    }
  }
}

修改一项：

json
{
  "token": "<TOKEN>",
  "rule": "<VISIBLE_RULE>",
  "enable": true,
  "value": "<VALUE>"
}

安全时序：读取 → 备份原值 → 只改一个可见项 → 保存 → 重新读取 → 按页面提示重启或验收。客户端不得把未识别的规则名自动写入服务。

删除或清理配置前必须保存完整的当前对象，并要求用户确认范围。超时后先读取，不要直接再次提交删除。

任务九：备份和恢复缓存 ​

备份：

json
{ "token": "<TOKEN>" }

收到 data 后保存完整对象、账号别名、导出时间和客户端版本。不要只保存页面当前显示的字段。

恢复：

json
{
  "token": "<TOKEN>",
  "data": { "<BACKUP_OBJECT>": "<VALUE>" }
}

恢复前：

  1. 下载当前状态；
  2. 确认备份属于同一账号；
  3. 预览来源和时间；
  4. 要求二次确认；
  5. 写入后重新读取记录、成绩、相片和配方。

count 是处理条数，不是所有页面已经完成索引的证明。

任务十：列出、下载和删除相片 ​

列出：

json
{ "token": "<TOKEN>" }

选择文件名后下载：

json
{
  "token": "<TOKEN>",
  "fileName": "<FILE_NAME_FROM_LIST>"
}

下载器先判断 Content-Type。图片成功时使用 Blob；JSON 响应时显示错误消息。删除单张前先重新读取列表并二次确认；删除全部必须明确显示“全部相片”，不能误实现成自动循环单张删除。

任务十一：管理上传缓存 ​

读取索引：

json
{ "token": "<TOKEN>" }

下载快照：

json
{
  "token": "<TOKEN>",
  "indexName": "<INDEX_FROM_LIST>"
}

上传快照：

json
{
  "token": "<TOKEN>",
  "indexName": "<INDEX_FROM_LIST>",
  "SGWCMAID": "<QR_TEXT>",
  "customAimeUrl": ""
}

删除快照前先下载留档。上传超时后刷新索引和记录，确认没有成功后再考虑重试。空列表只表示当前没有可见快照，不表示普通缓存为空。

任务十二：读取乐曲数据和游玩记录 ​

乐曲索引：

json
{ "token": "<TOKEN>" }

游玩记录：

json
{
  "token": "<TOKEN>",
  "start": 0,
  "end": 50
}

范围为 [start, end)。根据实际返回条数推进游标，保存每页请求范围。记录包含个人数据时，公开展示前去掉用户、地点、对手和伙伴等可识别信息。

任务十三：读取成绩互动 ​

批量读取少量曲目互动：

json
{
  "token": "<TOKEN>",
  "musicIds": [10001, 10002],
  "includeReviews": false
}

点赞/点踩：

json
{
  "token": "<TOKEN>",
  "musicId": 10001,
  "action": "like"
}

评论：

json
{
  "token": "<TOKEN>",
  "musicId": 10001,
  "parentId": "<OPTIONAL_COMMENT_ID>",
  "content": "<COMMENT>"
}

互动写入后重新读取汇总和评论。请求超时不应自动重复发布；先检查评论列表或互动计数。

任务十四：提交和处理内容反馈 ​

普通用户提交反馈时：

json
{
  "token": "<TOKEN>",
  "musicId": 10001,
  "reason": "<NON_SENSITIVE_REASON>"
}

用户撤回只能撤回本人有权限的反馈或评论。审核账号处理时，动作值以公开页面允许的选项为准，例如隐藏或显示；备注不要包含 Token、私钥或未公开内部信息。

反馈列表、历史和决定都是不同动作。客户端不要把“已提交”显示成“已处理”，要展示当前状态和更新时间。

任务十五：读取查卡、地区和服务统计 ​

查卡：

json
{
  "token": "<TOKEN>",
  "clientId": "<AUTHORIZED_MACHINE_ID>"
}

地区和服务统计使用当前账号权限读取。统计是快照或聚合值，不要用来反推出单个用户。多机台合并时保留每个来源，不要把合并值写回成单机台数据。

任务十六：安全关闭客户端 ​

客户端退出时：

  1. 停止自动刷新和未完成轮询；
  2. 取消尚未完成的读取；
  3. 清理内存 Token；
  4. 释放图片对象 URL；
  5. 清理临时二维码图片；
  6. 不把请求体写入退出日志；
  7. 在下一次打开时重新验证账号。

客户端实现的详细状态和错误规则见API 错误模型与重试，文件和分页边界见分页、范围与文件接口。

Released under the CC BY-NC-SA 4.0 License.

Copyright © 2025-2026 ZundaLink