依据游戏客户端 Assembly-CSharp.dll 反编译代码整理（Net.Packet.Mai2 / Net.VO.Mai2 命名空间）。 所有请求/响应结构均直接提取自游戏 VO 类定义，JSON 示例由脚本按字段类型自动生成。 对应数据版本：PRiSM PLUS。

1. 协议基础

1.1 传输方式

• 全部接口为 HTTP POST，请求/响应体均为二进制：

  请求体  = AES-256-CBC( 4字节大端长度前缀 + JSON(请求VO) )      # AesKey/AesIV 见 1.3
  响应体  = AES-256-CBC( JSON(响应VO) )

• 客户端类：NetHttpClient（加密 CipherAES.Encrypt）、NetQuery<TReq, TResp>（VO 载体）。

1.2 URL 规则（端点名混淆）

Api      = 端点名 + "MaimaiChn"                       # NetQuery 构造函数追加国服后缀
URL      = {TitleServerBaseUri} + MD5( Api + "8bF76dE9" )   # MD5 小写十六进制, 盐值硬编码

• 例：GetUserMapApi → 实际请求路径 = MD5("GetUserMapApiMaimaiChn8bF76dE9")。
• TitleServerBaseUri 由机器配置（OperationManager.GetBaseUri()）给出。
• 源码位置：Net.Packet.Packet.Obfuscator() / NetQuery..ctor。

1.3 AES 参数

不知道

1.4 通用机制

• 分页：列表类下载接口的响应带 nextIndex；nextIndex != 0 时须以该值再次请求直至为 0。
• 差量上传与 isNew 位图：UpsertUserAllApi 的每个列表只包含与上次服务器快照的差集； 配套的 isNewXxxList 字符串与数组按位对齐，"1" = 新增条目、"0" = 已有条目被修改 （源码 VOExtensions.BuildListData，以 key 字段判重，如 userMapList 按 mapId）。
• 登录流程：Ping → UserLoginApi（取得 loginId）→ 各 GetUser*Api 拉取数据 → 游玩 → 每曲 UploadUserPlaylogApi → 数据保存时 UploadUserPortraitApi/UploadUserPhotoApi（如有）→ UpsertUserAllApi → UserLogoutApi。
• 空请求体：部分接口的请求 VO 为空类（如 PingRequestVO、GameNgMusicIdRequestVO、 GameWeeklyRequestVO 等），示例中的 {} 即真实请求体。

1.5 请求头、会话与重试

• 重试：包失败时自动重试；同一包重试次数达到 NetConfig.RetryCountToErrorWithSamePacket 后转入错误流程并计入机器备份信息。
• 鉴权：请求 JSON 内携带 userId（UserAllRequestVO 等同时带 playlogId = 登录时服务器下发的 loginId），没有独立签名头。

1.6 图片上传（UserPortrait / UserPhoto）

照片/头像不走独立二进制通道，仍是同一套 AES 加密 JSON：

• UploadUserPortraitApi：UploadUserPortraitRequestVO { userPortrait }，UserPortrait.divData 为 JPG 的 Base64 字符串，大图按 divNumber（当前分片号）/divLength（总分片数）分片上传， 另带 placeId/clientId/uploadDate/fileName（文件名为 {userId}.jpg）。
• UploadUserPhotoApi：同理携带 UserPhoto（JPEG Base64 + trackNo）。

1.7 UpsertUserAll 差量对照表

UpsertUserAllApi 中各列表的差量判定键与 isNew 位图对应关系（源码 VOExtensions.ExportUserAll）：

服务器合并原则：位图 "1" = INSERT（服务器无此 key）、"0" = UPDATE（已有此 key）；无位图的字段整体覆盖。

2. API 详解

会话与基础

Ping — Ping（延迟探测）

网络连通性探测接口，也是全部接口中开销最小的一个。请求与响应均为（近乎）空对象，客户端 PingChecker 通过测量发出请求到收到响应的耗时得到往返延迟（毫秒），用于判定机器与服务器的在线状态；GameSetting.pingDisable 为 true 时可整体禁用该检测。

请求字段（PingRequestVO）

响应字段（PingResponseVO）

JSON 示例

请求（PingRequestVO）：

{}

响应（PingResponseVO）：

{
  "result": ""
}

服务器实现要点

• 直接返回 {} 或 {"result": ""} 即可，内容不参与逻辑
• 用于在线判定，延迟过高时客户端会提示网络异常

UserLoginApi — 用户登录

玩家刷卡后建立会话的核心接口。请求携带 Aime 卡号（accessCode）、机厅与机器标识（placeId/clientId/regionId）、是否继续游玩（isContinue）等信息；响应中的 loginId 是整个会话的锚点——之后每一首曲子的 UploadUserPlaylogApi 与保存时的 UpsertUserAllApi 都要回传它作为 playlogId。响应同时返回登录统计（累计/连续登录天数），登录奖励（UserLoginBonus）的发放也以本次登录为触发点。

请求字段（UserLoginRequestVO）

响应字段（UserLoginResponseVO）

JSON 示例

请求（UserLoginRequestVO）：

{
  "userId": 100000000000000001,
  "accessCode": "604012345678901234",
  "regionId": 0,
  "placeId": 0,
  "clientId": "",
  "dateTime": 0,
  "loginDateTime": 0,
  "isContinue": false,
  "genericFlag": 0,
  "token": ""
}

响应（UserLoginResponseVO）：

{
  "returnCode": 1,
  "lastLoginDate": "",
  "loginCount": 0,
  "consecutiveLoginCount": 0,
  "loginId": 1,
  "loginDateTime": 0,
  "token": ""
}

服务器实现要点

• 校验 accessCode 后创建会话，生成唯一的 loginId 返回
• isContinue 标记可区分新用户/老用户，决定是否走出块引导
• token 字段原样回填即可（客户端会保存并在预览等请求中回传）
• 响应会话 Cookie 需要下发，客户端后续请求会携带

GetUserPreviewApi — 刷卡预览

刷卡瞬间的"预览"接口，发生在 UserLoginApi 之前。以卡号派生的 userId 换取玩家的最小展示信息：昵称、Rating、图标/名牌/相框/搭档、最近游玩日期、封禁状态（banState）等，用于刷卡确认画面显示"欢迎回来"。同时以 isLogin 告知客户端该玩家是否已在别处登录，isInherit 标记是否存在可继承的数据。

请求字段（UserPreviewRequestVO）

响应字段（UserPreviewResponseVO）

JSON 示例

请求（UserPreviewRequestVO）：

{
  "userId": 100000000000000001,
  "segaIdAuthKey": "",
  "token": "",
  "clientId": ""
}

响应（UserPreviewResponseVO）：

{
  "userId": 100000000000000001,
  "userName": "玩家昵称",
  "isLogin": false,
  "lastGameId": "",
  "lastDataVersion": "",
  "lastRomVersion": "",
  "lastLoginDate": "",
  "lastPlayDate": "",
  "playerRating": 0,
  "nameplateId": 0,
  "iconId": 0,
  "trophyId": 0,
  "partnerId": 0,
  "frameId": 0,
  "dispRate": 0,
  "totalAwake": 0,
  "isNetMember": 0,
  "dailyBonusDate": "",
  "headPhoneVolume": 0,
  "isInherit": false,
  "banState": 0,
  "errorId": 0
}

服务器实现要点

• 未登录数据时返回 errorId 相应错误码，客户端走出块/错误流程
• banState 非 0 时客户端禁止进入游玩
• 不需要 Cookie，属于登录前接口

UserLogoutApi — 用户登出

结束会话。在数据保存状态机（StateULUserLogout）的最后调用，也用于服务器触发强制登出（NetPacketUtil.ForcedUserLogout）。请求带卡号、机厅信息与登出类型（LogoutType）。本接口在源码中存在两个请求 VO（UserLogoutRequestVO / UserLogoutRequest2VO），现行保存流程使用 Request2VO，两者字段高度重合。

请求字段（UserLogoutRequest2VO）

响应字段（UserLogoutResponseVO）

请求变体字段（UserLogoutRequestVO）

JSON 示例

请求（UserLogoutRequest2VO）：

{
  "userId": 100000000000000001,
  "accessCode": "604012345678901234",
  "regionId": 0,
  "placeId": 0,
  "clientId": "",
  "loginDateTime": 0,
  "type": 0,
  "delayLog": {
    "dlRequests": 0,
    "dlSize": 0,
    "dlRetry": 0,
    "loginMsec": 0,
    "saveMsec": 0,
    "reductionMusic": 0,
    "reductionItem": 0
  }
}

响应（UserLogoutResponseVO）：

{
  "returnCode": 1
}

服务器实现要点

• 清理会话与 Cookie
• LogoutType 枚举见附录 B.2
• returnCode 返回 1 即可

全局配置下载（机器级）

GetGameSettingApi — 全局游戏设定

机器级全局设定接口，开机联网时由 DataDownloaderMai2 拉取。响应中的 GameSetting 共 25 个字段，直接控制客户端行为：维护模式（isMaintenance）、计划重启窗口（rebootStartTime/EndTime）、各功能服务器地址（movieServerUri/deliverServerUri 等）、包超时与重试参数（packetTimeout/packetRetryCount）、照片与改名开关（uploadPhotoDisable/nameEntryDisable）等。

请求字段（GameSettingRequestVO）

响应字段（GameSettingResponseVO）

JSON 示例

请求（GameSettingRequestVO）：

{
  "placeId": 0,
  "clientId": ""
}

响应（GameSettingResponseVO）：

{
  "isAouAccession": false,
  "gameSetting": {
    "isMaintenance": false,
    "requestInterval": 0,
    "rebootStartTime": "",
    "rebootEndTime": "",
    "movieUploadLimit": 0,
    "movieStatus": 0,
    "movieServerUri": "",
    "deliverServerUri": "",
    "oldServerUri": "",
    "usbDlServerUri": "",
    "rebootInterval": 0,
    "pingDisable": false,
    "packetTimeout": 0,
    "packetTimeoutLong": 0,
    "packetRetryCount": 0,
    "userDataDlErrTimeout": 0,
    "userDataDlErrRetryCount": 0,
    "userDataDlErrSamePacketRetryCount": 0,
    "userDataUpSkipTimeout": 0,
    "userDataUpSkipRetryCount": 0,
    "iconPhotoDisable": false,
    "uploadPhotoDisable": false,
    "nameEntryDisable": false,
    "packetRecreateCount": 0,
    "collectDelayInfoDisable": false
  }
}

服务器实现要点

• 这是最优先实现的接口之一，字段值不合理会导致客户端行为异常
• 超时/重试字段建议给宽松值（私有服务器网络延迟波动大）
• isMaintenance=true 时客户端直接进入维护状态，可用于停服维护

备注

• 响应外层的 isAouAccession 为 AOU 协作标记，false 即可

GetGameEventApi — 运营活动列表

拉取当前生效的运营活动列表。请求以 type 区分活动大类、isAllEvent 决定是否包含未开始的；响应为 {type, startDate, endDate} 列表。活动驱动游戏内的加点、加成与解禁日程（与 Music.xml 的 eventName 活动体系联动）。

请求字段（GameEventRequestVO）

响应字段（GameEventResponseVO）

JSON 示例

请求（GameEventRequestVO）：

{
  "type": 0,
  "isAllEvent": false
}

响应（GameEventResponseVO）：

{
  "type": 0,
  "gameEventList": [
    {
      "type": 0,
      "id": 0,
      "startDate": "",
      "endDate": ""
    }
  ]
}

服务器实现要点

