@easecation/ecapi-sdk 0.1.3 → 3.0.4

package/API_REFERENCE.md

@@ -0,0 +1,313 @@
+# @easecation/ecapi-sdk API Reference
+
+自动从 `openapi.json` 生成。OpenAPI 是路径、参数、权限与文档的唯一事实源。
+
+## AdminApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `deleteMail` | 删除邮件 | `mail` | `DELETE` | `/admin/mail/{mailId}` | `path.mailId` | - |
+| `getOperationLogs` | 分页查询管理员操作日志 | `game_admin` | `GET` | `/admin/operations` | - | `query.startTime`, `query.endTime`, `query.sourceEcid`, `query.targetEcid`, `query.skipWac`, `query.sortOrder`, `query.current`, `query.pageSize`, `query.enableBanHistoryParse` |
+| `getOperationStatistics` | 查询操作日志统计 | `game_admin` | `GET` | `/admin/operations/statistic` | `query.startTime`, `query.endTime` | - |
+| `getOverwatchCase` | 分页查询 Overwatch 案件 | `player_info` | `GET` | `/admin/overwatch` | - | `query.recordId`, `query.current`, `query.pageSize` |
+| `getPrismDeviceBanLog` | 分页查询设备封禁日志 | `punish` | `GET` | `/admin/prism-device-ban-log` | - | `query.deviceId`, `query.current`, `query.pageSize` |
+| `prismDeviceBan` | 设置设备封禁状态 | `punish` | `POST` | `/admin/prism-device-ban` | `body` | - |
+| `sendMail` | 发送邮件 | `mail` | `POST` | `/admin/mail` | `body` | - |
+| `upsertOverwatchCase` | 添加 Overwatch 案件 | `punish` | `POST` | `/admin/overwatch` | `body` | - |
+
+## AuditApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getAdminLogs` | 查询管理员操作日志 | `audit` | `GET` | `/audits/admin` | - | `query.current`, `query.pageSize`, `query.startTime`, `query.endTime`, `query.sortOrder`, `query.operatorId`, `query.operationStatus`, `query.operationType`, `query.highRisk` |
+| `getAuthLogs` | 查询用户认证日志 | `audit` | `GET` | `/audits/auth` | - | `query.current`, `query.pageSize`, `query.startTime`, `query.endTime`, `query.sortOrder`, `query.operatorId`, `query.operationStatus`, `query.clientIp`, `query.httpMethod`, `query.authMethod` |
+| `getConfigLogs` | 查询配置管理日志 | `audit` | `GET` | `/audits/config` | - | `query.current`, `query.pageSize`, `query.startTime`, `query.endTime`, `query.sortOrder`, `query.operatorId`, `query.operationStatus`, `query.configType`, `query.operationType` |
+| `getPermissionLogs` | 查询权限管理日志 | `audit` | `GET` | `/audits/permission` | - | `query.current`, `query.pageSize`, `query.startTime`, `query.endTime`, `query.sortOrder`, `query.operatorId`, `query.operationStatus`, `query.targetEcid`, `query.permissionType`, `query.operationType` |
+| `getPlayerLogs` | 查询玩家操作日志 | `audit` | `GET` | `/audits/player` | - | `query.current`, `query.pageSize`, `query.startTime`, `query.endTime`, `query.sortOrder`, `query.operatorId`, `query.operationStatus`, `query.targetEcid`, `query.operationType`, `query.httpMethod` |
+| `getPunishmentLogs` | 查询处罚操作日志 | `audit` | `GET` | `/audits/punishment` | - | `query.current`, `query.pageSize`, `query.startTime`, `query.endTime`, `query.sortOrder`, `query.operatorId`, `query.operationStatus`, `query.targetEcid`, `query.banType`, `query.durationRange` |
+
+## AuthApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getOpenId` | 获取用户 OpenId | `AUTHENTICATED` | `GET` | `/auth/open-id` | - | - |
+| `loginByOauth2` | 创建 OAuth2 登录会话 | `PUBLIC` | `POST` | `/auth/oauth2` | `body` | - |
+| `loginByPassword` | 创建密码登录会话 | `PUBLIC` | `POST` | `/auth/login` | `body` | - |
+| `refreshToken` | 刷新 Token | `PUBLIC` | `POST` | `/auth/refresh` | `body` | - |
+
+## BroadcastApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `compare` | 查询 Broadcast 差异 | `broadcast` | `GET` | `/broadcast-diffs` | - | - |
+| `create` | 创建 Broadcast | `broadcast` | `POST` | `/broadcast` | `body` | - |
+| `deleteOne` | 删除 Broadcast | `broadcast` | `DELETE` | `/broadcast/{msg}` | `path.msg` | `query.languages`, `query.onlyMsg` |
+| `deploy` | 创建 Broadcast 部署 | `broadcast` | `POST` | `/broadcast-deployments` | `body` | - |
+| `getOne` | 获取单个 Broadcast | `PUBLIC` | `GET` | `/broadcast/{msg}` | `path.msg` | `query.env` |
+| `list` | 分页查询 Broadcast 列表 | `PUBLIC` | `GET` | `/broadcast` | - | `query.current`, `query.pageSize`, `query.search`, `query.env` |
+| `update` | 更新 Broadcast | `broadcast` | `PUT` | `/broadcast/{msg}` | `path.msg`, `body` | - |
+
+## CfgLangApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `compare` | 查询语言配置差异 | `cfglang` | `GET` | `/language-config-diffs` | `query.table` | - |
+| `create` | 创建语言配置条目 | `cfglang` | `POST` | `/language-configs/{table}/entries` | `path.table`, `body` | - |
+| `deleteOne` | 删除语言配置条目 | `cfglang` | `DELETE` | `/language-configs/{table}/entries/{key}` | `path.table`, `path.key` | - |
+| `deploy` | 创建语言配置部署 | `cfglang` | `POST` | `/language-config-deployments` | `body` | - |
+| `list` | 分页查询语言配置 | `PUBLIC` | `GET` | `/cfglang` | `query.table` | `query.key`, `query.search`, `query.env`, `query.current`, `query.pageSize` |
+| `update` | 更新语言配置条目 | `cfglang` | `PATCH` | `/language-configs/{table}/entries/{key}` | `path.table`, `path.key`, `body` | - |
+
+## CountApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getHistory` | 查询历史玩家数 | `AUTHENTICATED` | `GET` | `/counts/history` | `query.startTime`, `query.endTime` | `query.types`, `query.maxPoints` |
+| `getLatest` | 查询最新玩家数 | `PUBLIC` | `GET` | `/counts/latest` | - | `query.types` |
+| `getTypes` | 获取可用类型 | `AUTHENTICATED` | `GET` | `/counts/types` | - | - |
+
+## EaseChatApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `createSubscription` | 创建订阅 | `easechat` | `POST` | `/easechat/subscriptions` | `body` | - |
+| `deleteSubscription` | 删除订阅 | `easechat` | `DELETE` | `/easechat/subscriptions/{subscriptionId}` | `path.subscriptionId` | - |
+| `listSubscriptions` | 分页查询订阅 | `easechat` | `GET` | `/easechat/subscriptions` | - | `query.current`, `query.pageSize` |
+| `sendHlaba` | 发送 HLABA 消息 | `AUTHENTICATED` | `POST` | `/easechat/hlaba` | `body` | - |
+
+## GamelogApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getDisasterEvents` | 获取灾难事件字典 | `player_info` | `GET` | `/game-logs/disasters/events` | - | - |
+| `getDisasterMatchDetails` | 获取单局灾难对局详情 | `player_info` | `GET` | `/game-logs/disasters/matches/{stageId}` | `path.stageId` | - |
+| `getDisasterMatches` | 分页查询灾难对局日志 | `player_info` | `GET` | `/game-logs/disasters/matches` | `query.ecid` | `query.startTime`, `query.endTime`, `query.current`, `query.pageSize` |
+| `getDisasterPlayerStats` | 获取玩家灾难点数与灾级 | `player_info` | `GET` | `/game-logs/disasters/players/{ecid}/stats` | `path.ecid` | - |
+| `getGames` | 获取游戏列表 | `player_info` | `GET` | `/game-logs/games` | - | - |
+| `getMatchDetails` | 获取单局对局详情 | `player_info` | `GET` | `/game-logs/matches/{sessionId}` | `path.sessionId` | `query.game` |
+| `getMatches` | 分页查询对局记录 | `player_info` | `GET` | `/game-logs/matches` | `query.game` | `query.ecid`, `query.startTime`, `query.endTime`, `query.current`, `query.pageSize` |
+| `getPitSessionDetails` | 获取 Pit 会话详情 | `player_info` | `GET` | `/game-logs/pit-sessions/{id}` | `path.id` | - |
+| `getPitSessions` | 分页查询 Pit 会话列表 | `player_info` | `GET` | `/game-logs/pit-sessions` | - | `query.serverName`, `query.ecid`, `query.startTime`, `query.endTime`, `query.current`, `query.pageSize` |
+| `getPlayers` | 分页查询游戏玩家记录 | `player_info` | `GET` | `/game-logs/players` | `query.game` | `query.ecid`, `query.startTime`, `query.endTime`, `query.current`, `query.pageSize` |
+
+## GlobalKVApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `create` | 创建 GlobalKV | `globalkv` | `POST` | `/globalkv` | `body` | - |
+| `deleteBatch` | 创建 GlobalKV 批量删除任务 | `globalkv` | `POST` | `/globalkv-deletion-jobs` | `body` | - |
+| `deleteOne` | 删除单个 GlobalKV | `globalkv` | `DELETE` | `/globalkv/{key}` | `path.key` | - |
+| `getOne` | 获取单个 GlobalKV | `globalkv` | `GET` | `/globalkv/{key}` | `path.key` | - |
+| `list` | 分页查询 GlobalKV 列表 | `globalkv` | `GET` | `/globalkv` | - | `query.current`, `query.pageSize`, `query.search`, `query.pattern`, `query.sortBy`, `query.sortOrder`, `query.valueType` |
+| `update` | 更新 GlobalKV | `globalkv` | `PUT` | `/globalkv/{key}` | `path.key`, `body` | - |
+
+## ItemApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getCommodity` | 获取所有商品类型配置 | `AUTHENTICATED` | `GET` | `/items` | - | `query.lang` |
+
+## LobbyApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `list` | 查询大厅运行列表 | `lobby` | `GET` | `/lobby` | - | `query.type`, `query.bigId` |
+
+## LogApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getAction` | 分页查询玩家行为记录 | `player_info` | `GET` | `/logs/action` | `query.startTime`, `query.endTime` | `query.ecid`, `query.categories`, `query.events`, `query.current`, `query.pageSize` |
+| `getAuth` | 分页查询登录日志 | `player_senstive_info` | `GET` | `/logs/auth` | - | `query.ecid`, `query.action`, `query.startTime`, `query.endTime`, `query.current`, `query.pageSize` |
+| `getChat` | 分页查询聊天日志 | `chat_log` | `GET` | `/logs/chat` | - | `query.current`, `query.pageSize`, `query.type`, `query.startTime`, `query.endTime`, `query.posType`, `query.posId`, `query.sourceEcid`, `query.sourceDisplayName`, `query.message` |
+| `getCommand` | 分页查询命令使用日志 | `player_info` | `GET` | `/logs/command` | `query.ecid`, `query.startTime`, `query.endTime` | `query.current`, `query.pageSize` |
+| `getLatestTeaming` | 获取最新组队日志 | `player_info` | `GET` | `/logs/latest-teaming` | - | `query.current`, `query.pageSize` |
+| `getMail` | 分页查询玩家邮件日志 | `player_info` | `GET` | `/logs/mail` | - | `query.targetEcid`, `query.startTime`, `query.endTime`, `query.current`, `query.pageSize` |
+| `getTeaming` | 分页查询组队日志 | `player_info` | `GET` | `/logs/teaming` | `query.ecid`, `query.startTime`, `query.endTime` | `query.current`, `query.pageSize` |
+
+## SpamDetectorApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getStats` | 查询刷屏检测器统计数据 | `punish` | `GET` | `/monitor/spam-detector/stats` | - | - |
+| `getStatus` | 获取刷屏检测器状态 | `punish` | `GET` | `/monitor/spam-detector/status` | - | - |
+| `restart` | 创建刷屏检测器重启任务 | `punish` | `POST` | `/monitor/spam-detector/restarts` | `body` | - |
+| `setState` | 更新刷屏检测器运行状态 | `punish` | `PUT` | `/monitor/spam-detector/state` | `body` | - |
+| `updateConfig` | 更新刷屏检测器配置 | `punish` | `PATCH` | `/monitor/spam-detector/config` | `body` | - |
+
+## OrderApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `createDownloadTask` | 创建下载任务 | `player_info` | `POST` | `/orders/downloads` | `body` | - |
+| `getDeliver` | 查询订单发货状态 | `player_info` | `GET` | `/order-deliveries` | `query.ecid`, `query.key` | - |
+| `getDownloadCount` | 获取下载总条数 | `player_info` | `GET` | `/orders/downloads/count` | `query.startTime`, `query.endTime` | - |
+| `getDownloadStatus` | 查询下载任务状态 | `player_info` | `GET` | `/orders/downloads/{downloadId}` | `path.downloadId` | - |
+| `getExchangeLogs` | 分页查询兑换日志 | `player_info` | `GET` | `/orders/exchange-logs` | `query.ecid`, `query.startTime`, `query.endTime` | `query.current`, `query.pageSize` |
+| `getLogs` | 分页查询订单日志 | `player_info` | `GET` | `/orders/logs` | `query.ecid` | `query.current`, `query.pageSize` |
+| `listDownloadTasks` | 分页查询下载任务 | `player_info` | `GET` | `/orders/downloads` | - | `query.current`, `query.pageSize` |
+
+## PermissionApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `deleteOne` | 删除玩家权益 | `permission` | `DELETE` | `/players/{ecid}/entitlements/{entitlementKey}` | `path.ecid`, `path.entitlementKey` | - |
+| `getPermission` | 获取玩家权益 | `player_info` | `GET` | `/players/{ecid}/entitlements` | `path.ecid` | - |
+| `upsert` | 创建或更新玩家权益 | `permission` | `PUT` | `/players/{ecid}/entitlements/{entitlementKey}` | `path.ecid`, `path.entitlementKey`, `body` | - |
+
+## PlayerApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `batchNeteaseNicknames` | 批量获取玩家展示名 | `AUTHENTICATED` | `POST` | `/players/netease-nicknames` | `body` | - |
+| `clearRespackCache` | 删除资源包缓存 | `player_info` | `DELETE` | `/players/{ecid}/resource-pack/cache` | `path.ecid` | - |
+| `createGamingTags` | 批量创建 GamingTag | `player_info` | `POST` | `/players/gaming-tags` | `body` | - |
+| `getBinding` | 查询玩家绑定的网易账号 | `player_info` | `GET` | `/players/{ecid}/netease-accounts` | `path.ecid` | - |
+| `getFarmSeasonPointSpends` | 分页查询 EC 农场赛季积分消耗 | `player_info` | `GET` | `/players/{ecid}/farm/season-point-spends` | `path.ecid` | `query.seasonId`, `query.current`, `query.pageSize` |
+| `getHeadicon` | 获取玩家头像图片 | `PUBLIC` | `GET` | `/players/{ecid}/headicon` | `path.ecid` | `query.frame`, `query.size` |
+| `getInfo` | 查询玩家服内状态 | `player_info` | `GET` | `/players/info` | `query.displayName` | - |
+| `getLastPlayed` | 获取最近游戏记录 | `player_info` | `GET` | `/players/{ecid}/last-played` | `path.ecid` | `query.count` |
+| `getNeteaseAccountPlayer` | 查询网易账号当前绑定的玩家 | `player_info` | `GET` | `/netease-accounts/{xuid}/player` | `path.xuid` | - |
+| `getPasswordHash` | 获取用户密码哈希 | `password_update` | `GET` | `/players/{ecid}/password` | `path.ecid` | - |
+| `getSkin` | 获取玩家皮肤数据 | `PUBLIC` | `GET` | `/players/{ecid}/skin` | `path.ecid` | - |
+| `getStageRecord` | 分页查询玩家关卡记录 | `player_info` | `GET` | `/players/{ecid}/stage/record` | `path.ecid`, `query.startTime`, `query.endTime` | `query.current`, `query.pageSize` |
+| `getUserData` | 获取玩家基础数据 | `player_info` | `GET` | `/players/{ecid}/data` | `path.ecid` | - |
+| `getWallet` | 获取玩家钱包 | `player_info` | `GET` | `/players/{ecid}/wallet` | `path.ecid` | - |
+| `getWalletLots` | 分页查询玩家钱包批次 | `player_info` | `GET` | `/players/{ecid}/wallet/lots` | `path.ecid` | `query.currency`, `query.includeExpired`, `query.current`, `query.pageSize` |
+| `listAllGamingTags` | 查询 GamingTag 管理列表 | `player_info` | `GET` | `/players/gaming-tags` | - | `query.current`, `query.pageSize`, `query.sortOrder`, `query.sortField`, `query.ecid`, `query.tag` |
+| `listGamingTags` | 获取玩家 GamingTag | `player_info` | `GET` | `/players/{ecid}/gaming-tags` | `path.ecid` | `query.current`, `query.pageSize` |
+| `operateGamingTag` | 添加玩家 GamingTag | `player_info` | `POST` | `/players/{ecid}/gaming-tags` | `path.ecid`, `body` | - |
+| `queryNetease` | 查询网易账号搜索命中列表 | `AUTHENTICATED` | `GET` | `/netease-accounts` | `query.displayName` | - |
+| `removeGamingTag` | 删除玩家 GamingTag | `player_info` | `DELETE` | `/players/{ecid}/gaming-tags/{tag}` | `path.ecid`, `path.tag` | - |
+| `resetBinding` | 解绑玩家名下全部网易账号 | `player_senstive_info` | `DELETE` | `/players/{ecid}/netease-accounts` | `path.ecid` | - |
+| `resetNeteaseAccountPlayer` | 解绑网易账号当前玩家 | `player_senstive_info` | `DELETE` | `/netease-accounts/{xuid}/player` | `path.xuid` | - |
+| `resetSingleBinding` | 解绑玩家名下单个网易账号 | `player_senstive_info` | `DELETE` | `/players/{ecid}/netease-accounts/{xuid}` | `path.ecid`, `path.xuid` | - |
+| `searchEcid` | 查询玩家搜索命中列表 | `player_info` | `GET` | `/players` | `query.search` | - |
+| `setRankLevel` | 设置玩家 VIP 等级 | `ranklevel` | `PUT` | `/players/{ecid}/rank-level` | `path.ecid`, `body` | - |
+| `updateBinding` | 绑定或改绑网易账号到玩家 | `player_senstive_info` | `PUT` | `/netease-accounts/{xuid}/player` | `path.xuid`, `body` | - |
+| `updateGamingTag` | 更新玩家 GamingTag | `player_info` | `PUT` | `/players/{ecid}/gaming-tags/{tag}` | `path.ecid`, `path.tag`, `body` | - |
+| `updatePassword` | 更新用户密码 | `password_update` | `PUT` | `/players/{ecid}/password` | `path.ecid`, `body` | - |
+| `updateUserData` | 更新用户数据 | `player_senstive_info` | `PUT` | `/players/{ecid}` | `path.ecid`, `body` | - |
+
+## CutoffLeaderboardApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getLeaderboard` | 获取 Cutoff 排行榜 | `PUBLIC` | `GET` | `/players/cutoff-leaderboard` | - | `query.game`, `query.season`, `query.current`, `query.pageSize` |
+| `getPlayerRank` | 获取玩家 Cutoff 排名 | `PUBLIC` | `GET` | `/players/cutoff-leaderboard/{ecid}/rank` | `path.ecid` | `query.game`, `query.season` |
+
+## PlayerMerchandiseApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `create` | 创建玩家道具 | `mail` | `POST` | `/players/{ecid}/merchandise` | `path.ecid`, `body` | - |
+| `deleteOne` | 删除玩家道具 | `mail` | `DELETE` | `/players/{ecid}/merchandise/{category}/{itemId}` | `path.ecid`, `path.category`, `path.itemId` | - |
+| `list` | 查询玩家商品道具 | `player_info` | `GET` | `/players/{ecid}/merchandise` | `path.ecid` | `query.category`, `query.itemId`, `query.data`, `query.current`, `query.pageSize` |
+| `update` | 更新玩家道具 | `mail` | `PUT` | `/players/{ecid}/merchandise/{category}/{itemId}` | `path.ecid`, `path.category`, `path.itemId`, `body` | - |
+
+## PlayerRankScoreApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getConfig` | 查询段位等级配置 | `AUTHENTICATED` | `GET` | `/players/rank-score/config` | - | `query.game` |
+| `getProgress` | 查询玩家段位进度 | `player_info` | `GET` | `/players/rank-score/progress` | `query.ecid` | `query.game`, `query.season` |
+| `getScore` | 查询玩家段位分 | `player_info` | `GET` | `/players/rank-score` | `query.ecid` | `query.game`, `query.season` |
+
+## PlayerScoreApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `deleteTop` | 删除玩家分数 | `score` | `DELETE` | `/players/score/top` | `query.ecid`, `query.game`, `query.scoreType`, `query.deadlineType` | - |
+| `getConfig` | 获取分数配置 | `AUTHENTICATED` | `GET` | `/players/score/config` | - | - |
+| `getLeaderboard` | 批量查询排行榜数据 | `PUBLIC` | `GET` | `/players/score/leaderboard` | - | `query.game` |
+| `getRank` | 获取玩家指定榜单名次 | `PUBLIC` | `GET` | `/players/score/rank` | `query.ecid`, `query.game`, `query.scoreType`, `query.deadlineType` | `query.sortOrder` |
+| `getScore` | 获取玩家分数 | `PUBLIC` | `GET` | `/players/score` | `query.ecid`, `query.game` | `query.scoreType`, `query.deadlineType` |
+| `getStages` | 获取玩家历史对局分数 | `AUTHENTICATED` | `GET` | `/players/score/stages` | `query.ecid` | `query.game` |
+| `getTop` | 分页查询排行榜前 N 名 | `PUBLIC` | `GET` | `/players/score/top` | `query.game`, `query.scoreType`, `query.deadlineType` | `query.current`, `query.pageSize`, `query.sortOrder` |
+
+## PlayerTasksApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `create` | 创建玩家任务 | `mail` | `POST` | `/players/{ecid}/tasks` | `path.ecid`, `body` | - |
+| `deleteOne` | 删除玩家任务 | `mail` | `DELETE` | `/players/{ecid}/tasks/{category}/{taskId}` | `path.ecid`, `path.category`, `path.taskId` | - |
+| `list` | 查询玩家任务 | `player_info` | `GET` | `/players/{ecid}/tasks` | `path.ecid` | `query.category`, `query.taskId`, `query.data`, `query.current`, `query.pageSize` |
+| `update` | 更新玩家任务 | `mail` | `PUT` | `/players/{ecid}/tasks/{category}/{taskId}` | `path.ecid`, `path.category`, `path.taskId`, `body` | - |
+
+## PlayerVoteApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `processRewards` | 创建投票奖励邮件 | `AUTHENTICATED` | `POST` | `/players/vote/rewards` | `body` | - |
+
+## PlayerYearSummaryApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getBasicInfo` | 查询年度总结基础资料 | `player_info` | `GET` | `/players/year-summary/basic-info` | `query.ecid` | `query.year` |
+| `getCurrencyData` | 获取货币与消费数据 | `player_info` | `GET` | `/players/year-summary/currency-data` | `query.ecid` | `query.year` |
+| `getGameStats` | 获取游戏统计 | `player_info` | `GET` | `/players/year-summary/game-stats` | `query.ecid` | `query.year` |
+| `getLoginStats` | 获取登录统计 | `player_info` | `GET` | `/players/year-summary/login-stats` | `query.ecid` | `query.year` |
+| `getRankData` | 获取段位与积分数据 | `player_info` | `GET` | `/players/year-summary/rank-data` | `query.ecid` | `query.year` |
+| `getSocialData` | 获取社交数据 | `player_info` | `GET` | `/players/year-summary/social-data` | `query.ecid` | `query.year` |
+
+## PullConfigApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `pull` | 创建服务器配置同步任务 | `AUTHENTICATED` | `POST` | `/config-sync-jobs` | `body` | - |
+
+## PunishApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `clearDegree` | 清空玩家违规次数 | `punish` | `DELETE` | `/players/{ecid}/punishment-degree` | `path.ecid` | - |
+| `create` | 创建处罚 | `punish` | `POST` | `/punishments` | `body` | - |
+| `createPlayerOverwatchCases` | 创建玩家近期回放监管案件 | `punish` | `POST` | `/punishments/overwatch/player` | `body` | - |
+| `list` | 分页查询处罚列表 | `punish` | `GET` | `/punishments` | - | `query.ecid`, `query.type`, `query.current`, `query.pageSize` |
+| `overwatch` | 创建或更新 Overwatch 监督案件 | `punish` | `POST` | `/punishments/overwatch` | `body` | - |
+| `remove` | 解除处罚 | `punish` | `DELETE` | `/punishments/{ecid}/{type}` | `path.ecid`, `path.type` | `query.source`, `query.reason`, `query.displayName` |
+| `setParkourPunishment` | 设置跑酷天堂惩罚 | `punish` | `POST` | `/punishments/parkour` | `body` | - |
+
+## ServersApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getMainstackEvent` | 查询 MainStack 事件日志 | `servers` | `GET` | `/servers/mainstack-event` | `query.address`, `query.port` | - |
+| `getStatistics` | 查询服务器统计数据 | `servers` | `GET` | `/servers/statistics` | - | - |
+| `list` | 查询服务器运行列表 | `servers` | `GET` | `/servers` | - | `query.filter`, `query.min`, `query.max`, `query.sortBy`, `query.sortOrder` |
+
+## StageApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `create` | 创建自定义房间 | `stage` | `POST` | `/stages` | `body` | - |
+| `getDbId` | 查询房间数据库 ID | `stage` | `GET` | `/stage-database-ids` | `query.runtimeId` | - |
+| `getInfo` | 查询房间运行状态 | `stage` | `GET` | `/stages` | - | `query.game`, `query.state`, `query.runtimeId`, `query.requestId` |
+| `getTypes` | 获取房间类型设置 | `stage` | `GET` | `/stages/types` | - | - |
+
+## StageLogApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `exportCsv` | 导出房间日志计分 CSV | `stage` | `GET` | `/stage-logs/{id}/score.csv` | `path.id` | - |
+| `list` | 分页查询房间日志 | `stage` | `GET` | `/stage-logs` | - | `query.game`, `query.current`, `query.pageSize` |
+| `query` | 获取单个房间日志 | `stage` | `GET` | `/stage-logs/{id}` | `path.id` | - |
+
+## SystemApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getHealth` | 获取服务健康状态 | `PUBLIC` | `GET` | `/health` | - | - |
+| `getLiveness` | 获取服务存活状态 | `PUBLIC` | `GET` | `/health/live` | - | - |
+| `getReadiness` | 获取服务就绪状态 | `PUBLIC` | `GET` | `/health/ready` | - | - |
+| `getRoot` | 获取服务基础资料 | `PUBLIC` | `GET` | `/` | - | - |
+
+## UserApi
+
+| 方法 | 说明 | 权限 | HTTP | 路径 | 必填参数 | 可选参数 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `getById` | 获取玩家账号详情 | `auth_admin` | `GET` | `/users/{id}` | `path.id` | - |
+| `getMe` | 获取当前用户资料 | `AUTHENTICATED` | `GET` | `/users/me` | - | - |
+| `listAll` | 分页查询用户 | `auth_admin` | `GET` | `/users` | - | `query.current`, `query.pageSize` |
+| `updatePermissions` | 更新用户访问权限 | `auth_admin` | `PUT` | `/users/{username}/accesses` | `path.username`, `body` | - |

