{ "openapi": "3.1.0", "info": { "title": "星途 SDK、开发者账号与游戏服接口", "version": "0.2.1", "description": "本地接入验证协议：账号、SDK业务、开发者注册、Windows授权、可信角色与外部履约。平台运营后台其余接口不在本文件范围；真实支付供应商未开放。" }, "servers": [ { "url": "https://api.starai.art", "description": "当前文档部署的 API 地址；能力以 /api/capabilities 为准，地址配置不代表真实支付已开放" } ], "tags": [ { "name": "Public", "description": "无需身份凭据的基础信息" }, { "name": "Authentication", "description": "服务端授权码兑换与玩家身份验证" } ], "paths": { "/api/health": { "get": { "operationId": "getHealth", "tags": [ "Public" ], "summary": "本地演示健康检查", "security": [], "responses": { "200": { "description": "服务运行中", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "status": "ok", "mode": "demo" } } } }, "403": { "description": "浏览器来源未获准。错误码：ORIGIN_FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端内部错误。错误码：INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-source": "packages/server/src/app.ts:createApp GET /api/health" } }, "/api/config": { "get": { "operationId": "getConfig", "tags": [ "Public" ], "summary": "获取已批准应用配置", "description": "维护状态通过 maintenance 字段返回，配置查询本身不因维护返回 503。应用待审、停用或开发者受限时拒绝访问。", "security": [], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "去除首尾空白后的应用 ID。", "example": "starlight-h5" } ], "responses": { "200": { "description": "应用配置", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformConfig" } } } }, "400": { "description": "查询参数无效。错误码：VALIDATION_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "应用不可用或浏览器来源未获准。错误码：APP_UNAVAILABLE、ORIGIN_FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "应用不存在。错误码：APP_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端内部错误。错误码：INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-source": "packages/server/src/app.ts:GET /api/config; packages/server/src/platform.ts:config/app" } }, "/api/server/auth/exchange": { "post": { "operationId": "exchangeAuthorizationCode", "tags": [ "Authentication" ], "summary": "可信游戏服务器兑换一次性登录授权码", "description": "服务端密钥不可分发给 H5/Android 客户端。验证应用、游戏密钥、一次性授权码与 PKCE 后返回本地平台会话。授权码有效期 60 秒，只能消费一次；响应丢失时重新发起登录，不盲目重试旧码。当前每请求 IP 每分钟最多 120 次，单进程计数。", "security": [ { "GameServerKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRequest" } } } }, "responses": { "200": { "description": "兑换成功，返回玩家会话与本地模拟角色", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "400": { "description": "请求不符合严格字段约束或 JSON 格式错误。错误码：VALIDATION_ERROR、INVALID_JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "密钥无效，或授权码过期、已消费、应用或 PKCE 不匹配。错误码：INVALID_GAME_KEY、INVALID_AUTH_CODE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "应用或账号受限，或浏览器来源未获准。错误码：APP_UNAVAILABLE、ACCOUNT_RESTRICTED、ORIGIN_FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "应用不存在。错误码：APP_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "JSON 请求体超过 32 KB。错误码：PAYLOAD_TOO_LARGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "兑换请求过于频繁。错误码：RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端内部错误。错误码：INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-source": "packages/server/src/app.ts:exchangeSchema/exchange" } }, "/api/me": { "get": { "operationId": "getPlayerIdentity", "tags": [ "Authentication" ], "summary": "查询当前玩家与模拟角色", "description": "只接受玩家会话，不接受开发者或运营后台会话。返回 user 与 role，不返回或刷新 token；会话过期、撤销或账号/应用受限时拒绝。", "security": [ { "PlayerBearer": [] } ], "responses": { "200": { "description": "当前逻辑游戏中的玩家身份", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityResponse" } } } }, "401": { "description": "缺少有效 Bearer 请求头，或玩家会话无效/过期。错误码：UNAUTHENTICATED、SESSION_EXPIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "账号或应用受限，或浏览器来源未获准。错误码：ACCOUNT_RESTRICTED、APP_UNAVAILABLE、ORIGIN_FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "会话关联应用不存在。错误码：APP_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "服务端内部错误。错误码：INTERNAL_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-source": "packages/server/src/app.ts:player and GET /api/me" } }, "/api/auth/sms/send": { "post": { "operationId": "postApiAuthSmsSend", "summary": "申请本地演示短信挑战", "security": [], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "retryAfterSeconds": { "type": "integer", "minimum": 0, "maximum": 100000 }, "demoCode": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "challengeId", "retryAfterSeconds", "demoCode" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 11, "maxLength": 11 }, "purpose": { "type": "string", "enum": [ "login", "password_reset", "account_deletion" ] } }, "required": [ "phone", "purpose" ], "additionalProperties": false } } } } } }, "/api/auth/login": { "post": { "operationId": "postApiAuthLogin", "summary": "玩家PKCE授权", "security": [], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "minLength": 16, "maxLength": 256 }, "expiresIn": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "code", "state", "expiresIn" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100 }, "method": { "type": "string", "enum": [ "password", "sms" ] }, "account": { "type": "string", "minLength": 11, "maxLength": 11 }, "password": { "type": "string", "minLength": 1, "maxLength": 128 }, "challengeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "code": { "type": "string", "minLength": 1, "maxLength": 10 }, "consentVersion": { "const": "2026-09" }, "codeChallenge": { "type": "string", "minLength": 43, "maxLength": 43 }, "state": { "type": "string", "minLength": 16, "maxLength": 256 } }, "required": [ "appId", "method", "account", "consentVersion", "codeChallenge", "state" ], "additionalProperties": false } } } } } }, "/api/auth/password/reset": { "post": { "operationId": "postApiAuthPasswordReset", "summary": "重置玩家密码", "security": [], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 11, "maxLength": 11 }, "challengeId": { "type": "string", "minLength": 20, "maxLength": 100 }, "code": { "type": "string", "minLength": 1, "maxLength": 10 }, "newPassword": { "type": "string", "minLength": 10, "maxLength": 128 } }, "required": [ "phone", "challengeId", "code", "newPassword" ], "additionalProperties": false } } } } } }, "/api/auth/logout": { "post": { "operationId": "postApiAuthLogout", "summary": "退出当前玩家会话", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/center": { "get": { "operationId": "getApiCenter", "summary": "读取游戏平台中心", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CenterResponse" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/account/sessions": { "get": { "operationId": "getApiAccountSessions", "summary": "读取本人会话", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSession" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/account/sessions/revoke-others": { "post": { "operationId": "postApiAccountSessionsRevokeOthers", "summary": "撤销玩家会话", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } } }, "/api/account/sessions/{id}/revoke": { "post": { "operationId": "postApiAccountSessionsIdRevoke", "summary": "撤销玩家会话", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } } }, "/api/account/password": { "post": { "operationId": "postApiAccountPassword", "summary": "修改密码并撤销其他会话", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 128 }, "newPassword": { "type": "string", "minLength": 10, "maxLength": 128 } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false } } } } } }, "/api/orders": { "get": { "operationId": "getApiOrders", "summary": "当前游戏订单", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "postApiOrders", "summary": "创建订单并冻结目标快照", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "201": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 100 }, "roleId": { "type": "string", "minLength": 1, "maxLength": 100 }, "couponId": { "type": "string", "minLength": 1, "maxLength": 100 }, "paymentMethod": { "type": "string", "enum": [ "demo", "wallet" ] }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "productId", "roleId", "paymentMethod", "requestId" ], "additionalProperties": false } } } } } }, "/api/orders/{id}": { "get": { "operationId": "getApiOrdersId", "summary": "订单详情", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orders/{id}/pay": { "post": { "operationId": "postApiOrdersIdPay", "summary": "执行演示或钱包付款", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "requestId" ], "additionalProperties": false } } } } } }, "/api/orders/{id}/refund": { "post": { "operationId": "postApiOrdersIdRefund", "summary": "申请退款", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "requestId" ], "additionalProperties": false } } } } } }, "/api/orders/{id}/close": { "post": { "operationId": "postApiOrdersIdClose", "summary": "关闭未支付订单", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/gifts/{id}/claim": { "post": { "operationId": "postApiGiftsIdClaim", "summary": "领取礼包", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleId": { "type": "string", "minLength": 1, "maxLength": 100 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "roleId", "requestId" ], "additionalProperties": false } } } } } }, "/api/coupons/{id}/claim": { "post": { "operationId": "postApiCouponsIdClaim", "summary": "领取优惠券", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "requestId" ], "additionalProperties": false } } } } } }, "/api/benefits/daily/claim": { "post": { "operationId": "postApiBenefitsDailyClaim", "summary": "领取每日权益", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "requestId" ], "additionalProperties": false } } } } } }, "/api/messages/{id}/read": { "post": { "operationId": "postApiMessagesIdRead", "summary": "标记游戏消息已读", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/support/tickets": { "get": { "operationId": "getApiSupportTickets", "summary": "工单分页", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "before", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SupportTicket" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "postApiSupportTickets", "summary": "创建工单", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "201": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicket" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 80 }, "category": { "type": "string", "enum": [ "account", "payment", "game", "other" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 2000 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 100 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "subject", "category", "content", "requestId" ], "additionalProperties": false } } } } } }, "/api/support/tickets/{id}": { "get": { "operationId": "getApiSupportTicketsId", "summary": "工单详情", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicket" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/support/tickets/{id}/messages": { "post": { "operationId": "postApiSupportTicketsIdMessages", "summary": "追加工单消息", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicket" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 2000 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "content", "requestId" ], "additionalProperties": false } } } } } }, "/api/support/tickets/{id}/close": { "post": { "operationId": "postApiSupportTicketsIdClose", "summary": "关闭工单", "security": [ { "PlayerBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicket" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "requestId" ], "additionalProperties": false } } } } } }, "/api/desktop/authorizations": { "post": { "operationId": "postApiDesktopAuthorizations", "summary": "创建Windows系统浏览器授权事务", "security": [], "parameters": [], "responses": { "201": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopAuthorization" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100 }, "redirectUri": { "type": "string", "pattern": "^http://127\\.0\\.0\\.1:[0-9]+/starlight/callback$" }, "codeChallenge": { "type": "string", "minLength": 43, "maxLength": 43 }, "state": { "type": "string", "minLength": 16, "maxLength": 256 } }, "required": [ "appId", "redirectUri", "codeChallenge", "state" ], "additionalProperties": false } } } } } }, "/api/capabilities": { "get": { "operationId": "getApiCapabilities", "summary": "查询实际可用能力", "security": [], "parameters": [ { "in": "query", "name": "appId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformCapabilities" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/realms": { "get": { "operationId": "getApiRealms", "summary": "查询本人游戏区服", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GameRealm" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/roles": { "get": { "operationId": "getApiRoles", "summary": "查询本人可信角色绑定", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRoleBinding" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/server/realms": { "post": { "operationId": "postApiServerRealms", "summary": "可信游戏服务器登记区服", "security": [ { "GameServerKey": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GameRealm" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100 }, "serverId": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "enabled": { "type": "boolean" }, "version": { "type": "integer", "minimum": 0, "maximum": 100000 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "appId", "serverId", "name", "enabled", "version", "requestId" ], "additionalProperties": false } } } } } }, "/api/server/roles/bind": { "post": { "operationId": "postApiServerRolesBind", "summary": "游戏密钥与玩家会话双重验证角色绑定", "security": [ { "GameServerKey": [], "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRoleBinding" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100 }, "serverId": { "type": "string", "minLength": 1, "maxLength": 100 }, "externalRoleId": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "level": { "type": "integer", "minimum": 1, "maximum": 100000 }, "enabled": { "type": "boolean" }, "version": { "type": "integer", "minimum": 0, "maximum": 100000 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "appId", "serverId", "externalRoleId", "name", "level", "requestId" ], "additionalProperties": false } } } } } }, "/api/server/deliveries/claim": { "post": { "operationId": "postApiServerDeliveriesClaim", "summary": "领取30秒租约的履约事件", "security": [ { "GameServerKey": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LeasedDelivery" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "appId" ], "additionalProperties": false } } } } } }, "/api/server/deliveries/{id}/ack": { "post": { "operationId": "postApiServerDeliveriesIdAck", "summary": "游戏服完成发放或资产回收后确认", "security": [ { "GameServerKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEvent" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100 }, "leaseToken": { "type": "string", "minLength": 20, "maxLength": 100 }, "receiptId": { "type": "string", "minLength": 1, "maxLength": 100 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "appId", "leaseToken", "receiptId", "requestId" ], "additionalProperties": false } } } } } }, "/api/server/deliveries/{id}/fail": { "post": { "operationId": "postApiServerDeliveriesIdFail", "summary": "报告失败并进入退避或死信", "security": [ { "GameServerKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEvent" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100 }, "leaseToken": { "type": "string", "minLength": 20, "maxLength": 100 }, "reason": { "type": "string", "minLength": 1, "maxLength": 100 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "appId", "leaseToken", "reason", "requestId" ], "additionalProperties": false } } } } } }, "/api/developer/registration-terms": { "get": { "operationId": "getApiDeveloperRegistrationTerms", "summary": "获取当前注册服务说明", "security": [], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 100 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "content": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "required": [ "version", "title", "content" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/developer/register": { "post": { "operationId": "postApiDeveloperRegister", "summary": "创建开发者并建立8小时会话", "security": [], "parameters": [], "responses": { "201": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 100 }, "developer": { "$ref": "#/components/schemas/Developer" } }, "required": [ "token", "developer" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{2,39}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "pattern": "^(?=.*[A-Za-z])(?=.*[0-9]).*$" }, "acceptedTerms": { "const": true }, "termsVersion": { "const": "2026-09" } }, "required": [ "username", "name", "password", "acceptedTerms", "termsVersion" ], "additionalProperties": false } } } } } }, "/api/developer/login": { "post": { "operationId": "postApiDeveloperLogin", "summary": "开发者登录", "security": [], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 100 }, "developer": { "$ref": "#/components/schemas/Developer" } }, "required": [ "token", "developer" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 80 }, "password": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "username", "password" ], "additionalProperties": false } } } } } }, "/api/developer/me": { "get": { "operationId": "getApiDeveloperMe", "summary": "当前开发者", "security": [ { "DeveloperBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "developer": { "$ref": "#/components/schemas/Developer" } }, "required": [ "developer" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/developer/applications/{id}/fulfillment": { "get": { "operationId": "getApiDeveloperApplicationsIdFulfillment", "summary": "读取履约模式", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentConfiguration" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "postApiDeveloperApplicationsIdFulfillment", "summary": "更新后续订单履约模式", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentConfiguration" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "local", "external" ] }, "version": { "type": "integer", "minimum": 0, "maximum": 100000 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "mode", "version", "requestId" ], "additionalProperties": false } } } } } }, "/api/developer/applications/{id}/deliveries": { "get": { "operationId": "getApiDeveloperApplicationsIdDeliveries", "summary": "开发者事件分页", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "before", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryEvent" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/developer/applications/{id}/deliveries/{eventId}/retry": { "post": { "operationId": "postApiDeveloperApplicationsIdDeliveriesEventIdRetry", "summary": "人工重试死信事件", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEvent" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "requestId" ], "additionalProperties": false } } } } } }, "/api/developer/applications/{id}/provider-settings": { "get": { "operationId": "getApiDeveloperApplicationsIdProviderSettings", "summary": "读取供应商偏好", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSettings" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "postApiDeveloperApplicationsIdProviderSettings", "summary": "保存偏好，不激活真实通道", "security": [ { "DeveloperBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSettings" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentProvider": { "type": "string", "enum": [ "none", "wechat", "alipay", "apple_iap", "steam" ] }, "identityProvider": { "type": "string", "enum": [ "platform", "apple", "steam" ] }, "smsProvider": { "type": "string", "enum": [ "demo", "external" ] }, "version": { "type": "integer", "minimum": 0, "maximum": 100000 }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "paymentProvider", "identityProvider", "smsProvider", "version", "requestId" ], "additionalProperties": false } } } } } }, "/api/account/deletion-preview": { "get": { "operationId": "getApiAccountDeletionPreview", "summary": "注销资格和资产阻碍", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionPreview" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/account/export": { "get": { "operationId": "getApiAccountExport", "summary": "导出本人资料与记录", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "description": "按账号归属导出，保留记录字段见资料导出指南" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/account/deletion": { "post": { "operationId": "postApiAccountDeletion", "summary": "验证本人身份后执行账号注销", "security": [ { "PlayerBearer": [] } ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionResult" } } } }, "default": { "description": "请求校验、权限、冲突或服务错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "password", "sms" ] }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 128 }, "challengeId": { "type": "string", "minLength": 20, "maxLength": 100 }, "code": { "type": "string", "minLength": 1, "maxLength": 10 }, "confirmation": { "const": "DELETE_ACCOUNT" }, "forfeitBonus": { "type": "boolean" }, "requestId": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "method", "confirmation", "requestId" ], "additionalProperties": false } } } } } } }, "components": { "securitySchemes": { "GameServerKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "当前逻辑游戏的服务器密钥，仅保存在可信后端。" }, "PlayerBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "授权码兑换得到的玩家会话；不是 JWT。" }, "DeveloperBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "开发者控制台会话，与玩家和管理员令牌隔离。" } }, "schemas": { "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "mode": { "type": "string", "const": "demo" } }, "required": [ "status", "mode" ] }, "PlatformConfig": { "type": "object", "properties": { "brand": { "type": "string" }, "gameName": { "type": "string" }, "appId": { "type": "string" }, "accent": { "type": "string" }, "announcement": { "type": "string" }, "customerService": { "type": "string" }, "maintenance": { "type": "boolean" }, "giftsEnabled": { "type": "boolean" }, "couponsEnabled": { "type": "boolean" }, "walletEnabled": { "type": "boolean" }, "membershipEnabled": { "type": "boolean" }, "version": { "type": "integer" } }, "required": [ "brand", "gameName", "appId", "accent", "announcement", "customerService", "maintenance", "giftsEnabled", "couponsEnabled", "walletEnabled", "membershipEnabled", "version" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "description": "平台账号 ID；跨游戏关联身份。" }, "gameUserId": { "type": "string", "description": "当前逻辑游戏内玩家 ID；用于游戏服账号映射。" }, "nickname": { "type": "string" }, "phone": { "type": "string", "description": "当前实现返回完整手机号，请按业务必要性使用和展示。" }, "avatar": { "type": "string" }, "restricted": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "gameUserId", "nickname", "phone", "avatar", "restricted", "createdAt" ] }, "Role": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "server": { "type": "string" }, "level": { "type": "number" }, "diamonds": { "type": "number" }, "power": { "type": "number" } }, "required": [ "id", "name", "server", "level", "diamonds", "power" ], "description": "本地模拟游戏角色，尚未连接外部游戏服角色与资产。" }, "SessionResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "不透明玩家 Bearer 凭据，当前有效期 12 小时。" }, "user": { "$ref": "#/components/schemas/User" }, "role": { "$ref": "#/components/schemas/Role" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "token", "user", "role", "expiresAt" ] }, "IdentityResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "role": { "$ref": "#/components/schemas/Role" } }, "required": [ "user", "role" ] }, "ExchangeRequest": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "服务端会先去掉首尾空白；必须为已批准应用。" }, "code": { "type": "string", "minLength": 20, "maxLength": 100, "description": "有效期 60 秒且一次性消费的登录授权码。" }, "codeVerifier": { "type": "string", "minLength": 43, "maxLength": 128, "pattern": "^[a-zA-Z0-9._~-]+$", "description": "与该次登录 challenge 配对的 PKCE 验证器。" } }, "required": [ "appId", "code", "codeVerifier" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "共享类型允许此字段；当前实现通常不返回。" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "gameUserId": { "type": "string" }, "roleId": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "game_item" }, { "type": "string", "const": "wallet_topup" }, { "type": "string", "const": "monthly_pass" } ] }, "priceCents": { "type": "number" }, "discountCents": { "type": "number" }, "amountCents": { "type": "number" }, "paymentMethod": { "anyOf": [ { "type": "string", "const": "demo" }, { "type": "string", "const": "wallet" } ] }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "fulfilled" }, { "type": "string", "const": "refund_pending" }, { "type": "string", "const": "refunded" }, { "type": "string", "const": "closed" } ] }, "couponId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "createdAt": { "type": "string" }, "paidAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "refundedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "fulfillmentMode": { "anyOf": [ { "type": "string", "const": "local" }, { "type": "string", "const": "external" } ] }, "externalRole": { "anyOf": [ { "type": "object", "properties": { "bindingId": { "type": "string" }, "serverId": { "type": "string" }, "externalRoleId": { "type": "string" } }, "required": [ "bindingId", "serverId", "externalRoleId" ] } ] }, "source": { "anyOf": [ { "type": "string", "const": "purchase" }, { "type": "string", "const": "gift" } ] }, "giftId": { "anyOf": [ { "type": "string" } ] } }, "required": [ "id", "userId", "gameUserId", "roleId", "productId", "productName", "kind", "priceCents", "discountCents", "amountCents", "paymentMethod", "status", "couponId", "createdAt", "paidAt", "refundedAt" ] }, "PlatformCapabilities": { "type": "object", "properties": { "appId": { "type": "string" }, "platform": { "anyOf": [ { "type": "string", "const": "h5" }, { "type": "string", "const": "android" }, { "type": "string", "const": "ios" }, { "type": "string", "const": "windows" } ] }, "productionReady": { "type": "boolean", "const": false }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "payment" }, { "type": "string", "const": "identity" }, { "type": "string", "const": "sms" }, { "type": "string", "const": "fulfillment" } ] }, "available": { "type": "boolean" }, "mode": { "anyOf": [ { "type": "string", "const": "demo" }, { "type": "string", "const": "external" }, { "type": "string", "const": "platform" } ] }, "reason": { "type": "string" } }, "required": [ "id", "kind", "available", "mode", "reason" ] } } }, "required": [ "appId", "platform", "productionReady", "providers" ] }, "ProviderSettings": { "type": "object", "properties": { "gameId": { "type": "string" }, "paymentProvider": { "anyOf": [ { "type": "string", "const": "none" }, { "type": "string", "const": "wechat" }, { "type": "string", "const": "alipay" }, { "type": "string", "const": "apple_iap" }, { "type": "string", "const": "steam" } ] }, "identityProvider": { "anyOf": [ { "type": "string", "const": "platform" }, { "type": "string", "const": "steam" }, { "type": "string", "const": "apple" } ] }, "smsProvider": { "anyOf": [ { "type": "string", "const": "demo" }, { "type": "string", "const": "external" } ] }, "version": { "type": "number" }, "updatedAt": { "type": "string" } }, "required": [ "gameId", "paymentProvider", "identityProvider", "smsProvider", "version", "updatedAt" ] }, "DesktopAuthorization": { "type": "object", "properties": { "authorizationId": { "type": "string" }, "authorizationUrl": { "type": "string" }, "expiresIn": { "type": "number" } }, "required": [ "authorizationId", "authorizationUrl", "expiresIn" ] }, "GameRealm": { "type": "object", "properties": { "id": { "type": "string" }, "gameId": { "type": "string" }, "serverId": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "number" }, "updatedAt": { "type": "string" } }, "required": [ "id", "gameId", "serverId", "name", "enabled", "version", "updatedAt" ] }, "ExternalRoleTarget": { "type": "object", "properties": { "bindingId": { "type": "string" }, "serverId": { "type": "string" }, "externalRoleId": { "type": "string" } }, "required": [ "bindingId", "serverId", "externalRoleId" ] }, "ExternalRoleBinding": { "type": "object", "properties": { "gameId": { "type": "string" }, "gameUserId": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "number" }, "enabled": { "type": "boolean" }, "version": { "type": "number" }, "updatedAt": { "type": "string" }, "bindingId": { "type": "string" }, "serverId": { "type": "string" }, "externalRoleId": { "type": "string" } }, "required": [ "gameId", "gameUserId", "name", "level", "enabled", "version", "updatedAt", "bindingId", "serverId", "externalRoleId" ] }, "FulfillmentConfiguration": { "type": "object", "properties": { "gameId": { "type": "string" }, "mode": { "anyOf": [ { "type": "string", "const": "local" }, { "type": "string", "const": "external" } ] }, "version": { "type": "number" }, "updatedAt": { "type": "string" } }, "required": [ "gameId", "mode", "version", "updatedAt" ] }, "DeliveryEvent": { "type": "object", "properties": { "id": { "type": "string" }, "gameId": { "type": "string" }, "orderId": { "type": "string" }, "gameUserId": { "type": "string" }, "action": { "anyOf": [ { "type": "string", "const": "grant" }, { "type": "string", "const": "revoke" } ] }, "target": { "type": "object", "properties": { "bindingId": { "type": "string" }, "serverId": { "type": "string" }, "externalRoleId": { "type": "string" } }, "required": [ "bindingId", "serverId", "externalRoleId" ] }, "productId": { "type": "string" }, "diamonds": { "type": "number" }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "leased" }, { "type": "string", "const": "acknowledged" }, { "type": "string", "const": "dead" } ] }, "attempts": { "type": "number" }, "nextAttemptAt": { "type": "string" }, "leaseExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "receiptId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "lastError": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "createdAt": { "type": "string" }, "acknowledgedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "gameId", "orderId", "gameUserId", "action", "target", "productId", "diamonds", "status", "attempts", "nextAttemptAt", "leaseExpiresAt", "receiptId", "lastError", "createdAt", "acknowledgedAt" ] }, "LeasedDelivery": { "type": "object", "properties": { "leaseToken": { "type": "string" }, "id": { "type": "string" }, "gameId": { "type": "string" }, "orderId": { "type": "string" }, "gameUserId": { "type": "string" }, "action": { "anyOf": [ { "type": "string", "const": "grant" }, { "type": "string", "const": "revoke" } ] }, "target": { "type": "object", "properties": { "bindingId": { "type": "string" }, "serverId": { "type": "string" }, "externalRoleId": { "type": "string" } }, "required": [ "bindingId", "serverId", "externalRoleId" ] }, "productId": { "type": "string" }, "diamonds": { "type": "number" }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "leased" }, { "type": "string", "const": "acknowledged" }, { "type": "string", "const": "dead" } ] }, "attempts": { "type": "number" }, "nextAttemptAt": { "type": "string" }, "leaseExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "receiptId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "lastError": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "createdAt": { "type": "string" }, "acknowledgedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "leaseToken", "id", "gameId", "orderId", "gameUserId", "action", "target", "productId", "diamonds", "status", "attempts", "nextAttemptAt", "leaseExpiresAt", "receiptId", "lastError", "createdAt", "acknowledgedAt" ] }, "AccountDeletionPreview": { "type": "object", "properties": { "canDelete": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string" } }, "paidBalance": { "type": "number" }, "bonusBalance": { "type": "number" }, "requiresBonusForfeit": { "type": "boolean" }, "retainedRecords": { "type": "array", "items": { "type": "string" } } }, "required": [ "canDelete", "blockers", "paidBalance", "bonusBalance", "requiresBonusForfeit", "retainedRecords" ] }, "AccountDeletionResult": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "deletedAt": { "type": "string" }, "retainedRecords": { "type": "array", "items": { "type": "string" } }, "externalGameData": { "type": "string", "const": "contact_game_operator" } }, "required": [ "ok", "deletedAt", "retainedRecords", "externalGameData" ] }, "Developer": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "restricted": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "username", "name", "restricted", "createdAt" ] }, "CenterResponse": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "gameUserId": { "type": "string" }, "nickname": { "type": "string" }, "phone": { "type": "string" }, "avatar": { "type": "string" }, "restricted": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "gameUserId", "nickname", "phone", "avatar", "restricted", "createdAt" ] }, "role": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "server": { "type": "string" }, "level": { "type": "number" }, "diamonds": { "type": "number" }, "power": { "type": "number" } }, "required": [ "id", "name", "server", "level", "diamonds", "power" ] }, "config": { "type": "object", "properties": { "brand": { "type": "string" }, "gameName": { "type": "string" }, "appId": { "type": "string" }, "accent": { "type": "string" }, "announcement": { "type": "string" }, "customerService": { "type": "string" }, "maintenance": { "type": "boolean" }, "giftsEnabled": { "type": "boolean" }, "couponsEnabled": { "type": "boolean" }, "walletEnabled": { "type": "boolean" }, "membershipEnabled": { "type": "boolean" }, "version": { "type": "number" } }, "required": [ "brand", "gameName", "appId", "accent", "announcement", "customerService", "maintenance", "giftsEnabled", "couponsEnabled", "walletEnabled", "membershipEnabled", "version" ] }, "wallet": { "type": "object", "properties": { "paid": { "type": "number" }, "bonus": { "type": "number" }, "frozen": { "type": "number" } }, "required": [ "paid", "bonus", "frozen" ] }, "membership": { "type": "object", "properties": { "level": { "type": "number" }, "name": { "type": "string" }, "growth": { "type": "number" }, "nextGrowth": { "type": "number" }, "monthlyPassExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "dailyBenefitClaimed": { "type": "boolean" } }, "required": [ "level", "name", "growth", "nextGrowth", "monthlyPassExpiresAt", "dailyBenefitClaimed" ] }, "gifts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "diamonds": { "type": "number" }, "stock": { "type": "number" }, "claimed": { "type": "boolean" }, "tag": { "type": "string" } }, "required": [ "id", "name", "description", "icon", "diamonds", "stock", "claimed", "tag" ] } }, "coupons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "discountCents": { "type": "number" }, "minSpendCents": { "type": "number" }, "expiresAt": { "type": "string" }, "claimed": { "type": "boolean" }, "status": { "anyOf": [ { "type": "string", "const": "available" }, { "type": "string", "const": "locked" }, { "type": "string", "const": "used" }, { "type": "string", "const": "expired" } ] } }, "required": [ "id", "name", "discountCents", "minSpendCents", "expiresAt", "claimed", "status" ] } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "game_item" }, { "type": "string", "const": "wallet_topup" }, { "type": "string", "const": "monthly_pass" } ] }, "priceCents": { "type": "number" }, "diamonds": { "type": "number" }, "walletCredit": { "type": "number" }, "bonusCredit": { "type": "number" }, "tag": { "type": "string" } }, "required": [ "id", "name", "description", "kind", "priceCents", "diamonds", "walletCredit", "bonusCredit", "tag" ] } }, "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "gameUserId": { "type": "string" }, "roleId": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "game_item" }, { "type": "string", "const": "wallet_topup" }, { "type": "string", "const": "monthly_pass" } ] }, "priceCents": { "type": "number" }, "discountCents": { "type": "number" }, "amountCents": { "type": "number" }, "paymentMethod": { "anyOf": [ { "type": "string", "const": "demo" }, { "type": "string", "const": "wallet" } ] }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "fulfilled" }, { "type": "string", "const": "refund_pending" }, { "type": "string", "const": "refunded" }, { "type": "string", "const": "closed" } ] }, "couponId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "createdAt": { "type": "string" }, "paidAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "refundedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "fulfillmentMode": { "anyOf": [ { "type": "string", "const": "local" }, { "type": "string", "const": "external" } ] }, "externalRole": { "anyOf": [ { "type": "object", "properties": { "bindingId": { "type": "string" }, "serverId": { "type": "string" }, "externalRoleId": { "type": "string" } }, "required": [ "bindingId", "serverId", "externalRoleId" ] } ] }, "source": { "anyOf": [ { "type": "string", "const": "purchase" }, { "type": "string", "const": "gift" } ] }, "giftId": { "anyOf": [ { "type": "string" } ] } }, "required": [ "id", "userId", "gameUserId", "roleId", "productId", "productName", "kind", "priceCents", "discountCents", "amountCents", "paymentMethod", "status", "couponId", "createdAt", "paidAt", "refundedAt" ] } }, "ledger": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "purchase" }, { "type": "string", "const": "topup" }, { "type": "string", "const": "refund" }, { "type": "string", "const": "bonus" } ] }, "description": { "type": "string" }, "paidDelta": { "type": "number" }, "bonusDelta": { "type": "number" }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "description", "paidDelta", "bonusDelta", "orderId", "createdAt" ] } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "system" }, { "type": "string", "const": "order" }, { "type": "string", "const": "benefit" } ] }, "read": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "title", "body", "kind", "read", "createdAt" ] } }, "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "tag": { "type": "string" }, "action": { "anyOf": [ { "type": "string", "const": "wallet" }, { "type": "string", "const": "gifts" }, { "type": "string", "const": "coupons" }, { "type": "string", "const": "membership" }, { "type": "string", "const": "shop" } ] }, "theme": { "anyOf": [ { "type": "string", "const": "violet" }, { "type": "string", "const": "orange" }, { "type": "string", "const": "cyan" } ] } }, "required": [ "id", "title", "subtitle", "tag", "action", "theme" ] } } }, "required": [ "user", "role", "config", "wallet", "membership", "gifts", "coupons", "products", "orders", "ledger", "messages", "campaigns" ] }, "AccountSession": { "type": "object", "properties": { "id": { "type": "string" }, "appId": { "type": "string" }, "gameName": { "type": "string" }, "clientDescription": { "type": "string" }, "createdAt": { "type": "string" }, "lastSeenAt": { "type": "string" }, "expiresAt": { "type": "string" }, "current": { "type": "boolean" } }, "required": [ "id", "appId", "gameName", "clientDescription", "createdAt", "lastSeenAt", "expiresAt", "current" ] }, "SupportTicket": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "gameId": { "type": "string" }, "subject": { "type": "string" }, "category": { "anyOf": [ { "type": "string", "const": "account" }, { "type": "string", "const": "payment" }, { "type": "string", "const": "game" }, { "type": "string", "const": "other" } ] }, "status": { "anyOf": [ { "type": "string", "const": "closed" }, { "type": "string", "const": "open" }, { "type": "string", "const": "waiting_player" }, { "type": "string", "const": "waiting_support" } ] }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "version": { "type": "number" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "author": { "anyOf": [ { "type": "string", "const": "player" }, { "type": "string", "const": "support" } ] }, "content": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "author", "content", "createdAt" ] } } }, "required": [ "id", "userId", "gameId", "subject", "category", "status", "orderId", "createdAt", "updatedAt", "version", "messages" ] }, "SupportMessage": { "type": "object", "properties": { "id": { "type": "string" }, "author": { "anyOf": [ { "type": "string", "const": "player" }, { "type": "string", "const": "support" } ] }, "content": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "author", "content", "createdAt" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "game_item" }, { "type": "string", "const": "wallet_topup" }, { "type": "string", "const": "monthly_pass" } ] }, "priceCents": { "type": "number" }, "diamonds": { "type": "number" }, "walletCredit": { "type": "number" }, "bonusCredit": { "type": "number" }, "tag": { "type": "string" } }, "required": [ "id", "name", "description", "kind", "priceCents", "diamonds", "walletCredit", "bonusCredit", "tag" ] }, "Gift": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "diamonds": { "type": "number" }, "stock": { "type": "number" }, "claimed": { "type": "boolean" }, "tag": { "type": "string" } }, "required": [ "id", "name", "description", "icon", "diamonds", "stock", "claimed", "tag" ] }, "Coupon": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "discountCents": { "type": "number" }, "minSpendCents": { "type": "number" }, "expiresAt": { "type": "string" }, "claimed": { "type": "boolean" }, "status": { "anyOf": [ { "type": "string", "const": "available" }, { "type": "string", "const": "locked" }, { "type": "string", "const": "used" }, { "type": "string", "const": "expired" } ] } }, "required": [ "id", "name", "discountCents", "minSpendCents", "expiresAt", "claimed", "status" ] }, "Wallet": { "type": "object", "properties": { "paid": { "type": "number" }, "bonus": { "type": "number" }, "frozen": { "type": "number" } }, "required": [ "paid", "bonus", "frozen" ] }, "Membership": { "type": "object", "properties": { "level": { "type": "number" }, "name": { "type": "string" }, "growth": { "type": "number" }, "nextGrowth": { "type": "number" }, "monthlyPassExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "dailyBenefitClaimed": { "type": "boolean" } }, "required": [ "level", "name", "growth", "nextGrowth", "monthlyPassExpiresAt", "dailyBenefitClaimed" ] }, "LedgerEntry": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "purchase" }, { "type": "string", "const": "topup" }, { "type": "string", "const": "refund" }, { "type": "string", "const": "bonus" } ] }, "description": { "type": "string" }, "paidDelta": { "type": "number" }, "bonusDelta": { "type": "number" }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "description", "paidDelta", "bonusDelta", "orderId", "createdAt" ] } } } }