• 返回空列表即表示无活动
• 日期格式为字符串（yyyyMMdd 或带时间，客户端按字符串解析）

GetGameChargeApi — 收费项配置

收费项定义接口：通行证/门票等可购买项目的 orderId、chargeId、price 与销售起止日期。玩家使用收费项后产生的持有状态由 GetUserChargeApi 下载、UserChargelog 上传。

请求字段（GameChargeRequestVO）

响应字段（GameChargeResponseVO）

JSON 示例

请求（GameChargeRequestVO）：

{
  "isAll": false
}

响应（GameChargeResponseVO）：

{
  "length": 30,
  "gameChargeList": [
    {
      "orderId": 0,
      "chargeId": 0,
      "price": 0,
      "startDate": "",
      "endDate": ""
    }
  ]
}

服务器实现要点

• isAll=true 时返回全部定义
• chargeId 与 UserCharge.chargeId、UserChargelog.chargeId 对应

GetGameRankingApi — 排行数据

排行榜数据接口，请求参数 type 区分榜单种类（人气曲投票、周排行等），响应为 {id, point, userName} 列表，展示在选曲/大厅的排行界面。

请求字段（GameRankingRequestVO）

响应字段（GameRankingResponseVO）

JSON 示例

请求（GameRankingRequestVO）：

{
  "type": 0
}

响应（GameRankingResponseVO）：

{
  "type": 0,
  "gameRankingList": [
    {
      "id": 0,
      "point": 0,
      "userName": "玩家昵称"
    }
  ]
}

服务器实现要点

• 可返回空列表隐藏该功能入口

GetGameNgMusicIdApi — 禁用曲目列表

禁用曲目（GameNG）列表接口。请求体为空对象，响应为 musicIdList。列表中的曲目在选曲时被排除（与本地 OperationManager.IsGameNgMusicId 配合）。

请求字段（GameNgMusicIdRequestVO）

响应字段（GameNgMusicIdResponseVO）

JSON 示例

请求（GameNgMusicIdRequestVO）：

{}

响应（GameNgMusicIdResponseVO）：

{
  "length": 30,
  "musicIdList": [
    0
  ]
}

服务器实现要点

• 空列表即可；注意响应外层有 length 字段表示条数

GetGameMusicScoreApi — 谱面成绩数据

按 (musicId, level, type) 三元组查询单个谱面的成绩数据，响应为单个 MusicScore（scoreData 为字符串载荷，内容按 type 解释）。用于成绩排行/谱面成绩参考的按需查询。

请求字段（GameMusicScoreRequestVO）

响应字段（GameMusicScoreResponseVO）

JSON 示例

请求（GameMusicScoreRequestVO）：

{
  "musicId": 11820,
  "level": 3,
  "type": 0
}

响应（GameMusicScoreResponseVO）：

{
  "gameMusicScore": {
    "musicId": 11820,
    "level": 3,
    "type": 0,
    "scoreData": ""
  }
}

服务器实现要点

• 无数据时返回空 scoreData 即可

GetGameTournamentInfoApi — 锦标赛信息

锦标赛（官方比赛活动）信息接口，返回活动定义列表（含比赛曲目等），供比赛模式使用。

请求字段（GameTournamentInfoRequestVO）

响应字段（GameTournamentInfoResponseVO）

JSON 示例

请求（GameTournamentInfoRequestVO）：

{}

响应（GameTournamentInfoResponseVO）：

{
  "length": 30,
  "gameTournamentInfoList": [
    {
      "tournamentId": 0,
      "tournamentName": "",
      "rankingKind": 0,
      "scoreType": 0,
      "noticeStartDate": "",
      "noticeEndDate": "",
      "startDate": "",
      "endDate": "",
      "entryStartDate": "",
      "entryEndDate": "",
      "gameTournamentMusicList": [
        {}
      ]
    }
  ]
}

服务器实现要点

• 无比赛时返回空列表

GetGameWeeklyDataApi — 每周数据

每周运营数据接口，返回单个 GameWeeklyData 对象（周任务/周排行等每周刷新内容）。

请求字段（GameWeeklyRequestVO）

响应字段（GameWeeklyResponseVO）

JSON 示例

请求（GameWeeklyRequestVO）：

{}

响应（GameWeeklyResponseVO）：

{
  "gameWeeklyData": {
    "missionCategory": 0,
    "updateDate": "",
    "beforeDate": ""
  }
}

服务器实现要点

• 可返回默认结构

GetGameKaleidxScopeApi — 万花筒全局配置

万花筒（カレイドスコープ）模式的全局配置：门/钥匙的日程与章节定义。个人进度则由 GetUserKaleidxScopeApi / UpsertUserAll 的 userKaleidxScopeList 承载。

请求字段（GameKaleidxScopeRequestVO）

响应字段（GameKaleidxScopeResponseVO）

JSON 示例

请求（GameKaleidxScopeRequestVO）：

{}

响应（GameKaleidxScopeResponseVO）：

{
  "gameKaleidxScopeList": [
    {
      "gateId": 0,
      "phaseId": 0
    }
  ]
}

服务器实现要点

• 私有服务器若不开放万花筒玩法可返回空列表

玩家数据下载

GetUserDataApi — 用户主数据

用户主数据接口，返回 UserDetail（82 字段）——昵称、当前外观（头像/名牌/称号/相框/搭档）、当前选择的舞里程地图（selectMapId）、Rating 与段位、累计统计（游玩数、各难度 DXScore/达成率合计）、同行角色编成（charaSlot）、舞里程结转（mapStock）等。响应额外带 banState。是所有下载数据中最核心的一份。

请求字段（UserDetailRequestVO）

响应字段（UserDetailResponseVO）

JSON 示例

请求（UserDetailRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserDetailResponseVO）：

{
  "userId": 100000000000000001,
  "userData": {
    "accessCode": "604012345678901234",
    "userName": "玩家昵称",
    "isNetMember": 0,
    "point": 0,
    "totalPoint": 0,
    "iconId": 0,
    "plateId": 0,
    "titleId": 0,
    "partnerId": 0,
    "frameId": 0,
    "selectMapId": 0,
    "totalAwake": 0,
    "gradeRating": 0,
    "musicRating": 0,
    "playerRating": 0,
    "highestRating": 0,
    "gradeRank": 0,
    "classRank": 0,
    "courseRank": 0,
    "charaSlot": [
      0
    ],
    "charaLockSlot": [
      0
    ],
    "contentBit": 0,
    "playCount": 0,
    "currentPlayCount": 0,
    "renameCredit": 0,
    "mapStock": 0,
    "eventWatchedDate": "",
    "lastGameId": "",
    "lastRomVersion": "",
    "lastDataVersion": "",
    "lastLoginDate": "",
    "lastPlayDate": "",
    "lastPlayCredit": 0,
    "lastPlayMode": 0,
    "lastPlaceId": 0,
    "lastPlaceName": "",
    "lastAllNetId": 0,
    "lastRegionId": 0,
    "lastRegionName": "",
    "lastClientId": "",
    "lastCountryCode": "",
    "lastSelectEMoney": 0,
    "lastSelectTicket": 0,
    "lastSelectCourse": 0,
    "lastCountCourse": 0,
    "firstGameId": "",
    "firstRomVersion": "",
    "firstDataVersion": "",
    "firstPlayDate": "",
    "compatibleCmVersion": "",
    "dailyBonusDate": "",
    "dailyCourseBonusDate": "",
    "lastPairLoginDate": "",
    "lastTrialPlayDate": "",
    "playVsCount": 0,
    "playSyncCount": 0,
    "winCount": 0,
    "helpCount": 0,
    "comboCount": 0,
    "totalDeluxscore": 0,
    "totalBasicDeluxscore": 0,
    "totalAdvancedDeluxscore": 0,
    "totalExpertDeluxscore": 0,
    "totalMasterDeluxscore": 0,
    "totalReMasterDeluxscore": 0,
    "totalSync": 0,
    "totalBasicSync": 0,
    "totalAdvancedSync": 0,
    "totalExpertSync": 0,
    "totalMasterSync": 0,
    "totalReMasterSync": 0,
    "totalAchievement": 0,
    "totalBasicAchievement": 0,
    "totalAdvancedAchievement": 0,
    "totalExpertAchievement": 0,
    "totalMasterAchievement": 0,
    "totalReMasterAchievement": 0,
    "playerOldRating": 0,
    "playerNewRating": 0,
    "banState": 0,
    "friendRegistSkip": 0,
    "dateTime": 0
  },
  "banState": 0
}

服务器实现要点

• 新用户首次登录时返回按默认值填充的 UserDetail
• charaSlot 为空时客户端会让玩家编成角色
• banState 返回 0

GetUserExtendApi — 用户扩展数据

用户扩展数据：选曲光标位置（selectMusicId/categoryIndex/musicIndex）、排序偏好、拍照条款同意标记（isPhotoAgree）、结算画面设置等 16 个字段。属于"玩家上次离开时的状态"记忆。

请求字段（UserExtendRequestVO）

响应字段（UserExtendResponseVO）

JSON 示例

请求（UserExtendRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserExtendResponseVO）：

{
  "userId": 100000000000000001,
  "userExtend": {
    "selectMusicId": 0,
    "selectDifficultyId": 0,
    "categoryIndex": 0,
    "musicIndex": 0,
    "extraFlag": 0,
    "selectScoreType": 0,
    "extendContentBit": 0,
    "isPhotoAgree": false,
    "isGotoCodeRead": false,
    "selectResultDetails": false,
    "selectResultScoreViewType": 0,
    "sortCategorySetting": "/*SortTabID*/ 0",
    "sortMusicSetting": "/*SortMusicID*/ 0",
    "playStatusSetting": "/*PlaystatusTabID*/ 0",
    "selectedCardList": [
      0
    ],
    "encountMapNpcList": [
      {
        "npcId": 0,
        "musicId": 11820
      }
    ]
  }
}

服务器实现要点

• 新用户返回默认结构即可

GetUserOptionApi — 用户设置

用户设置接口，返回 UserOption（48 字段）：音符/滑条/触摸速度、各类设计（tap/hold/slide/star）、判定显示与调整、音量组、镜像模式、排序设置等，即设置菜单里的全部可调项。

请求字段（UserOptionRequestVO）

响应字段（UserOptionResponseVO）

JSON 示例

请求（UserOptionRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserOptionResponseVO）：