package/README.md

@@ -1,9 +1,9 @@
 # @easecation/ecapi-sdk
 
-ECAPI 的 Node.js / TypeScript SDK，封装了常用接口，并内置两种鉴权方式：
+ECAPI 的 Node.js / TypeScript SDK。SDK 同时提供两层入口：
 
-- `X-API-Key`（IAM API Key）
-- `X-App-Session-Token`（App Session Token）
+- `ECAPIClient`：推荐给业务代码使用的人类友好门面，按领域分组，由 OpenAPI 生成并覆盖当前全部 160 个接口。
+- `generated`：Orval 从 `openapi.json` 生成的完整低层函数与响应类型，适合需要精确状态码联合类型的场景。
 
 ## 安装
 
@@ -11,125 +11,176 @@ ECAPI 的 Node.js / TypeScript SDK，封装了常用接口，并内置两种鉴
 npm install @easecation/ecapi-sdk
 ```
 
+项目内开发请使用仓库根目录命令重新生成和构建：
+
+```bash
+yarn generate:openapi
+yarn generate:sdk
+yarn type-check:sdk
+yarn --cwd sdk/npm/ecapi-sdk build
+```
+
 ## 快速开始
 
 ```ts
-import { ECAPIClient } from "@easecation/ecapi-sdk";
+import { ECAPIClient, isECAPIError } from '@easecation/ecapi-sdk';
 
 const client = new ECAPIClient({
-  auth: { type: "apiKey", apiKey: process.env.EC_API_KEY! },
+  baseUrl: 'https://api.easecation.net',
+  apiKey: process.env.EC_API_KEY,
+  timeoutMs: 15_000,
 });
 
