公开数据模型

本页把公开 API 中反复出现的数据结构集中列出，方便 TypeScript、Python 或其他客户端建立类型。字段可能新增，客户端应忽略未知字段并保留原始数据。

通用 Envelope

interface ResultEnvelope {
  success: boolean;
  msg: string;
}

失败时 success 通常为 false；部分验证接口使用 valid 而不是 success。

Token

interface TokenResult extends ResultEnvelope {
  token: string;
  isMachine: boolean;
}

interface TokenValidation {
  valid: boolean;
  token?: string;
  expires_at?: string;
  expired?: boolean;
}

配方

interface RuleValue {
  enable: boolean;
  value: string;
}

interface RuleMap {
  [visibleRuleName: string]: RuleValue;
}

interface ForwardResult extends ResultEnvelope {
  forwardData: RuleMap;
}

机台目标字段 clientId、clientPwd 只在账号拥有对应权限时出现，不要把它们放进普通用户客户端。

配方请求字段

请求	字段	类型	说明
获取	token	string	当前 Token
获取/清理	clientId	string?	有权限时指定机台
获取/清理	clientPwd	string?	机台凭据，不应记录日志
添加	rule	string	当前响应中可见的配置名
添加	enable	boolean	开关状态
添加	value	string	配置值，统一按文本传输

客户端不要把未知配置名写死，也不要把 clientPwd 放在浏览器 URL 中。

相片

interface PhotoListResult extends ResultEnvelope {
  fileList: string[];
}

interface PhotoDeleteResult extends ResultEnvelope {}

读取文件接口成功时不是 JSON，而是图片二进制；失败时才返回 ResultEnvelope。

缓存

interface BackupResult extends ResultEnvelope {
  data: unknown;
}

interface RestoreResult extends ResultEnvelope {
  count: number;
}

data 应被当作不透明对象保存，不要只挑选客户端认识的字段再恢复。

上传缓存

interface UploadCacheList extends ResultEnvelope {
  data: string[];
}

interface UploadCacheUploadResult extends ResultEnvelope {
  data: string;
  music: string;
}

interface UploadCacheFileResult extends ResultEnvelope {
  data: unknown;
}

上传请求通常还包含 indexName、SGWCMAID 和可选的 customAimeUrl。indexName 来自列表接口，不应由用户任意拼接；SGWCMAID 是敏感访问值，提交后不要写入日志。

用户乐曲数据

interface UserMusicRow {
  musicId: number;
  level: number;
  playCount: number;
  achievement: number;
  comboStatus: number;
  syncStatus: number;
  deluxscoreMax: number;
  scoreRank: number;
  extNum1: number;
  extNum2: number;
}

interface UserMusicResult extends ResultEnvelope {
  data: {
    userMusicList?: Array<{
      userMusicDetailList?: UserMusicRow[];
    }>;
  } | null;
}

achievement 是放大后的整数；comboStatus、syncStatus 和 scoreRank 是索引值，显示名称由客户端映射。extNum1/extNum2 属于扩展字段，未知时原样保留。

成绩互动

interface SocialRecord {
  musicId: number;
  likeCount: number;
  dislikeCount: number;
  commentCount: number;
  updatedAt: string;
}

interface Comment {
  id: string;
  musicId: number;
  parentId: string;
  kind: string;
  floor: number;
  user: string;
  content: string;
  likeCount: number;
  dislikeCount: number;
  createdAt: string;
}

interface CommentGroup {
  musicId: number;
  comments: Comment[];
}

评论、反馈和审核结果都可能增加新的 kind、status 或 action，客户端不要只接受固定枚举。

反馈和审核模型

interface ReviewRequest {
  user: string;
  reason: string;
  createdAt: string;
}

interface Review {
  musicId: number;
  requests: ReviewRequest[];
  status: string;
  decisionAction: string;
  decisionBy: string;
  decisionNote: string;
  createdAt: string;
  updatedAt: string;
}

审核接口只对明确拥有审核权限的账号开放。普通客户端可以显示 pending/approved/rejected 等状态，但不应显示或执行决策按钮。

游玩记录

游玩记录的基本字段分为四组：

1. 身份和地点：userId、orderId、playlogId、version、placeId、placeName；
2. 时间和曲目：loginDate、playDate、userPlayDate、musicId、level、trackNo；
3. 对战和伙伴：vs*、playedUser*、characterId*、characterLevel*、characterAwakening*；
4. 成绩和标记：achievement、deluxscore、scoreRank、判定计数、isClear、Rating/Grade 和扩展字段。

完整说明见游玩记录。

请求体

interface PlaylogRequest {
  token: string;
  start: number;
  end: number;
}

start 从 0 开始，end 不包含在结果中。响应的 total 用于计算总页数，客户端应以实际返回数组长度推进下一页。

查卡数据

查卡返回 playerQueueData，包含：

• statistics：在线和时间窗口摘要；
• currentOnlinePlayers：当前在线用户；
• timeRangeStatistics：时段聚合；
• playerActivityAnalysis：活动时长；
• recentPlayRecords：近期游玩记录；
• peakHoursAnalysis：峰值小时；
• sessionStatistics：会话摘要；
• recentSessionRecords：近期会话；
• sessionDurationAnalysis：会话时长；
• playerSessionFrequencyAnalysis：频率与回访；
• sessionHourlyDistribution：按小时分布；
• generatedAt：生成时间。

统计数据

公开统计字段包括用户数、绑定数、机台数、在线数、请求数、配方读取次数和耗时字段。它们是聚合快照，不能关联回单个用户。

interface UsageData {
  playerNum: number;
  chimeBindPlayerNum: number;
  machineNum: number;
  specialMachineNum: number;
  forwardRuleNum: number;
  totalRequestNum: number;
  onlineMachineNum: number;
  onlinePlayerNum: number;
  pullDataNum: number;
  pullDataAvgTime: number;
  pullDataTolTime: number;
}

统计接口没有个人明细字段；客户端不应把聚合数字与单个用户名称关联。

空值和兼容性

• data: null 表示当前没有可用数据，不一定是服务异常；
• 数组为空应显示空状态；
• 可选字段缺失时使用默认显示；
• 不要把未知字符串枚举当作错误；
• 保存原始响应，便于后续版本重新解析。