{
  "userId": 100000000000000001,
  "userOption": {
    "optionKind": "/*OptionKindID*/ 0",
    "noteSpeed": "/*OptionNotespeedID*/ 0",
    "slideSpeed": "/*OptionSlidespeedID*/ 0",
    "touchSpeed": "/*OptionTouchspeedID*/ 0",
    "tapDesign": "/*OptionGametapID*/ 0",
    "holdDesign": "/*OptionGameholdID*/ 0",
    "slideDesign": "/*OptionGameslideID*/ 0",
    "starType": "/*OptionStartypeID*/ 0",
    "outlineDesign": "/*OptionGameoutlineID*/ 0",
    "noteSize": "/*OptionNotesizeID*/ 0",
    "slideSize": "/*OptionSlidesizeID*/ 0",
    "touchSize": "/*OptionTouchsizeID*/ 0",
    "starRotate": "/*OptionStarrotateID*/ 0",
    "dispCenter": "/*OptionCenterdisplayID*/ 0",
    "outFrameType": "/*OptionOutframedisplayID*/ 0",
    "dispChain": "/*OptionDispchainID*/ 0",
    "dispRate": "/*OptionDisprateID*/ 0",
    "dispBar": "/*OptionDispbarlineID*/ 0",
    "touchEffect": "/*OptionToucheffectID*/ 0",
    "submonitorAnimation": "/*OptionSubmonitorID*/ 0",
    "submonitorAchive": "/*OptionSubmonAchiveID*/ 0",
    "submonitorAppeal": "/*OptionAppealID*/ 0",
    "matching": "/*OptionMatchingID*/ 0",
    "trackSkip": "/*OptionTrackskipID*/ 0",
    "brightness": "/*OptionMoviebrightnessID*/ 0",
    "mirrorMode": "/*OptionMirrorID*/ 0",
    "dispJudge": "/*OptionDispjudgeID*/ 0",
    "dispJudgePos": "/*OptionDispjudgeposID*/ 0",
    "dispJudgeTouchPos": "/*OptionDispjudgetouchposID*/ 0",
    "adjustTiming": "/*OptionJudgetimingID*/ 0",
    "judgeTiming": "/*OptionJudgetimingID*/ 0",
    "ansVolume": "/*OptionVolumeAnswerSoundID*/ 0",
    "tapHoldVolume": "/*OptionVolumeID*/ 0",
    "criticalSe": "/*OptionCriticalID*/ 0",
    "tapSe": "/*OptionTapSuccessSeID*/ 0",
    "breakSe": "/*OptionBreakseID*/ 0",
    "breakVolume": "/*OptionVolumeID*/ 0",
    "exSe": "/*OptionExseID*/ 0",
    "exVolume": "/*OptionVolumeID*/ 0",
    "slideSe": "/*OptionSlideseID*/ 0",
    "slideVolume": "/*OptionVolumeID*/ 0",
    "breakSlideVolume": "/*OptionVolumeID*/ 0",
    "touchVolume": "/*OptionVolumeID*/ 0",
    "touchHoldVolume": "/*OptionVolumeID*/ 0",
    "damageSeVolume": "/*OptionVolumeID*/ 0",
    "headPhoneVolume": "/*OptionHeadphonevolumeID*/ 0",
    "sortTab": "/*SortTabID*/ 0",
    "sortMusic": "/*SortMusicID*/ 0"
  }
}

服务器实现要点

• 字段均为枚举值 ID，新用户可全返 0（默认档）

GetUserCharacterApi — 持有角色

持有角色列表：characterId、等级（level 高位为转生次数）、觉醒阶段（awakening 0-4 星）、使用次数。角色是舞里程系统的核心——同行角色的队长/同色状态直接决定里程增速。

请求字段（UserCharacterRequestVO）

响应字段（UserCharacterResponseVO）

JSON 示例

请求（UserCharacterRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserCharacterResponseVO）：

{
  "userId": 100000000000000001,
  "userCharacterList": [
    {
      "characterId": 101,
      "level": 3,
      "awakening": 0,
      "useCount": 0
    }
  ]
}

服务器实现要点

• 新用户返回空列表或初始角色（でらっくま family）

GetUserItemApi — 持有物品（解锁列表）

持有物品接口——整个解锁体系的数据来源。UserItem 四元组 {itemKind, itemId, stock, isValid}，itemKind 遵循 ItemKind 枚举：5=整曲解锁（写入 Base 列表）、6=紫谱解锁、7=白谱解锁、8=Strong 谱解锁、12=门票、15=万花筒钥匙……所有 lockType=1/3/4 曲子的解锁状态、谱面级解锁状态都在这里。支持 nextIndex 分页，且响应带 itemKind（客户端按类型逐类拉取）。

请求字段（UserItemRequestVO）

响应字段（UserItemResponseVO）

JSON 示例

请求（UserItemRequestVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0
}

响应（UserItemResponseVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0,
  "itemKind": 5,
  "userItemList": [
    {
      "itemKind": 5,
      "itemId": 5011820,
      "stock": 0,
      "isValid": false
    }
  ]
}

服务器实现要点

• 按 itemKind 分页返回；客户端会循环拉取所有类型
• kind=5 的条目即"已解锁乐曲清单"，与 lockType=1 曲子求差即得"未解锁"集合

GetUserMapApi — 舞里程地图进度

舞里程地图进度接口，返回 UserMap 列表 {mapId, distance, isLock, isClear, isComplete, unlockFlag}，支持分页。客户端据此重建每张地图的推进状态与宝藏领取进度。

请求字段（UserMapRequestVO）

响应字段（UserMapResponseVO）

JSON 示例

请求（UserMapRequestVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0
}

响应（UserMapResponseVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0,
  "userMapList": [
    {
      "mapId": 1,
      "distance": 12345,
      "isLock": false,
      "isClear": false,
      "isComplete": false,
      "unlockFlag": 0
    }
  ]
}

服务器实现要点

• distance 为该图累计里程；isComplete 表示已走到终点
• unlockFlag 置 0 即可（开场动画标记）
• 新用户返回空列表

GetUserLoginBonusApi — 登录奖励进度

登录奖励进度：每个奖励活动的 bonusId、当前天数（point）、进行中/已拿满标记。

请求字段（UserLoginBonusRequestVO）

响应字段（UserLoginBonusResponseVO）

JSON 示例

请求（UserLoginBonusRequestVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0
}

响应（UserLoginBonusResponseVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0,
  "userLoginBonusList": [
    {
      "bonusId": 0,
      "point": 0,
      "isCurrent": false,
      "isComplete": false
    }
  ]
}

服务器实现要点

• 登录奖励的"发放"发生在 UserLoginApi 时由服务器计入

GetUserKaleidxScopeApi — 万花筒个人进度

万花筒模式个人进度：每扇门一条 UserKaleidxScope 记录 {gateId, isGateFound, isKeyFound, isClear, 成绩统计…}。钥匙不是独立列表——获得某门钥匙即对应记录的 isKeyFound=true。

请求字段（UserKaleidxScopeRequestVO）

响应字段（UserKaleidxScopeResponseVO）

JSON 示例

请求（UserKaleidxScopeRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserKaleidxScopeResponseVO）：

{
  "userId": 100000000000000001,
  "userKaleidxScopeList": [
    {
      "gateId": 0,
      "isGateFound": false,
      "isKeyFound": false,
      "isClear": false,
      "totalRestLife": 0,
      "totalAchievement": 0,
      "totalDeluxscore": 0,
      "bestAchievement": 0,
      "bestDeluxscore": 0,
      "bestAchievementDate": "",
      "bestDeluxscoreDate": "",
      "playCount": 0,
      "clearDate": "",
      "lastPlayDate": "",
      "isInfoWatched": false
    }
  ]
}

服务器实现要点

• 服务器发钥匙 = 按门 upsert 一条 isKeyFound=true 的记录
• 与 UpsertUserAll 的 userKaleidxScopeList（按 gateId 去重）同构

GetUserMissionDataApi — 任务进度

任务进度接口，响应由 userWeeklyData（周数据）与 userMissionDataList（任务定义与达成标记）组成。

请求字段（UserMissionRequestVO）

响应字段（UserMissionResponseVO）

JSON 示例

请求（UserMissionRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserMissionResponseVO）：

{
  "userId": 100000000000000001,
  "userWeeklyData": {
    "lastLoginWeek": "",
    "beforeLoginWeek": "",
    "friendBonusFlag": false
  },
  "userMissionDataList": [
    {
      "type": 0,
      "difficulty": 0,
      "targetGenreId": 0,
      "targetGenreTableId": 0,
      "conditionGenreId": 0,
      "conditionGenreTableId": 0,
      "clearFlag": false
    }
  ]
}

服务器实现要点

• 无任务活动时返回空列表

GetUserMusicApi — 乐曲成绩明细

乐曲成绩明细接口，返回 UserMusic 列表（内嵌 UserMusicDetail：曲目×难度的最佳达成率、FC/AP 状态、DXScore、rank 等），支持分页。是玩家成绩库的全量下载。

请求字段（UserMusicRequestVO）

响应字段（UserMusicResponseVO）

JSON 示例

请求（UserMusicRequestVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0
}

响应（UserMusicResponseVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0,
  "userMusicList": [
    {
      "userMusicDetailList": [
        {}
      ]
    }
  ]
}

服务器实现要点

• 成绩量大的玩家需正确处理分页
• achievement 为万分比整数

GetUserRatingApi — 评级数据

Rating 构成接口：当前 rating 值 + 四个 UserRate 列表（旧曲 Best 35 / 新曲 Best 15 及各自的候选位）+ 段位对象 udemae。

请求字段（UserRatingRequestVO）

响应字段（UserRatingResponseVO）

JSON 示例

请求（UserRatingRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserRatingResponseVO）：

{
  "userId": 100000000000000001,
  "userRating": {
    "rating": 0,
    "ratingList": [
      {
        "musicId": 11820,
        "level": 3,
        "romVersion": 0,
        "achievement": 0
      }
    ],
    "newRatingList": [
      {
        "musicId": 11820,
        "level": 3,
        "romVersion": 0,
        "achievement": 0
      }
    ],
    "nextRatingList": [
      {
        "musicId": 11820,
        "level": 3,
        "romVersion": 0,
        "achievement": 0
      }
    ],
    "nextNewRatingList": [
      {
        "musicId": 11820,
        "level": 3,
        "romVersion": 0,
        "achievement": 0
      }
    ],
    "udemae": {
      "rate": 0,
      "maxRate": 0,
      "classValue": 0,
      "maxClassValue": 0,
      "totalWinNum": 0,
      "totalLoseNum": 0,
      "maxWinNum": 0,
      "maxLoseNum": 0,
      "winNum": 0,
      "loseNum": 0,
      "npcTotalWinNum": 0,
      "npcTotalLoseNum": 0,
      "npcMaxWinNum": 0,
      "npcMaxLoseNum": 0,
      "npcWinNum": 0,
      "npcLoseNum": 0
    }
  }
}

服务器实现要点

• 新用户各列表为空、rating=0

GetUserActivityApi — 活动日志

活动日志接口，返回 UserActivity = {playList, musicList} 两个 UserAct 列表。UserAct.kind 遵循 ActivityCode（100=传导乐曲解锁、120=挑战曲通关等），是"玩家达成史"的流水。

请求字段（UserActivityRequestVO）

响应字段（UserActivityResponseVO）

JSON 示例

请求（UserActivityRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserActivityResponseVO）：

{
  "userActivity": {
    "playList": [
      {
        "kind": 0,
        "id": 0,
        "sortNumber": 0,
        "param1": 0,
        "param2": 0,
        "param3": 0,
        "param4": 0
      }
    ],
    "musicList": [
      {
        "kind": 0,
        "id": 0,
        "sortNumber": 0,
        "param1": 0,
        "param2": 0,
        "param3": 0,
        "param4": 0
      }
    ]
  }
}

服务器实现要点

• 游戏内"达成/通知"画面据此渲染；返回空列表可隐藏

GetUserFavoriteApi — 收藏乐曲

收藏乐曲：一个 {itemKind, itemIdList} 对象（按类别分组收藏的曲目 ID 列表）。

请求字段（UserFavoriteRequestVO）

响应字段（UserFavoriteResponseVO）

JSON 示例

请求（UserFavoriteRequestVO）：

{
  "userId": 100000000000000001,
  "itemKind": 5
}

响应（UserFavoriteResponseVO）：

{
  "userId": 100000000000000001,
  "userFavorite": {
    "itemKind": 5,
    "itemIdList": [
      0
    ]
  }
}

服务器实现要点

• 返回空对象即可

GetUserFavoriteItemApi — 收藏物品

收藏物品接口（按键 kind 分类拉取，支持分页与 isAllFavoriteItem 全量标记）。

请求字段（UserFavoriteItemRequestVO）