-const me = await client.user.getMe();
-const player = await client.player.getInfo({ name: "player123" });
+try {
+  const me = await client.user.getMe();
+  const player = await client.player.getInfo({ displayName: 'Steve' });
+
+  console.log(me.data, player.data);
+} catch (error) {
+  if (isECAPIError(error)) {
+    console.error(error.status, error.code, error.requestId, error.message);
+  }
+  throw error;
+}
 ```
 
-切换为 App Session Token：
+## 认证方式
+
+`ECAPIClient` 支持构造时配置，也支持运行时切换：
 
 ```ts
+const client = new ECAPIClient({ apiKey: process.env.EC_API_KEY });
+
+client.setApiKey('ec_xxx');
+client.setBearerToken(process.env.EC_LEGACY_TOKEN!);
 client.setAppSessionToken(process.env.EC_APP_SESSION_TOKEN!);
+client.clearAuth();
 ```
 
-## 客户端能力
+也可以使用更显式的 `auth`：
 
-- 默认 `baseUrl`：`https://console.easecation.net/apiv2`
-- 统一请求入口：`client.request(method, path, options)`
-- 默认超时：15s（可在构造时 `timeoutMs` 覆盖）
-- 支持 per-request 覆盖鉴权：`options.auth`
-- 非 2xx 响应抛出 `ECAPIError`（包含 `status`、`payload`、`url`）
+```ts
+new ECAPIClient({
+  auth: { type: 'bearer', token: process.env.EC_TOKEN! },
+});
+```
 
