ZundaLink 文档

Appearance

公开 API 工作流示例 ​

本页把多个公开接口组合成可以直接测试的最小流程。示例中的地址、Token、访问码、机台标识和曲目编号全部是占位符，不能直接当作真实凭据使用。

统一约定 ​

text
BASE=https://xn--9er778cb3e.xn--igrr70arr3c.vip/zundalink/api/v0
TOKEN=<TOKEN>
  • JSON 请求使用 POST 和 Content-Type: application/json；
  • 地区聚合使用 GET；
  • Token 放在 JSON 请求体中，不放在 URL、查询字符串或日志中；
  • HTTP 200 不代表业务一定成功，必须同时检查 success 或 valid；
  • msg 是给用户看的诊断信息，应保留原文；
  • 失败后不要立即重复执行删除、恢复、评论和配置写入。

工作流一：登录、验证和退出 ​

取得会话 ​

二维码方式：

bash
curl -sS "$BASE/token/get" \
  -H "Content-Type: application/json" \
  --data '{"qrcode":"<QR_TEXT>"}'

用户名密码方式：

bash
curl -sS "$BASE/token/get" \
  -H "Content-Type: application/json" \
  --data '{"username":"<USERNAME>","password":"<PASSWORD>"}'

成功响应至少应包含 success: true、msg、token 和 isMachine。脚本应立即把 Token 放入内存安全区域，不要在标准输出中打印完整响应。

验证会话 ​

bash
curl -sS "$BASE/token/validate" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>"}'

验证响应使用 valid，并可能包含 expires_at、expired 或新的 token。如果 valid 为假，停止所有后台轮询，要求用户重新登录。

退出 ​

bash
curl -sS "$BASE/token/logout" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>"}'

无论退出请求是否成功，客户端都应清除内存中的 Token；本地保存的账号条目则按用户选择保留或删除。

工作流二：备份账号数据 ​

先生成快照：

bash
curl -sS "$BASE/cache/backup" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>"}' \
  -o account-backup.json

下载后检查：

  1. 文件能被 JSON 解析；
  2. 顶层响应的 success 为真；
  3. data 存在且不是明显的错误对象；
  4. 文件名包含账号别名和 UTC 时间，但不包含 Token；
  5. 文件放在加密磁盘或离线介质。

保存的是完整的 data 对象，而不是只挑选当前客户端认识的字段。未来字段新增时，这样才能保持恢复兼容性。

工作流三：恢复前确认与恢复 ​

恢复属于写入操作。推荐顺序：

text
当前数据备份 → 用户确认目标账号和文件 → 本地解析 JSON → 调用恢复 → 重新读取只读页面

调用示例：

bash
curl -sS "$BASE/cache/restore" \
  -H "Content-Type: application/json" \
  --data-binary @restore-payload.json

restore-payload.json 的形状为：

json
{
  "token": "<TOKEN>",
  "data": {
    "...": "完整备份对象"
  }
}

恢复成功后，count 只是服务接受或处理的条目数，不是“每个字段都覆盖成功”的证明。客户端应重新读取缓存相关页面、成绩和记录，并把恢复时间写入本地操作记录。

工作流四：读取配方并修改一个字段 ​

先读取当前响应：

bash
curl -sS "$BASE/forward/get" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>"}'

从响应中选择用户当前确实能看到的配置名，再提交一项修改：

bash
curl -sS "$BASE/forward/add" \
  -H "Content-Type: application/json" \
  --data '{
    "token":"<TOKEN>",
    "rule":"<VISIBLE_RULE>",
    "enable":true,
    "value":"<VALUE>"
  }'

提交后再次调用 forward/get。如果返回值没有变化，先检查权限、机台在线状态和是否需要重启，不要连续发送相同写入请求。

机台目标字段只应在页面明确显示目标机台选择和相应权限时使用。普通用户客户端不要凭猜测加入机台标识或凭据。