响应字段（UserFavoriteItemResponseVO）

JSON 示例

请求（UserFavoriteItemRequestVO）：

{
  "userId": 100000000000000001,
  "kind": 0,
  "nextIndex": 0,
  "isAllFavoriteItem": false
}

响应（UserFavoriteItemResponseVO）：

{
  "userId": 100000000000000001,
  "kind": 0,
  "nextIndex": 0,
  "userFavoriteItemList": [
    {
      "orderId": 0,
      "id": 0
    }
  ]
}

服务器实现要点

• 空列表即可

GetUserGhostApi — 幽灵数据

幽灵数据接口：返回其他玩家（对手）的单曲成绩与档案缩略（UserGhost），选曲时叠加显示"幽灵"成绩线。

请求字段（UserGhostRequestVO）

响应字段（UserGhostResponseVO）

JSON 示例

请求（UserGhostRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserGhostResponseVO）：

{
  "userId": 100000000000000001,
  "userGhostList": [
    {
      "name": "",
      "iconId": 0,
      "plateId": 0,
      "titleId": 0,
      "rate": 0,
      "udemaeRate": 0,
      "courseRank": 0,
      "classRank": 0,
      "classValue": 0,
      "playDatetime": "",
      "shopId": 0,
      "regionCode": 0,
      "typeId": "/*MusicDifficultyID*/ 0",
      "musicId": 11820,
      "difficulty": 0,
      "version": 0,
      "resultBitList": [
        0
      ],
      "resultNum": 0,
      "achievement": 0
    }
  ]
}

服务器实现要点

• 无幽灵功能可返回空列表

GetUserCourseApi — 课程模式进度

课程模式（段位认定等）进度：courseId、通关标记、剩余命数合计、最佳达成率/DXScore 及日期、挑战次数。支持分页。

请求字段（UserCourseRequestVO）

响应字段（UserCourseResponseVO）

JSON 示例

请求（UserCourseRequestVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0
}

响应（UserCourseResponseVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0,
  "userCourseList": [
    {
      "courseId": 0,
      "isLastClear": false,
      "totalRestlife": 0,
      "totalAchievement": 0,
      "totalDeluxscore": 0,
      "playCount": 0,
      "clearDate": "",
      "lastPlayDate": "",
      "bestAchievement": 0,
      "bestAchievementDate": "",
      "bestDeluxscore": 0,
      "bestDeluxscoreDate": ""
    }
  ]
}

服务器实现要点

• 新玩家返回空列表

GetUserChargeApi — 持有收费道具

持有收费道具：chargeId（对应 GetGameChargeApi 定义）、剩余次数（stock）、购买/失效日期。通行证（有効期限内无限游玩加成）与门票都表现为 UserCharge。

请求字段（UserChargeRequestVO）

响应字段（UserChargeResponseVO）

JSON 示例

请求（UserChargeRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserChargeResponseVO）：

{
  "userId": 100000000000000001,
  "length": 30,
  "userChargeList": [
    {
      "chargeId": 0,
      "stock": 0,
      "purchaseDate": "",
      "validDate": ""
    }
  ]
}

服务器实现要点

• 有效期校验由服务器在结算时执行

GetUserShopStockApi — 商店库存

商店库存：玩家在各商店商品上的已兑换次数（shopItemId + tradeCount），用于限购。

请求字段（UserShopStockRequestVO）

响应字段（UserShopStockResponseVO）

JSON 示例

请求（UserShopStockRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserShopStockResponseVO）：

{
  "userId": 100000000000000001,
  "userShopStockList": [
    {
      "shopItemId": 0,
      "tradeCount": 0
    }
  ]
}

服务器实现要点

• 返回空列表即无兑换记录

GetUserFriendSeasonRankingApi — 友情赛季排名

友情对战赛季排名数据（seasonId 定位赛季），支持分页。

请求字段（UserFriendSeasonRankingRequestVO）

响应字段（UserFriendSeasonRankingResponseVO）

JSON 示例

请求（UserFriendSeasonRankingRequestVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0
}

响应（UserFriendSeasonRankingResponseVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0,
  "userFriendSeasonRankingList": [
    {
      "seasonId": 0,
      "point": 0,
      "rank": 0,
      "rewardGet": false,
      "userName": "玩家昵称",
      "recordDate": ""
    }
  ]
}

服务器实现要点

• 无赛季活动时返回空列表

GetUserRegionApi — 游玩地域

玩家游玩过的地域记录（regionId + 游玩次数 + 首次日期），配合地域.collect 玩法。

请求字段（UserRegionRequestVO）

响应字段（UserRegionResponseVO）

JSON 示例

请求（UserRegionRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserRegionResponseVO）：

{
  "userId": 100000000000000001,
  "length": 30,
  "userRegionList": [
    {
      "regionId": 0,
      "playCount": 0,
      "created": ""
    }
  ]
}

服务器实现要点

• 可由 playlog 的 regionId 汇总生成

GetUserPortraitApi — 拉取肖像

拉取玩家面部肖像。请求仅 {userId}，响应 length 为分片信息（数据体量小，实际照片内容按需上传/下载）。

请求字段（GetUserPortraitRequestVO）

响应字段（GetUserPortraitResponseVO）

JSON 示例

请求（GetUserPortraitRequestVO）：

{
  "userId": 100000000000000001
}

响应（GetUserPortraitResponseVO）：

{
  "length": 30
}

服务器实现要点

• 未设置肖像时返回空

GetUserNewItemApi — 游玩结算新物品

由服务器按游玩记录结算解锁的接口：请求携带 version 与本局全部 userPlaylogList，服务器分析后返回一个待解锁物品 {itemKind, itemId}。它是"游玩行为→解锁"的服务器侧结算通道（如条件达成的新曲解锁）。

请求字段（UserNewItemRequestVO）

响应字段（UserNewItemResponseVO）

JSON 示例

请求（UserNewItemRequestVO）：

{
  "userId": 100000000000000001,
  "version": 0,
  "userPlaylogList": [
    {
      "userId": 100000000000000001,
      "orderId": 0,
      "playlogId": 1,
      "version": 0,
      "placeId": 0,
      "placeName": "",
      "loginDate": 0,
      "playDate": "",
      "userPlayDate": "",
      "type": 0,
      "musicId": 11820,
      "level": 3,
      "trackNo": 0,
      "vsMode": 0,
      "vsUserName": "",
      "vsStatus": 0,
      "vsUserRating": 0,
      "vsUserAchievement": 0,
      "vsUserGradeRank": 0,
      "vsRank": 0,
      "playerNum": 0,
      "playedUserId1": 0,
      "playedUserName1": "",
      "playedMusicLevel1": 0,
      "playedUserId2": 0,
      "playedUserName2": "",
      "playedMusicLevel2": 0,
      "playedUserId3": 0,
      "playedUserName3": "",
      "playedMusicLevel3": 0,
      "characterId1": 0,
      "characterLevel1": 0,
      "characterAwakening1": 0,
      "characterId2": 0,
      "characterLevel2": 0,
      "characterAwakening2": 0,
      "characterId3": 0,
      "characterLevel3": 0,
      "characterAwakening3": 0,
      "characterId4": 0,
      "characterLevel4": 0,
      "characterAwakening4": 0,
      "characterId5": 0,
      "characterLevel5": 0,
      "characterAwakening5": 0,
      "achievement": 0,
      "deluxscore": 0,
      "scoreRank": 0,
      "maxCombo": 0,
      "totalCombo": 0,
      "maxSync": 0,
      "totalSync": 0,
      "tapCriticalPerfect": 0,
      "tapPerfect": 0,
      "tapGreat": 0,
      "tapGood": 0,
      "tapMiss": 0,
      "holdCriticalPerfect": 0,
      "holdPerfect": 0,
      "holdGreat": 0,
      "holdGood": 0,
      "holdMiss": 0,
      "slideCriticalPerfect": 0,
      "slidePerfect": 0,
      "slideGreat": 0,
      "slideGood": 0,
      "slideMiss": 0,
      "touchCriticalPerfect": 0,
      "touchPerfect": 0,
      "touchGreat": 0,
      "touchGood": 0,
      "touchMiss": 0,
      "breakCriticalPerfect": 0,
      "breakPerfect": 0,
      "breakGreat": 0,
      "breakGood": 0,
      "breakMiss": 0,
      "isTap": false,
      "isHold": false,
      "isSlide": false,
      "isTouch": false,
      "isBreak": false,
      "isCriticalDisp": false,
      "isFastLateDisp": false,
      "fastCount": 0,
      "lateCount": 0,
      "isAchieveNewRecord": false,
      "isDeluxscoreNewRecord": false,
      "comboStatus": 0,
      "syncStatus": 0,
      "isClear": false,
      "beforeRating": 0,
      "afterRating": 0,
      "beforeGrade": 0,
      "afterGrade": 0,
      "afterGradeRank": 0,
      "beforeDeluxRating": 0,
      "afterDeluxRating": 0,
      "isPlayTutorial": false,
      "isEventMode": false,
      "isFreedomMode": false,
      "playMode": 0,
      "isNewFree": false,
      "trialPlayAchievement": 0,
      "extNum1": 0,
      "extNum2": 0,
      "extNum4": 0,
      "extBool1": false,
      "extBool2": false,
      "extBool3": false
    }
  ]
}

响应（UserNewItemResponseVO）：

{
  "userId": 100000000000000001,
  "itemKind": 5,
  "itemId": 5011820
}

服务器实现要点

• 最简单的实现：返回 kind=0/空；如需实现"打 X 首歌解锁 Y"类规则在此结算

GetUserNewItemListApi — 新物品列表

GetUserNewItemApi 的列表版：请求额外携带完整 UserDetail，返回 UserItem 列表（带新获得标记的物品）。

请求字段（UserNewItemListRequestVO）

响应字段（UserNewItemListResponseVO）

JSON 示例

请求（UserNewItemListRequestVO）：