-## 参数传递（必填/可选）
+单次请求可通过 `options.auth` 覆盖，传 `null` 表示本次请求不发送认证。
 
-- 所有查询参数统一通过对象传入：`client.player.getWallet({ ecid: "..." })`
-- `QueryParams` 已补齐服务端常用 query key 自动提示
-- 每个 API 的必填/可选参数请查看：`API_REFERENCE.md`
-- 该参考文档由后端 OpenAPI 自动生成，和服务端校验保持一致
+## 类型提示与 Docstring
 
-## IDE 强类型提示
+- `client.player.getInfo({ displayName: '...' })` 这类方法会提示 query/body 的必填字段、字段类型和字段说明。
+- `apis.ts`、`method-signatures.d.ts`、API Reference 与 Python stub 均由 `sdk/generate_sdk_api_reference.py` 从 `openapi.json` 自动生成。
+- Query、Body、路径、权限和成功响应类型都从 OpenAPI schema 推断；新增后端接口会在生成时自动进入门面并接受覆盖检查。
+- 每个方法的 JSDoc 包含接口说明与所需权限；完整表格见 `API_REFERENCE.md`。
+- 响应体保持服务端统一 envelope；常规 JSON 接口会直接提示对应 OpenAPI 成功响应类型。
 
-- 包内提供方法级类型增强文件 `method-signatures.d.ts`
-- 调用每个 API 时，IDE 会提示该方法对应的 `Query` / `Body` 类型
-- 必填字段会在 TypeScript 类型检查中直接报错，减少运行时试错
+## 常用调用
 