工作流五：读取相片并安全保存 ​

先取列表：

bash
curl -sS "$BASE/photo/get" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>"}'

从 fileList 选择一个服务返回的文件名，再读取文件：

bash
curl -sS "$BASE/photo/get-file" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>","fileName":"<FILE_NAME>"}' \
  -o photo.bin

文件接口成功时可能返回二进制，失败时可能返回 JSON。脚本必须先看 Content-Type 再选择 blob、流或 JSON 解析方式。

删除单张相片前应显示准确文件名并二次确认：

bash
curl -sS "$BASE/photo/del-file" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>","fileName":"<FILE_NAME>"}'

删除全部相片是独立的高风险操作，不能用单张删除循环代替，也不应自动重试。

工作流六：分页读取记录 ​

bash
curl -sS "$BASE/playlog/get" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>","start":0,"end":50}'

start 从 0 开始，end 不包含在本次结果中。下一页应使用实际收到的数组长度推进：

text
nextStart = currentStart + length(playlogList)

不能只用请求大小推进，因为服务可能返回少于请求数量的记录。到达 total、收到空数组或收到明确失败消息时停止。

记录中的时间、地点、用户名称和对战信息可能属于个人数据。导出前应提供脱敏选项，公共日志只保留记录编号和错误类型。

工作流七：读取成绩和互动 ​

先读当前账号的成绩索引：

bash
curl -sS "$BASE/user/music/get" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>"}'

再按一批曲目读取互动：

bash
curl -sS "$BASE/chart/social/get" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>","musicIds":[10001,10002]}'

发表或互动前：

  1. 禁用提交按钮，避免重复点击；
  2. 检查内容长度和敏感信息；
  3. 保存请求关联的曲目编号；
  4. 以响应中的 social 或 comments 更新页面，而不是只本地加一；
  5. 响应丢失时先重新读取，再决定是否需要重试。

内容反馈与审核决策属于不同权限。普通客户端只显示反馈入口；只有明确拥有审核权限并且页面显示审核区域时，才显示审核列表和处理按钮。

工作流八：读取聚合统计 ​

地区聚合：

bash
curl -sS "$BASE/region/get"

服务级统计：

bash
curl -sS "$BASE/usage/get" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>"}'

这些结果是某个时间点的聚合快照，不适合作为精确计费、个人行为证明或实时在线保证。页面应显示生成时间，并允许空数组和缺省统计字段。

工作流九：机台查卡 ​

只有明确拥有机台权限的账号才调用：

bash
curl -sS "$BASE/player/queue/get" \
  -H "Content-Type: application/json" \
  --data '{"token":"<TOKEN>","clientId":"<MACHINE_ID>"}'

响应中的当前在线、最近游玩、会话统计和用户频率都可能包含个人信息。多机台仪表盘必须为每个响应保留来源标识，自动刷新要设置合理间隔，并在 Token 失效时停止。

失败处理模板 ​

ts
type Result = { success?: boolean; valid?: boolean; msg?: string };

function isBusinessSuccess(data: Result): boolean {
  if (typeof data.valid === 'boolean') return data.valid;
  return data.success === true;
}

function describeFailure(data: Result, status: number): string {
  return data.msg || `请求失败（HTTP ${status}）`;
}

对每次失败至少记录：页面/接口名称、HTTP 状态、业务消息、发生时间、是否已经显示成功、是否可以安全重试。不要记录 Token、密码、访问码或完整响应。

版本兼容策略 ​

  • 新字段：忽略但保留；
  • 缺少可选字段：使用空数组、空对象或“暂无数据”；
  • 未知状态字符串：显示原文，不要让程序崩溃；
  • 未知错误：保留 msg，向用户提供重试或联系管理员的路径；
  • 响应结构变动：先以公开字段目录和公开数据模型为准，再更新客户端。

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

Copyright © 2025-2026 ZundaLink