{
  "userId": 100000000000000001,
  "version": 0,
  "userData": [
    {
      "accessCode": "604012345678901234",
      "userName": "玩家昵称",
      "isNetMember": 0,
      "point": 0,
      "totalPoint": 0,
      "iconId": 0,
      "plateId": 0,
      "titleId": 0,
      "partnerId": 0,
      "frameId": 0,
      "selectMapId": 0,
      "totalAwake": 0,
      "gradeRating": 0,
      "musicRating": 0,
      "playerRating": 0,
      "highestRating": 0,
      "gradeRank": 0,
      "classRank": 0,
      "courseRank": 0,
      "charaSlot": [
        0
      ],
      "charaLockSlot": [
        0
      ],
      "contentBit": 0,
      "playCount": 0,
      "currentPlayCount": 0,
      "renameCredit": 0,
      "mapStock": 0,
      "eventWatchedDate": "",
      "lastGameId": "",
      "lastRomVersion": "",
      "lastDataVersion": "",
      "lastLoginDate": "",
      "lastPlayDate": "",
      "lastPlayCredit": 0,
      "lastPlayMode": 0,
      "lastPlaceId": 0,
      "lastPlaceName": "",
      "lastAllNetId": 0,
      "lastRegionId": 0,
      "lastRegionName": "",
      "lastClientId": "",
      "lastCountryCode": "",
      "lastSelectEMoney": 0,
      "lastSelectTicket": 0,
      "lastSelectCourse": 0,
      "lastCountCourse": 0,
      "firstGameId": "",
      "firstRomVersion": "",
      "firstDataVersion": "",
      "firstPlayDate": "",
      "compatibleCmVersion": "",
      "dailyBonusDate": "",
      "dailyCourseBonusDate": "",
      "lastPairLoginDate": "",
      "lastTrialPlayDate": "",
      "playVsCount": 0,
      "playSyncCount": 0,
      "winCount": 0,
      "helpCount": 0,
      "comboCount": 0,
      "totalDeluxscore": 0,
      "totalBasicDeluxscore": 0,
      "totalAdvancedDeluxscore": 0,
      "totalExpertDeluxscore": 0,
      "totalMasterDeluxscore": 0,
      "totalReMasterDeluxscore": 0,
      "totalSync": 0,
      "totalBasicSync": 0,
      "totalAdvancedSync": 0,
      "totalExpertSync": 0,
      "totalMasterSync": 0,
      "totalReMasterSync": 0,
      "totalAchievement": 0,
      "totalBasicAchievement": 0,
      "totalAdvancedAchievement": 0,
      "totalExpertAchievement": 0,
      "totalMasterAchievement": 0,
      "totalReMasterAchievement": 0,
      "playerOldRating": 0,
      "playerNewRating": 0,
      "banState": 0,
      "friendRegistSkip": 0,
      "dateTime": 0
    }
  ],
  "userPlaylogList": [
    {
      "userId": 100000000000000001,
      "orderId": 0,
      "playlogId": 1,
      "version": 0,
      "placeId": 0,
      "placeName": "",
      "loginDate": 0,
      "playDate": "",
      "userPlayDate": "",
      "type": 0,
      "musicId": 11820,
      "level": 3,
      "trackNo": 0,
      "vsMode": 0,
      "vsUserName": "",
      "vsStatus": 0,
      "vsUserRating": 0,
      "vsUserAchievement": 0,
      "vsUserGradeRank": 0,
      "vsRank": 0,
      "playerNum": 0,
      "playedUserId1": 0,
      "playedUserName1": "",
      "playedMusicLevel1": 0,
      "playedUserId2": 0,
      "playedUserName2": "",
      "playedMusicLevel2": 0,
      "playedUserId3": 0,
      "playedUserName3": "",
      "playedMusicLevel3": 0,
      "characterId1": 0,
      "characterLevel1": 0,
      "characterAwakening1": 0,
      "characterId2": 0,
      "characterLevel2": 0,
      "characterAwakening2": 0,
      "characterId3": 0,
      "characterLevel3": 0,
      "characterAwakening3": 0,
      "characterId4": 0,
      "characterLevel4": 0,
      "characterAwakening4": 0,
      "characterId5": 0,
      "characterLevel5": 0,
      "characterAwakening5": 0,
      "achievement": 0,
      "deluxscore": 0,
      "scoreRank": 0,
      "maxCombo": 0,
      "totalCombo": 0,
      "maxSync": 0,
      "totalSync": 0,
      "tapCriticalPerfect": 0,
      "tapPerfect": 0,
      "tapGreat": 0,
      "tapGood": 0,
      "tapMiss": 0,
      "holdCriticalPerfect": 0,
      "holdPerfect": 0,
      "holdGreat": 0,
      "holdGood": 0,
      "holdMiss": 0,
      "slideCriticalPerfect": 0,
      "slidePerfect": 0,
      "slideGreat": 0,
      "slideGood": 0,
      "slideMiss": 0,
      "touchCriticalPerfect": 0,
      "touchPerfect": 0,
      "touchGreat": 0,
      "touchGood": 0,
      "touchMiss": 0,
      "breakCriticalPerfect": 0,
      "breakPerfect": 0,
      "breakGreat": 0,
      "breakGood": 0,
      "breakMiss": 0,
      "isTap": false,
      "isHold": false,
      "isSlide": false,
      "isTouch": false,
      "isBreak": false,
      "isCriticalDisp": false,
      "isFastLateDisp": false,
      "fastCount": 0,
      "lateCount": 0,
      "isAchieveNewRecord": false,
      "isDeluxscoreNewRecord": false,
      "comboStatus": 0,
      "syncStatus": 0,
      "isClear": false,
      "beforeRating": 0,
      "afterRating": 0,
      "beforeGrade": 0,
      "afterGrade": 0,
      "afterGradeRank": 0,
      "beforeDeluxRating": 0,
      "afterDeluxRating": 0,
      "isPlayTutorial": false,
      "isEventMode": false,
      "isFreedomMode": false,
      "playMode": 0,
      "isNewFree": false,
      "trialPlayAchievement": 0,
      "extNum1": 0,
      "extNum2": 0,
      "extNum4": 0,
      "extBool1": false,
      "extBool2": false,
      "extBool3": false
    }
  ]
}

响应（UserNewItemListResponseVO）：

{
  "userId": 100000000000000001,
  "userItemList": [
    {
      "itemKind": 5,
      "itemId": 5011820,
      "stock": 0,
      "isValid": false
    }
  ]
}

服务器实现要点

• 返回空列表即可

GetUserCardApi — 卡片数据

玩家绑定的 Aime 卡信息（UserCard 列表）。

请求字段（UserCardRequestVO）

响应字段（UserCardResponseVO）

JSON 示例

请求（UserCardRequestVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0
}

响应（UserCardResponseVO）：

{
  "userId": 100000000000000001,
  "nextIndex": 0,
  "userCardList": [
    {
      "cardId": 0,
      "cardTypeId": 0,
      "charaId": 0,
      "mapId": 1,
      "startDate": "",
      "endDate": ""
    }
  ]
}

GetUserIntimateApi — 搭档亲密度

PartnerCloseness/亲密度数据（UserIntimate 列表）。Packet 类名为 PacketGetUserPartnerCloseness。

请求字段（UserIntimateRequestVO）

响应字段（UserIntimateResponseVO）

JSON 示例

请求（UserIntimateRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserIntimateResponseVO）：

{
  "userId": 100000000000000001,
  "length": 30,
  "userIntimateList": [
    {
      "partnerId": 0,
      "intimateLevel": 0,
      "intimateCountRewarded": 0
    }
  ]
}

GetUserScoreRankingApi — 谱面成绩排行

成绩排行（score ranking）活动的榜单数据。

请求字段（UserScoreRankingRequestVO）

响应字段（UserScoreRankingResponseVO）

JSON 示例

请求（UserScoreRankingRequestVO）：

{
  "userId": 100000000000000001,
  "competitionId": 0
}

响应（UserScoreRankingResponseVO）：

{
  "userId": 100000000000000001,
  "userScoreRanking": {
    "tournamentId": 0,
    "totalScore": 0,
    "ranking": 0,
    "rankingDate": ""
  }
}

GetUserRivalDataApi — 对手档案

对手（rival）档案接口：请求带 rivalId，返回对手的 UserRivalData。

请求字段（UserRivalRequestVO）

响应字段（UserRivalResponseVO）

JSON 示例

请求（UserRivalRequestVO）：

{
  "userId": 100000000000000001,
  "rivalId": 0
}

响应（UserRivalResponseVO）：

{
  "userId": 100000000000000001,
  "userRivalData": {
    "rivalId": 0,
    "rivalName": ""
  }
}

服务器实现要点

• 无 rival 系统返回默认结构

GetUserRivalMusicApi — 对手乐曲成绩

对手乐曲成绩：请求带 rivalId，返回该对手的成绩列表，支持分页。

请求字段（UserRivalMusicRequestVO）

响应字段（UserRivalMusicResponseVO）

JSON 示例

请求（UserRivalMusicRequestVO）：

{
  "userId": 100000000000000001,
  "rivalId": 0,
  "nextIndex": 0
}

响应（UserRivalMusicResponseVO）：

{
  "userId": 100000000000000001,
  "rivalId": 0,
  "nextIndex": 0,
  "userRivalMusicList": [
    {
      "musicId": 11820,
      "userRivalMusicDetailList": [
        {}
      ]
    }
  ]
}

服务器实现要点

• 空列表即可

GetUserRecommendRateMusicApi — 评级推荐曲

按 Rating 推荐曲目：返回推荐曲目对象列表（升 Rating 建议选曲）。

请求字段（UserRecommendRateMusicRequestVO）

响应字段（UserRecommendRateMusicResponseVO）

JSON 示例

请求（UserRecommendRateMusicRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserRecommendRateMusicResponseVO）：

{
  "userId": 100000000000000001,
  "userRecommendRateMusicIdList": [
    {
      "musicId": 11820,
      "level": 3,
      "averageAchievement": 0
    }
  ]
}

服务器实现要点

• 可由成绩与 ratingList 计算或返回空

GetUserRecommendSelectMusicApi — 选曲推荐

选曲场景的推荐曲目，响应为纯 ID 列表（userRecommendSelectionMusicIdList）。注意端点名是 RecommendSelectMusic（Packet 类名写作 Selection）。

请求字段（UserRecommendSelectionMusicRequestVO）

响应字段（UserRecommendSelectionMusicResponseVO）

JSON 示例

请求（UserRecommendSelectionMusicRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserRecommendSelectionMusicResponseVO）：

{
  "userId": 100000000000000001,
  "userRecommendSelectionMusicIdList": [
    0
  ]
}

服务器实现要点

• 返回空列表即无推荐

GetUserFriendBonusApi — 好友加成

好友加成：与好友同玩时获得的额外里程（getMiles）与结果码。

请求字段（UserFriendBonusRequestVO）

响应字段（UserFriendBonusResponseVO）

JSON 示例

请求（UserFriendBonusRequestVO）：

{
  "userId": 100000000000000001
}

响应（UserFriendBonusResponseVO）：

{
  "userId": 100000000000000001,
  "returnCode": 1,
  "getMiles": 0
}

服务器实现要点

• 无好友体系返回 getMiles=0

GetUserFriendCheckApi — 好友校验

好友校验：请求带双方 userId，返回 returnCode 表示是否可建立好友关系（存在性/已是好友等）。

请求字段（UserFriendCheckRequestVO）

响应字段（UserFriendCheckResponseVO）

JSON 示例

请求（UserFriendCheckRequestVO）：

{
  "userId1": 0,
  "userId2": 0
}

响应（UserFriendCheckResponseVO）：

{
  "returnCode": 1
}

服务器实现要点

• 简单实现恒返回 1

GetTransferFriendApi — 好友数据列表

好友数据列表（transferFriendList：同玩玩家、友情点、收藏标记）。当前版本客户端没有任何调用点（0 处），属于保留接口。

请求字段（TransferFriendRequestVO）

响应字段（TransferFriendResponseVO）

JSON 示例

请求（TransferFriendRequestVO）：

{
  "userId": 100000000000000001
}

响应（TransferFriendResponseVO）：

{
  "userId": 100000000000000001,
  "transferFriendList": [
    {
      "playUserId": 0,
      "playUserName": "",
      "playDate": "",
      "friendPoint": 0,
      "isFavorite": false
    }
  ]
}

服务器实现要点

• 返回空列表即可

玩家数据上传

UploadUserPlaylogApi — 上传游玩记录

单曲游玩记录上传。每首曲目结算后立即调用（PlaylogULProcess/StateUpload），请求体 UserPlaylog 为 110 字段的全量记录：判定明细（TAP/HOLD/SLIDE/TOUCH/BREAK × 五档）、FAST/LATE、达成率、DXScore、前后 Rating、同行角色、对战信息等。旧版本该数据并入 UpsertUserAll，现已拆分独立逐曲上传。

请求字段（UserPlaylogRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（UserPlaylogRequestVO）：