-## API 覆盖
+```ts
+await client.system.getHealth();
+await client.system.getLiveness();
+await client.system.getReadiness();
+
+await client.player.searchEcid({ search: 'Steve' });
+await client.player.cutoffLeaderboard.getLeaderboard({ game: 'bedwar' });
+await client.punish.create({
+  type: 'WARNING',
+  ecid: 'player-ecid',
+  source: 'console',
+  reason: '测试警告',
+});
+await client.punish.setParkourPunishment({
+  ecid: 'player-ecid',
+  map: 'parkour_01',
+  start: 1717200000,
+  end: 1717286400,
+  usetime: 12345,
+});
+```
 
-> 下列为 SDK 已封装的主要接口，未覆盖部分可通过 `client.request(...)` 直接调用。
+未封装或临时接口可以直接走统一请求入口：
 
-### 用户
+```ts
+const result = await client.request('GET', '/players/info', {
+  query: { displayName: 'Steve' },
+});
+```
 
-- `client.user.getMe()` → `GET /user/me`
-- `client.user.loginByPassword(payload)` → `POST /user/auth`
-- `client.user.loginByOauth2(payload)` → `POST /user/oauth2`
-- `client.user.refreshToken(payload)` → `POST /user/refresh`
-- `client.user.getOpenId()` → `GET /user/openid`
-- `client.user.listAll()` → `GET /user/all`
-- `client.user.updatePermissions(payload)` → `PUT /user/permissions`
-- `client.user.getById(id)` → `GET /user/:id`
+## 生成式 SDK
 