{
  "userId": 100000000000000001,
  "userPlaylog": {
    "userId": 100000000000000001,
    "orderId": 0,
    "playlogId": 1,
    "version": 0,
    "placeId": 0,
    "placeName": "",
    "loginDate": 0,
    "playDate": "",
    "userPlayDate": "",
    "type": 0,
    "musicId": 11820,
    "level": 3,
    "trackNo": 0,
    "vsMode": 0,
    "vsUserName": "",
    "vsStatus": 0,
    "vsUserRating": 0,
    "vsUserAchievement": 0,
    "vsUserGradeRank": 0,
    "vsRank": 0,
    "playerNum": 0,
    "playedUserId1": 0,
    "playedUserName1": "",
    "playedMusicLevel1": 0,
    "playedUserId2": 0,
    "playedUserName2": "",
    "playedMusicLevel2": 0,
    "playedUserId3": 0,
    "playedUserName3": "",
    "playedMusicLevel3": 0,
    "characterId1": 0,
    "characterLevel1": 0,
    "characterAwakening1": 0,
    "characterId2": 0,
    "characterLevel2": 0,
    "characterAwakening2": 0,
    "characterId3": 0,
    "characterLevel3": 0,
    "characterAwakening3": 0,
    "characterId4": 0,
    "characterLevel4": 0,
    "characterAwakening4": 0,
    "characterId5": 0,
    "characterLevel5": 0,
    "characterAwakening5": 0,
    "achievement": 0,
    "deluxscore": 0,
    "scoreRank": 0,
    "maxCombo": 0,
    "totalCombo": 0,
    "maxSync": 0,
    "totalSync": 0,
    "tapCriticalPerfect": 0,
    "tapPerfect": 0,
    "tapGreat": 0,
    "tapGood": 0,
    "tapMiss": 0,
    "holdCriticalPerfect": 0,
    "holdPerfect": 0,
    "holdGreat": 0,
    "holdGood": 0,
    "holdMiss": 0,
    "slideCriticalPerfect": 0,
    "slidePerfect": 0,
    "slideGreat": 0,
    "slideGood": 0,
    "slideMiss": 0,
    "touchCriticalPerfect": 0,
    "touchPerfect": 0,
    "touchGreat": 0,
    "touchGood": 0,
    "touchMiss": 0,
    "breakCriticalPerfect": 0,
    "breakPerfect": 0,
    "breakGreat": 0,
    "breakGood": 0,
    "breakMiss": 0,
    "isTap": false,
    "isHold": false,
    "isSlide": false,
    "isTouch": false,
    "isBreak": false,
    "isCriticalDisp": false,
    "isFastLateDisp": false,
    "fastCount": 0,
    "lateCount": 0,
    "isAchieveNewRecord": false,
    "isDeluxscoreNewRecord": false,
    "comboStatus": 0,
    "syncStatus": 0,
    "isClear": false,
    "beforeRating": 0,
    "afterRating": 0,
    "beforeGrade": 0,
    "afterGrade": 0,
    "afterGradeRank": 0,
    "beforeDeluxRating": 0,
    "afterDeluxRating": 0,
    "isPlayTutorial": false,
    "isEventMode": false,
    "isFreedomMode": false,
    "playMode": 0,
    "isNewFree": false,
    "trialPlayAchievement": 0,
    "extNum1": 0,
    "extNum2": 0,
    "extNum4": 0,
    "extBool1": false,
    "extBool2": false,
    "extBool3": false
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 每首曲子一条，按 playlogId+orderId 排序入库
• 是排行榜、统计、"游玩条件解锁"类规则的数据源
• 注意与 UpsertUserAll.userPlaylogList 内容一致（一次保存会重复携带）

UpsertUserAllApi — 全量差量上传（核心）

整个协议的核心落库接口。数据保存画面调用一次，把本局产生的全部状态变化以差量方式提交：约 20 个列表（解锁 userItemList、舞里程 userMapList、角色、成绩、活动、万花筒……）+ 各自的 isNew 位图（"1"=新增，"0"=更新）。服务器按 1.7 节的对照表合并即可完整复刻官方存档语义。解锁体系（乐曲/紫白谱/钥匙）的最终持久化都发生在这里。

请求字段（UserAllRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（UserAllRequestVO）：

{
  "userId": 100000000000000001,
  "playlogId": 1,
  "isEventMode": false,
  "isFreePlay": false,
  "loginDateTime": 0,
  "userPlaylogList": [
    {
      "userId": 100000000000000001,
      "orderId": 0,
      "playlogId": 1,
      "version": 0,
      "placeId": 0,
      "placeName": "",
      "loginDate": 0,
      "playDate": "",
      "userPlayDate": "",
      "type": 0,
      "musicId": 11820,
      "level": 3,
      "trackNo": 0,
      "vsMode": 0,
      "vsUserName": "",
      "vsStatus": 0,
      "vsUserRating": 0,
      "vsUserAchievement": 0,
      "vsUserGradeRank": 0,
      "vsRank": 0,
      "playerNum": 0,
      "playedUserId1": 0,
      "playedUserName1": "",
      "playedMusicLevel1": 0,
      "playedUserId2": 0,
      "playedUserName2": "",
      "playedMusicLevel2": 0,
      "playedUserId3": 0,
      "playedUserName3": "",
      "playedMusicLevel3": 0,
      "characterId1": 0,
      "characterLevel1": 0,
      "characterAwakening1": 0,
      "characterId2": 0,
      "characterLevel2": 0,
      "characterAwakening2": 0,
      "characterId3": 0,
      "characterLevel3": 0,
      "characterAwakening3": 0,
      "characterId4": 0,
      "characterLevel4": 0,
      "characterAwakening4": 0,
      "characterId5": 0,
      "characterLevel5": 0,
      "characterAwakening5": 0,
      "achievement": 0,
      "deluxscore": 0,
      "scoreRank": 0,
      "maxCombo": 0,
      "totalCombo": 0,
      "maxSync": 0,
      "totalSync": 0,
      "tapCriticalPerfect": 0,
      "tapPerfect": 0,
      "tapGreat": 0,
      "tapGood": 0,
      "tapMiss": 0,
      "holdCriticalPerfect": 0,
      "holdPerfect": 0,
      "holdGreat": 0,
      "holdGood": 0,
      "holdMiss": 0,
      "slideCriticalPerfect": 0,
      "slidePerfect": 0,
      "slideGreat": 0,
      "slideGood": 0,
      "slideMiss": 0,
      "touchCriticalPerfect": 0,
      "touchPerfect": 0,
      "touchGreat": 0,
      "touchGood": 0,
      "touchMiss": 0,
      "breakCriticalPerfect": 0,
      "breakPerfect": 0,
      "breakGreat": 0,
      "breakGood": 0,
      "breakMiss": 0,
      "isTap": false,
      "isHold": false,
      "isSlide": false,
      "isTouch": false,
      "isBreak": false,
      "isCriticalDisp": false,
      "isFastLateDisp": false,
      "fastCount": 0,
      "lateCount": 0,
      "isAchieveNewRecord": false,
      "isDeluxscoreNewRecord": false,
      "comboStatus": 0,
      "syncStatus": 0,
      "isClear": false,
      "beforeRating": 0,
      "afterRating": 0,
      "beforeGrade": 0,
      "afterGrade": 0,
      "afterGradeRank": 0,
      "beforeDeluxRating": 0,
      "afterDeluxRating": 0,
      "isPlayTutorial": false,
      "isEventMode": false,
      "isFreedomMode": false,
      "playMode": 0,
      "isNewFree": false,
      "trialPlayAchievement": 0,
      "extNum1": 0,
      "extNum2": 0,
      "extNum4": 0,
      "extBool1": false,
      "extBool2": false,
      "extBool3": false
    }
  ],
  "upsertUserAll": {
    "userData": [
      {
        "accessCode": "604012345678901234",
        "userName": "玩家昵称",
        "isNetMember": 0,
        "point": 0,
        "totalPoint": 0,
        "iconId": 0,
        "plateId": 0,
        "titleId": 0,
        "partnerId": 0,
        "frameId": 0,
        "selectMapId": 0,
        "totalAwake": 0,
        "gradeRating": 0,
        "musicRating": 0,
        "playerRating": 0,
        "highestRating": 0,
        "gradeRank": 0,
        "classRank": 0,
        "courseRank": 0,
        "charaSlot": [],
        "charaLockSlot": [],
        "contentBit": 0,
        "playCount": 0,
        "currentPlayCount": 0,
        "renameCredit": 0,
        "mapStock": 0,
        "eventWatchedDate": "",
        "lastGameId": "",
        "lastRomVersion": "",
        "lastDataVersion": "",
        "lastLoginDate": "",
        "lastPlayDate": "",
        "lastPlayCredit": 0,
        "lastPlayMode": 0,
        "lastPlaceId": 0,
        "lastPlaceName": "",
        "lastAllNetId": 0,
        "lastRegionId": 0,
        "lastRegionName": "",
        "lastClientId": "",
        "lastCountryCode": "",
        "lastSelectEMoney": 0,
        "lastSelectTicket": 0,
        "lastSelectCourse": 0,
        "lastCountCourse": 0,
        "firstGameId": "",
        "firstRomVersion": "",
        "firstDataVersion": "",
        "firstPlayDate": "",
        "compatibleCmVersion": "",
        "dailyBonusDate": "",
        "dailyCourseBonusDate": "",
        "lastPairLoginDate": "",
        "lastTrialPlayDate": "",
        "playVsCount": 0,
        "playSyncCount": 0,
        "winCount": 0,
        "helpCount": 0,
        "comboCount": 0,
        "totalDeluxscore": 0,
        "totalBasicDeluxscore": 0,
        "totalAdvancedDeluxscore": 0,
        "totalExpertDeluxscore": 0,
        "totalMasterDeluxscore": 0,
        "totalReMasterDeluxscore": 0,
        "totalSync": 0,
        "totalBasicSync": 0,
        "totalAdvancedSync": 0,
        "totalExpertSync": 0,
        "totalMasterSync": 0,
        "totalReMasterSync": 0,
        "totalAchievement": 0,
        "totalBasicAchievement": 0,
        "totalAdvancedAchievement": 0,
        "totalExpertAchievement": 0,
        "totalMasterAchievement": 0,
        "totalReMasterAchievement": 0,
        "playerOldRating": 0,
        "playerNewRating": 0,
        "banState": 0,
        "friendRegistSkip": 0,
        "dateTime": 0
      }
    ],
    "userExtend": [
      {
        "selectMusicId": 0,
        "selectDifficultyId": 0,
        "categoryIndex": 0,
        "musicIndex": 0,
        "extraFlag": 0,
        "selectScoreType": 0,
        "extendContentBit": 0,
        "isPhotoAgree": false,
        "isGotoCodeRead": false,
        "selectResultDetails": false,
        "selectResultScoreViewType": 0,
        "sortCategorySetting": "/*SortTabID*/ 0",
        "sortMusicSetting": "/*SortMusicID*/ 0",
        "playStatusSetting": "/*PlaystatusTabID*/ 0",
        "selectedCardList": [],
        "encountMapNpcList": []
      }
    ],
    "userOption": [
      {
        "optionKind": "/*OptionKindID*/ 0",
        "noteSpeed": "/*OptionNotespeedID*/ 0",
        "slideSpeed": "/*OptionSlidespeedID*/ 0",
        "touchSpeed": "/*OptionTouchspeedID*/ 0",
        "tapDesign": "/*OptionGametapID*/ 0",
        "holdDesign": "/*OptionGameholdID*/ 0",
        "slideDesign": "/*OptionGameslideID*/ 0",
        "starType": "/*OptionStartypeID*/ 0",
        "outlineDesign": "/*OptionGameoutlineID*/ 0",
        "noteSize": "/*OptionNotesizeID*/ 0",
        "slideSize": "/*OptionSlidesizeID*/ 0",
        "touchSize": "/*OptionTouchsizeID*/ 0",
        "starRotate": "/*OptionStarrotateID*/ 0",
        "dispCenter": "/*OptionCenterdisplayID*/ 0",
        "outFrameType": "/*OptionOutframedisplayID*/ 0",
        "dispChain": "/*OptionDispchainID*/ 0",
        "dispRate": "/*OptionDisprateID*/ 0",
        "dispBar": "/*OptionDispbarlineID*/ 0",
        "touchEffect": "/*OptionToucheffectID*/ 0",
        "submonitorAnimation": "/*OptionSubmonitorID*/ 0",
        "submonitorAchive": "/*OptionSubmonAchiveID*/ 0",
        "submonitorAppeal": "/*OptionAppealID*/ 0",
        "matching": "/*OptionMatchingID*/ 0",
        "trackSkip": "/*OptionTrackskipID*/ 0",
        "brightness": "/*OptionMoviebrightnessID*/ 0",
        "mirrorMode": "/*OptionMirrorID*/ 0",
        "dispJudge": "/*OptionDispjudgeID*/ 0",
        "dispJudgePos": "/*OptionDispjudgeposID*/ 0",
        "dispJudgeTouchPos": "/*OptionDispjudgetouchposID*/ 0",
        "adjustTiming": "/*OptionJudgetimingID*/ 0",
        "judgeTiming": "/*OptionJudgetimingID*/ 0",
        "ansVolume": "/*OptionVolumeAnswerSoundID*/ 0",
        "tapHoldVolume": "/*OptionVolumeID*/ 0",
        "criticalSe": "/*OptionCriticalID*/ 0",
        "tapSe": "/*OptionTapSuccessSeID*/ 0",
        "breakSe": "/*OptionBreakseID*/ 0",
        "breakVolume": "/*OptionVolumeID*/ 0",
        "exSe": "/*OptionExseID*/ 0",
        "exVolume": "/*OptionVolumeID*/ 0",
        "slideSe": "/*OptionSlideseID*/ 0",
        "slideVolume": "/*OptionVolumeID*/ 0",
        "breakSlideVolume": "/*OptionVolumeID*/ 0",
        "touchVolume": "/*OptionVolumeID*/ 0",
        "touchHoldVolume": "/*OptionVolumeID*/ 0",
        "damageSeVolume": "/*OptionVolumeID*/ 0",
        "headPhoneVolume": "/*OptionHeadphonevolumeID*/ 0",
        "sortTab": "/*SortTabID*/ 0",
        "sortMusic": "/*SortMusicID*/ 0"
      }
    ],
    "userCharacterList": [
      {
        "characterId": 101,
        "level": 3,
        "awakening": 0,
        "useCount": 0
      }
    ],
    "userGhost": [
      {
        "name": "",
        "iconId": 0,
        "plateId": 0,
        "titleId": 0,
        "rate": 0,
        "udemaeRate": 0,
        "courseRank": 0,
        "classRank": 0,
        "classValue": 0,
        "playDatetime": "",
        "shopId": 0,
        "regionCode": 0,
        "typeId": "/*MusicDifficultyID*/ 0",
        "musicId": 11820,
        "difficulty": 0,
        "version": 0,
        "resultBitList": [],
        "resultNum": 0,
        "achievement": 0
      }
    ],
    "userMapList": [
      {
        "mapId": 1,
        "distance": 12345,
        "isLock": false,
        "isClear": false,
        "isComplete": false,
        "unlockFlag": 0
      }
    ],
    "userLoginBonusList": [
      {
        "bonusId": 0,
        "point": 0,
        "isCurrent": false,
        "isComplete": false
      }
    ],
    "userRatingList": [
      {
        "rating": 0,
        "ratingList": [],
        "newRatingList": [],
        "nextRatingList": [],
        "nextNewRatingList": [],
        "udemae": {}
      }
    ],
    "userItemList": [
      {
        "itemKind": 5,
        "itemId": 5011820,
        "stock": 0,
        "isValid": false
      }
    ],
    "userMusicDetailList": [
      {
        "musicId": 11820,
        "level": "/*MusicDifficultyID*/ 0",
        "playCount": 0,
        "achievement": 0,
        "comboStatus": "/*PlayComboflagID*/ 0",
        "syncStatus": "/*PlaySyncflagID*/ 0",
        "deluxscoreMax": 0,
        "scoreRank": "/*MusicClearrankID*/ 0",
        "extNum1": 0
      }
    ],
    "userCourseList": [
      {
        "courseId": 0,
        "isLastClear": false,
        "totalRestlife": 0,
        "totalAchievement": 0,
        "totalDeluxscore": 0,
        "playCount": 0,
        "clearDate": "",
        "lastPlayDate": "",
        "bestAchievement": 0,
        "bestAchievementDate": "",
        "bestDeluxscore": 0,
        "bestDeluxscoreDate": ""
      }
    ],
    "userFriendSeasonRankingList": [
      {
        "seasonId": 0,
        "point": 0,
        "rank": 0,
        "rewardGet": false,
        "userName": "玩家昵称",
        "recordDate": ""
      }
    ],
    "userChargeList": [
      {
        "chargeId": 0,
        "stock": 0,
        "purchaseDate": "",
        "validDate": ""
      }
    ],
    "userFavoriteList": [
      {
        "itemKind": 5,
        "itemIdList": []
      }
    ],
    "userActivityList": [
      {
        "playList": [],
        "musicList": []
      }
    ],
    "userMissionDataList": [
      {
        "type": 0,
        "difficulty": 0,
        "targetGenreId": 0,
        "targetGenreTableId": 0,
        "conditionGenreId": 0,
        "conditionGenreTableId": 0,
        "clearFlag": false
      }
    ],
    "userWeeklyData": {
      "lastLoginWeek": "",
      "beforeLoginWeek": "",
      "friendBonusFlag": false
    },
    "userGamePlaylogList": [
      {
        "playlogId": 1,
        "version": "",
        "playDate": "",
        "playMode": 0,
        "useTicketId": 0,
        "playCredit": 0,
        "playTrack": 0,
        "clientId": "",
        "isPlayTutorial": false,
        "isEventMode": false,
        "isNewFree": false,
        "playCount": 0,
        "playSpecial": 0,
        "playOtherUserId": 0
      }
    ],
    "user2pPlaylog": {
      "userId1": 0,
      "userId2": 0,
      "userName1": "",
      "userName2": "",
      "regionId": 0,
      "placeId": 0
    },
    "userIntimateList": [
      {
        "partnerId": 0,
        "intimateLevel": 0,
        "intimateCountRewarded": 0
      }
    ],
    "userShopItemStockList": [
      {
        "shopItemId": 0,
        "tradeCount": 0
      }
    ],
    "userGetPointList": [
      {
        "getKind": 0,
        "point": 0
      }
    ],
    "userTradeItemList": [
      {
        "shopItemId": 0,
        "point": 0,
        "tradeCount": 0
      }
    ],
    "userFavoritemusicList": [
      {
        "orderId": 0,
        "id": 0
      }
    ],
    "userKaleidxScopeList": [
      {
        "gateId": 0,
        "isGateFound": false,
        "isKeyFound": false,
        "isClear": false,
        "totalRestLife": 0,
        "totalAchievement": 0,
        "totalDeluxscore": 0,
        "bestAchievement": 0,
        "bestDeluxscore": 0,
        "bestAchievementDate": "",
        "bestDeluxscoreDate": "",
        "playCount": 0,
        "clearDate": "",
        "lastPlayDate": "",
        "isInfoWatched": false
      }
    ],
    "isNewCharacterList": "10",
    "isNewMapList": "10",
    "isNewLoginBonusList": "10",
    "isNewItemList": "10",
    "isNewMusicDetailList": "10",
    "isNewCourseList": "10",
    "isNewFavoriteList": "10",
    "isNewFriendSeasonRankingList": "10",
    "isNewUserIntimateList": "10",
    "isNewFavoritemusicList": "10",
    "isNewKaleidxScopeList": "10"
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 严格按 isNew 位图 INSERT/UPDATE，位图字符串与数组按位对齐
• userItemList 的 kind=5 条目落库后，下次 GetUserItemApi 要能原样返回
• userMapList 合并时注意 distance 取较大值（断线重传保护）
• 返回 returnCode=1；失败会导致客户端走保存错误流程

UploadUserPortraitApi — 上传面部肖像

面部肖像上传：拍头像功能开启时（TakeFaceIcon），把 {userId}.jpg 以 Base64 分片（divNumber/divLength）放入 UserPortrait 上传，仍走 AES 加密 JSON 通道。

请求字段（UploadUserPortraitRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（UploadUserPortraitRequestVO）：

{
  "userPortrait": {
    "userId": 100000000000000001,
    "divNumber": 0,
    "divLength": 0,
    "divData": "",
    "placeId": 0,
    "clientId": "",
    "uploadDate": "",
    "fileName": ""
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 按 divNumber 拼接分片后 Base64 解码存文件
• 功能未开启时该请求不会发出

UploadUserPhotoApi — 上传游玩照片

游玩照片上传：结算时拍摄的照片（JPEG Base64 分片）+ 关联的 playlogId/trackNo。

请求字段（UserPhotoRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（UserPhotoRequestVO）：

{
  "userPhoto": {
    "orderId": 0,
    "userId": 100000000000000001,
    "divNumber": 0,
    "divLength": 0,
    "divData": "",
    "placeId": 0,
    "clientId": "",
    "uploadDate": "",
    "playlogId": 1,
    "trackNo": 0
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 与 Portrait 同样的分片拼接方式
• GameSetting.uploadPhotoDisable=true 时不会发出

UpsertUserChargelogApi — 上传扣费记录

扣费记录上传：玩家使用收费项（门票/通行证）时由 TicketManager 调用，请求携带 UserChargelog（扣费流水：chargeId/price/时间/机器）与扣费后的 UserCharge 余量。

请求字段（UserChargelogRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（UserChargelogRequestVO）：

{
  "userId": 100000000000000001,
  "userChargelog": {
    "chargeId": 0,
    "price": 0,
    "purchaseDate": "",
    "playCount": 0,
    "playerRating": 0,
    "placeId": 0,
    "regionId": 0,
    "clientId": ""
  },
  "userCharge": {
    "chargeId": 0,
    "stock": 0,
    "purchaseDate": "",
    "validDate": ""
  },
  "loginDateTime": 0
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 同时更新 UserCharge.stock 与插入流水记录

UserFriendRegistApi — 注册好友

好友注册：请求带双方 userId（userId1=发起者，userId2=目标），返回两个 returnCode（各自侧的结果）。

请求字段（UserFriendRegistRequestVO）

响应字段（UserFriendRegistResponseVO）

JSON 示例

请求（UserFriendRegistRequestVO）：

{
  "userId1": 0,
  "userId2": 0
}

响应（UserFriendRegistResponseVO）：

{
  "returnCode1": 0,
  "returnCode2": 0
}

服务器实现要点

• 校验目标存在性后写好友关系表

机器遥测上传（与玩家数据无关）

UpsertClientPlayTimeApi — 运行时长上报

机器运行时长上报（ClientPlayTime 对象），用于运营统计，与玩家数据完全无关。

请求字段（ClientPlayTimeRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（ClientPlayTimeRequestVO）：

{
  "clientPlayTime": {
    "placeId": 0,
    "clientId": "",
    "updateDate": "",
    "playTimeTrack3": 0,
    "playTimeTrack4": 0,
    "playTime2P": 0,
    "playTrack3Num": 0,
    "playTrack4Num": 0,
    "play2PNum": 0,
    "regionId": 0
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 收到即返回 returnCode=1，可忽略内容

UpsertClientBookkeepingApi — 记账上报

记账上报（ClientBookkeeping：投入金额/计数等经营统计）。

请求字段（ClientBookkeepingRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（ClientBookkeepingRequestVO）：

{
  "clientBookkeeping": {
    "placeId": 0,
    "clientId": "",
    "updateDate": "",
    "creditSetting0": 0,
    "creditSetting1": 0,
    "creditSetting2": 0,
    "credits1P": 0,
    "credits2P": 0,
    "creditsFreedom": 0,
    "creditsTicket": 0,
    "creditCoin": 0,
    "creditService": 0,
    "creditEmoney": 0,
    "timeTotal": 0,
    "timeTotalPlay": 0,
    "timeLongest1P": 0,
    "timeShortest1P": 0,
    "timeLongest2P": 0,
    "timeShortest2P": 0,
    "timeLongestFreedom": 0,
    "timeShortestFreedom": 0,
    "newFreeUserNum": 0,
    "tutorialPlay": 0,
    "play1PNum": 0,
    "play2PNum": 0,
    "playFreedomNum": 0,
    "aimeLoginNum": 0,
    "guestLoginNum": 0,
    "regionId": 0,
    "playCount": 0,
    "coinToCredit": 0,
    "errorNum": [
      0
    ],
    "error2Num": [
      0
    ],
    "pingResult": [
      "/*BackupNetworkInformationRecord.PingResult*/ 0"
    ]
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 同上，空落库

UpsertClientSettingApi — 客户端设置上报

客户端设置快照上报（ClientSetting）。

请求字段（ClientSettingRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（ClientSettingRequestVO）：

{
  "clientSetting": {
    "placeId": 0,
    "clientId": "",
    "placeName": "",
    "regionId": 0,
    "regionName": "",
    "bordId": "",
    "romVersion": 0,
    "isDevelop": false,
    "isAou": false
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 同上

UpsertClientTestmodeApi — TestMode 上报

测试菜单（TestMode）配置快照上报。

请求字段（ClientTestmodeRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（ClientTestmodeRequestVO）：

{
  "clientTestmode": {
    "placeId": 0,
    "clientId": "",
    "trackSingle": 0,
    "trackMulti": 0,
    "trackEvent": 0,
    "totalMachine": 0,
    "satelliteId": 0,
    "cameraPosition": 0
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 同上

UpsertClientUploadApi — 错误/日志上报

客户端错误/诊断信息上报（ClientUpload），对应机器本地 UploadData 目录的收集内容。

请求字段（ClientUploadRequestVO）

响应字段（UpsertResponseVO）

JSON 示例

请求（ClientUploadRequestVO）：

{
  "clientUpload": {
    "orderId": 0,
    "divNumber": 0,
    "divLength": 0,
    "divData": "",
    "placeId": 0,
    "clientId": "",
    "uploadDate": "",
    "fileName": ""
  }
}

响应（UpsertResponseVO）：

{
  "returnCode": 1,
  "apiName": ""
}

服务器实现要点

• 同上

附录 A：数据类（VO）参考

以下为全部非请求/响应包装的数据类（包装类已在各 API 小节给出示例）。

ClientBookkeeping

{
  "placeId": 0,
  "clientId": "",
  "updateDate": "",
  "creditSetting0": 0,
  "creditSetting1": 0,
  "creditSetting2": 0,
  "credits1P": 0,
  "credits2P": 0,
  "creditsFreedom": 0,
  "creditsTicket": 0,
  "creditCoin": 0,
  "creditService": 0,
  "creditEmoney": 0,
  "timeTotal": 0,
  "timeTotalPlay": 0,
  "timeLongest1P": 0,
  "timeShortest1P": 0,
  "timeLongest2P": 0,
  "timeShortest2P": 0,
  "timeLongestFreedom": 0,
  "timeShortestFreedom": 0,
  "newFreeUserNum": 0,
  "tutorialPlay": 0,
  "play1PNum": 0,
  "play2PNum": 0,
  "playFreedomNum": 0,
  "aimeLoginNum": 0,
  "guestLoginNum": 0,
  "regionId": 0,
  "playCount": 0,
  "coinToCredit": 0,
  "errorNum": [
    0
  ],
  "error2Num": [
    0
  ],
  "pingResult": [
    "/*BackupNetworkInformationRecord.PingResult*/ 0"
  ]
}

ClientPlayTime

{
  "placeId": 0,
  "clientId": "",
  "updateDate": "",
  "playTimeTrack3": 0,
  "playTimeTrack4": 0,
  "playTime2P": 0,
  "playTrack3Num": 0,
  "playTrack4Num": 0,
  "play2PNum": 0,
  "regionId": 0
}

ClientSetting

{
  "placeId": 0,
  "clientId": "",
  "placeName": "",
  "regionId": 0,
  "regionName": "",
  "bordId": "",
  "romVersion": 0,
  "isDevelop": false,
  "isAou": false
}

ClientTestmode

{
  "placeId": 0,
  "clientId": "",
  "trackSingle": 0,
  "trackMulti": 0,
  "trackEvent": 0,
  "totalMachine": 0,
  "satelliteId": 0,
  "cameraPosition": 0
}

ClientUpload

{
  "orderId": 0,
  "divNumber": 0,
  "divLength": 0,
  "divData": "",
  "placeId": 0,
  "clientId": "",
  "uploadDate": "",
  "fileName": ""
}

DelayLog

{
  "dlRequests": 0,
  "dlSize": 0,
  "dlRetry": 0,
  "loginMsec": 0,
  "saveMsec": 0,
  "reductionMusic": 0,
  "reductionItem": 0
}

GameCharge

{
  "orderId": 0,
  "chargeId": 0,
  "price": 0,
  "startDate": "",
  "endDate": ""
}

GameEvent

{
  "type": 0,
  "id": 0,
  "startDate": "",
  "endDate": ""
}

GameKaleidxScope

{
  "gateId": 0,
  "phaseId": 0
}

GameRanking

{
  "id": 0,
  "point": 0,
  "userName": "玩家昵称"
}

GameSetting

{
  "isMaintenance": false,
  "requestInterval": 0,
  "rebootStartTime": "",
  "rebootEndTime": "",
  "movieUploadLimit": 0,
  "movieStatus": 0,
  "movieServerUri": "",
  "deliverServerUri": "",
  "oldServerUri": "",
  "usbDlServerUri": "",
  "rebootInterval": 0,
  "pingDisable": false,
  "packetTimeout": 0,
  "packetTimeoutLong": 0,
  "packetRetryCount": 0,
  "userDataDlErrTimeout": 0,
  "userDataDlErrRetryCount": 0,
  "userDataDlErrSamePacketRetryCount": 0,
  "userDataUpSkipTimeout": 0,
  "userDataUpSkipRetryCount": 0,
  "iconPhotoDisable": false,
  "uploadPhotoDisable": false,
  "nameEntryDisable": false,
  "packetRecreateCount": 0,
  "collectDelayInfoDisable": false
}

GameTournamentInfo

{
  "tournamentId": 0,
  "tournamentName": "",
  "rankingKind": 0,
  "scoreType": 0,
  "noticeStartDate": "",
  "noticeEndDate": "",
  "startDate": "",
  "endDate": "",
  "entryStartDate": "",
  "entryEndDate": "",
  "gameTournamentMusicList": [
    {
      "tournamentId": 0,
      "musicId": 11820,
      "level": 3,
      "isFirstLock": false
    }
  ]
}

GameTournamentMusic

{
  "tournamentId": 0,
  "musicId": 11820,
  "level": 3,
  "isFirstLock": false
}

GameWeeklyData

{
  "missionCategory": 0,
  "updateDate": "",
  "beforeDate": ""
}

MapEncountNpc

{
  "npcId": 0,
  "musicId": 11820
}

MusicScore

{
  "musicId": 11820,
  "level": 3,
  "type": 0,
  "scoreData": ""
}

RequestAPI

{
  "count": 0,
  "size": 0,
  "msec": 0,
  "retry": 0
}

TransferFriend

{
  "playUserId": 0,
  "playUserName": "",
  "playDate": "",
  "friendPoint": 0,
  "isFavorite": false
}

TransferRequestVO

{
  "userId": 100000000000000001,
  "userData": [
    {
      "accessCode": "604012345678901234",
      "userName": "玩家昵称",
      "isNetMember": 0,
      "point": 0,
      "totalPoint": 0,
      "iconId": 0,
      "plateId": 0,
      "titleId": 0,
      "partnerId": 0,
      "frameId": 0,
      "selectMapId": 0,
      "totalAwake": 0,
      "gradeRating": 0,
      "musicRating": 0,
      "playerRating": 0,
      "highestRating": 0,
      "gradeRank": 0,
      "classRank": 0,
      "courseRank": 0,
      "charaSlot": [],
      "charaLockSlot": [],
      "contentBit": 0,
      "playCount": 0,
      "currentPlayCount": 0,
      "renameCredit": 0,
      "mapStock": 0,
      "eventWatchedDate": "",
      "lastGameId": "",
      "lastRomVersion": "",
      "lastDataVersion": "",
      "lastLoginDate": "",
      "lastPlayDate": "",
      "lastPlayCredit": 0,
      "lastPlayMode": 0,
      "lastPlaceId": 0,
      "lastPlaceName": "",
      "lastAllNetId": 0,
      "lastRegionId": 0,
      "lastRegionName": "",
      "lastClientId": "",
      "lastCountryCode": "",
      "lastSelectEMoney": 0,
      "lastSelectTicket": 0,
      "lastSelectCourse": 0,
      "lastCountCourse": 0,
      "firstGameId": "",
      "firstRomVersion": "",
      "firstDataVersion": "",
      "firstPlayDate": "",
      "compatibleCmVersion": "",
      "dailyBonusDate": "",
      "dailyCourseBonusDate": "",
      "lastPairLoginDate": "",
      "lastTrialPlayDate": "",
      "playVsCount": 0,
      "playSyncCount": 0,
      "winCount": 0,
      "helpCount": 0,
      "comboCount": 0,
      "totalDeluxscore": 0,
      "totalBasicDeluxscore": 0,
      "totalAdvancedDeluxscore": 0,
      "totalExpertDeluxscore": 0,
      "totalMasterDeluxscore": 0,
      "totalReMasterDeluxscore": 0,
      "totalSync": 0,
      "totalBasicSync": 0,
      "totalAdvancedSync": 0,
      "totalExpertSync": 0,
      "totalMasterSync": 0,
      "totalReMasterSync": 0,
      "totalAchievement": 0,
      "totalBasicAchievement": 0,
      "totalAdvancedAchievement": 0,
      "totalExpertAchievement": 0,
      "totalMasterAchievement": 0,
      "totalReMasterAchievement": 0,
      "playerOldRating": 0,
      "playerNewRating": 0,
      "banState": 0,
      "friendRegistSkip": 0,
      "dateTime": 0
    }
  ],
  "userMusicDetailList": [
    {
      "musicId": 11820,
      "level": "/*MusicDifficultyID*/ 0",
      "playCount": 0,
      "achievement": 0,
      "comboStatus": "/*PlayComboflagID*/ 0",
      "syncStatus": "/*PlaySyncflagID*/ 0",
      "deluxscoreMax": 0,
      "scoreRank": "/*MusicClearrankID*/ 0",
      "extNum1": 0
    }
  ],
  "isNewMusicDetailList": "10"
}

User2pPlaylog