-### 玩家
+生成式函数默认返回 Orval 风格 `{ data, status, headers }`，其中 `data` 是服务端响应 payload。
+Node.js 中使用相对路径前需要配置 baseUrl：
 
-- `client.player.getInfo()` → `GET /player/info`
-- `client.player.searchEcid()` → `GET /player/searchecid`
-- `client.player.getUserData()` → `GET /player/userdata`
-- `client.player.queryNetease()` → `GET /player/querynetease`
-- `client.player.setRankLevel(payload)` → `POST /player/ranklevel`
-- `client.player.clearRespackCache()` → `DELETE /player/respack/cache`
-- `client.player.getWallet()` → `GET /player/wallet`
-- `client.player.listGamingTags()` / `operateGamingTag(payload)` → `GET/POST /player/gaming-tag`
-- `client.player.getLastPlayed()` → `GET /player/last-played`
-- `client.player.getStageRecord()` → `GET /player/stage/record`
-- `client.player.getHeadicon()` / `getSkin()` → `GET /player/headicon|skin`（返回 `ArrayBuffer`）
-- `client.player.batchNeteaseNicknames(payload)` → `POST /player/neteasenicknames`
-- `client.player.getBinding()` / `resetBinding(payload)` / `updateBinding(payload)`
-- `client.player.updateUserData(nick, payload)` → `POST /player/update/:nick`
-- `client.player.updatePassword(ecid, payload)` / `getPasswordHash(ecid)`
+```ts
+import { configureECAPIFetch, generated, patchECAPIFetchConfig } from '@easecation/ecapi-sdk';
 
-#### 玩家子模块
+configureECAPIFetch({
+  baseUrl: 'http://localhost:8083',
+  bearerToken: process.env.EC_TOKEN,
+});
 
-- `client.player.score.*` → `/player/score*`
-- `client.player.tasks.*` → `/player/:ecid/tasks*`
-- `client.player.merchandise.*` → `/player/:ecid/merchandise*`
-- `client.player.yearSummary.*` → `/player/year-summary/*`
-- `client.player.vote.processRewards()` → `GET /player/vote`
+// configureECAPIFetch 会替换全局配置；如需只补充 header 或 token，使用 patchECAPIFetchConfig。
+patchECAPIFetchConfig({ defaultHeaders: { 'X-Trace-Id': 'trace-1' } });
 
-### 管理与处罚
+const res = await generated.healthControllerCheck();
+console.log(res.status, res.data);
+```
 
-- `client.admin.*` → `/admin/*`
-- `client.punish.*` → `/punish/*`
-- `client.ban.*` → `/ban/*`
-- `client.permission.*` → `/permission`
+如果你只想要 payload 本身，可使用绑定配置的 `createECAPIFetch()` 或 `ECAPIClient`。
 
-### 日志与审计
+## 错误处理
 
-- `client.log.*` → `/log/*`
-- `client.audit.*` → `/audit/*`
+非 2xx 响应、网络错误和超时都会抛出 `ECAPIError`：
 
-### 配置与内容
+```ts
+try {
+  await client.permission.getPermission('player-ecid');
+} catch (error) {
+  if (isECAPIError(error)) {
+    console.log({
+      status: error.status,
+      code: error.code,
+      requestId: error.requestId,
+      details: error.details,
+      message: error.message,
+    });
+  }
+}
+```
 
-- `client.stage.*`（含 `stage.logs.*`）→ `/stage/*`
-- `client.item.getCommodity()` → `/item/commodity`
-- `client.cfglang.*` → `/cfglang*`
-- `client.globalkv.*` → `/globalkv*`
-- `client.broadcast.*` → `/broadcast*`
-- `client.pullConfig.pull()` → `/pull-config`
+字段说明：
 
-### 运营与系统
+- `status`：HTTP 状态码；网络错误或取消为 `0`。
+- `message`：优先来自服务端 `error.message` / `message`。
+- `code`：来自服务端 `error.code`，例如 `VALIDATION_ERROR`。
+- `requestId`：来自响应 envelope 或 `x-request-id` header。
+- `payload`：完整错误响应，便于调试或上报。
 
-- `client.order.*` → `/order/*`
-- `client.count.*` → `/count/*`
-- `client.servers.*` → `/servers*`
-- `client.lobby.list()` → `/lobby/list`
-- `client.easechat.*` → `/easechat/*`
-- `client.monitor.spamDetector.*` → `/monitor/spam-detector/*`
-- `client.system.getHealth()` → `/health`
+## 二进制响应
 
-## 完整 API 参考
+手写门面中的二进制接口会返回 `ArrayBuffer`：
 
-- `API_REFERENCE.md`
+```ts
+const headIcon = await client.player.getHeadicon('player-ecid');
+```
 
-更新命令（在 `easecation-api` 根目录执行）：
+生成式 SDK 对非 JSON 响应会把 `Blob` 放在 `{ data }` 中；手写门面会按方法语义返回 `ArrayBuffer` 或 `string`。
 
-```bash
-python3 sdk/generate_sdk_api_reference.py
-```
+## API 覆盖
+
+当前 `ECAPIClient` 门面由 `openapi.json` 生成并覆盖全部 160 个接口。主要分组包括：
+
+- `client.auth`、`client.user`
+- `client.player`、`client.player.score`、`client.player.cutoffLeaderboard`
+- `client.punish`、`client.permission`、`client.admin`
+- `client.log`、`client.audit`、`client.gamelog`
+- `client.stage`、`client.item`、`client.cfglang`、`client.globalKV`、`client.broadcast`
+- `client.order`、`client.count`、`client.servers`、`client.lobby`、`client.easechat`
+- `client.monitor.spamDetector`、`client.pullConfig`、`client.system`
+
+完整方法、权限和参数请查看 `API_REFERENCE.md`。
+
+## 契约说明
 
+SDK 只面向新的 REST/OpenAPI 契约，不提供旧路径兼容别名。接口路径、权限、参数说明以 `openapi.json` 和 Swagger 文档为准；`yarn check:sdk-contracts` 会校验门面对 OpenAPI 的双向覆盖。