Threecard Engine API 文档
Dev 测试环境 · 部署提交 a978c8ed2126 · 契约版本 1.0.0-draft.1
HTTP 基址 https://threecard-api.infantryfive.cc
实时 WebSocket
wss://threecard-api.infantryfive.cc/api/v1/realtime
使用已允许的 Origin 建连，首帧发送 authenticate，令牌通过消息体传递。接口在线状态与业务验收分开记录。
ClientMessage
{
"oneOf": [
{
"$ref": "#/$defs/Authenticate"
},
{
"$ref": "#/$defs/Subscribe"
},
{
"$ref": "#/$defs/Unsubscribe"
},
{
"$ref": "#/$defs/WsCommand"
},
{
"$ref": "#/$defs/WsQuery"
}
]
}ServerMessage
{
"oneOf": [
{
"$ref": "#/$defs/Authenticated"
},
{
"$ref": "#/$defs/Subscribed"
},
{
"$ref": "#/$defs/Unsubscribed"
},
{
"$ref": "#/$defs/Ack"
},
{
"$ref": "#/$defs/SnapshotMessage"
},
{
"$ref": "#/$defs/Event"
},
{
"$ref": "#/$defs/Progress"
},
{
"$ref": "#/$defs/WsError"
}
]
}Authenticate
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"const": "authenticate"
},
"protocol_version": {
"const": "threecard.v1"
},
"request_id": {
"$ref": "#/$defs/Id"
},
"access_token": {
"type": "string",
"minLength": 1
}
},
"required": [
"type",
"protocol_version",
"request_id",
"access_token"
]
}HTTP 接口
POST /api/v1/auth/telegram telegramLogin
验签取Telegram身份；注册/赠金固定业务键；同键重放可新签会话但不能重发赠分。201为首次注册。
{
"operationId": "telegramLogin",
"summary": "telegramLogin",
"security": [],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "既有用户/同键重放，新会话。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/LoginResponse"
}
}
}
},
"201": {
"description": "首次注册原子提交。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/LoginResponse"
}
}
}
},
"202": {
"description": "注册提交仍UNKNOWN；无token、无重发赠分。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"default": {
"description": "认证、参数或依赖失败。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
},
"503": {
"description": "已证明未受理或全回滚；否则UNKNOWN。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/TelegramRequest"
}
}
}
},
"description": "验签取Telegram身份；注册/赠金固定业务键；同键重放可新签会话但不能重发赠分。201为首次注册。"
}POST /api/v1/auth/refresh refreshPlayerSession
{
"operationId": "refreshPlayerSession",
"summary": "refreshPlayerSession",
"security": [],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/TokensResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/RefreshRequest"
}
}
}
}
}POST /api/v1/auth/logout logoutPlayer
Only the current authenticated request may receive an empty 200 confirmation after its own logout is durably committed and self-revocation provenance is verified. No token/balance/cards. UNKNOWN has no success confirmation; expired/otherwise revoked credentials and subsequent old-token replay/query remain rejected. See README section 3.
{
"operationId": "logoutPlayer",
"summary": "logoutPlayer",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/EmptyResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
},
"202": {
"description": "UNKNOWN：原键查证，无token/牌面或新业务效果。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"503": {
"description": "仅已证明未受理或全回滚才KNOWN_ROLLED_BACK；否则202。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/LogoutRequest"
}
}
}
},
"description": "Only the current authenticated request may receive an empty 200 confirmation after its own logout is durably committed and self-revocation provenance is verified. No token/balance/cards. UNKNOWN has no success confirmation; expired/otherwise revoked credentials and subsequent old-token replay/query remain rejected. See README section 3."
}GET /api/v1/auth/session getPlayerSession
{
"operationId": "getPlayerSession",
"summary": "getPlayerSession",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/SessionResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}POST /api/v1/auth/dev-login 仅测试机内部 devLogin
仅显式非生产开关和既有seed用户；不创建用户、不赠分；禁用时路由不存在。
{
"operationId": "devLogin",
"summary": "devLogin",
"security": [],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "既有seed会话；registration.created=false, bonus_amount=0。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/LoginResponse"
}
}
}
},
"404": {
"description": "关闭时路由不存在，不承诺JSON；开启但身份不存在为USER_NOT_FOUND。"
},
"default": {
"description": "拒绝。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/DevLoginRequest"
}
}
}
},
"description": "仅显式非生产开关和既有seed用户；不创建用户、不赠分；禁用时路由不存在。"
}GET /api/v1/me getMe
{
"operationId": "getMe",
"summary": "getMe",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/UserResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}GET /api/v1/me/wallet getWallet
{
"operationId": "getWallet",
"summary": "getWallet",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/WalletResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}GET /api/v1/me/ledger getOwnLedger
{
"operationId": "getOwnLedger",
"summary": "getOwnLedger",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
{
"name": "page_size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/LedgerPageResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}GET /api/v1/me/history getOwnHistory
{
"operationId": "getOwnHistory",
"summary": "getOwnHistory",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
{
"name": "start",
"in": "query",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Timestamp"
}
},
{
"name": "end",
"in": "query",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Timestamp"
}
},
{
"name": "page_size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/HistoryPageResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}GET /api/v1/me/history/{hand_id} getOwnHandHistory
{
"operationId": "getOwnHandHistory",
"summary": "getOwnHandHistory",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "hand_id",
"in": "path",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/HistoryEntryResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}POST /api/v1/commands executePlayerCommand
Idempotency-Key必须等于action_id；HTTP与WS共享业务槽；APPLIED/REJECTED最小回执，不带牌。
{
"operationId": "executePlayerCommand",
"summary": "executePlayerCommand",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "COMMITTED/APPLIED或COMMITTED/REJECTED。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"202": {
"description": "UNKNOWN，只查证；不以失败补偿。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"503": {
"description": "已证明未受理/全回滚时KNOWN_ROLLED_BACK；仍UNKNOWN则202。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"default": {
"description": "解析/鉴权/入口拒绝，不能据此推断旧请求回滚。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/Command"
}
}
}
},
"description": "Idempotency-Key必须等于action_id；HTTP与WS共享业务槽；APPLIED/REJECTED最小回执，不带牌。"
}GET /api/v1/command-results/{scope_kind}/{scope_id}/{action_id} queryOwnCommand
只查当前身份自己的最小回执；空SELECT返回UNKNOWN，不返回404代表未发生。scope=auth需已认证身份；匿名登录按原验签请求重试。
{
"operationId": "queryOwnCommand",
"summary": "queryOwnCommand",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "scope_kind",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"player",
"room",
"auth"
]
}
},
{
"name": "scope_id",
"in": "path",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "action_id",
"in": "path",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "已确认结果或经屏障证明未提交。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"202": {
"description": "在途或没有足够证据，继续UNKNOWN。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"default": {
"description": "认证/权限/资源故障。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"description": "只查当前身份自己的最小回执；空SELECT返回UNKNOWN，不返回404代表未发生。scope=auth需已认证身份；匿名登录按原验签请求重试。"
}GET /api/v1/rooms/{room_id} getRoomSnapshot
{
"operationId": "getRoomSnapshot",
"summary": "getRoomSnapshot",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "room_id",
"in": "path",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/SnapshotResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}GET /api/v1/rooms/{room_id}/quote getActionQuote
{
"operationId": "getActionQuote",
"summary": "getActionQuote",
"security": [
{
"PlayerBearer": []
}
],
"parameters": [
{
"name": "room_id",
"in": "path",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/QuoteResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}POST /api/v1/admin/auth/login 仅测试机内部 adminLogin
{
"operationId": "adminLogin",
"summary": "adminLogin",
"security": [],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/AdminLoginResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/AdminLoginRequest"
}
}
}
}
}POST /api/v1/admin/auth/refresh 仅测试机内部 adminRefresh
{
"operationId": "adminRefresh",
"summary": "adminRefresh",
"security": [],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/TokensResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/RefreshRequest"
}
}
}
}
}POST /api/v1/admin/auth/logout 仅测试机内部 adminLogout
Only the current authenticated request may receive an empty 200 confirmation after its own logout is durably committed and self-revocation provenance is verified. No token/balance/cards. UNKNOWN has no success confirmation; expired/otherwise revoked credentials and subsequent old-token replay/query remain rejected. See README section 3.
{
"operationId": "adminLogout",
"summary": "adminLogout",
"security": [
{
"AdminBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/EmptyResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
},
"202": {
"description": "UNKNOWN：原键查证，无token/牌面或新业务效果。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"503": {
"description": "仅已证明未受理或全回滚才KNOWN_ROLLED_BACK；否则202。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/LogoutRequest"
}
}
}
},
"description": "Only the current authenticated request may receive an empty 200 confirmation after its own logout is durably committed and self-revocation provenance is verified. No token/balance/cards. UNKNOWN has no success confirmation; expired/otherwise revoked credentials and subsequent old-token replay/query remain rejected. See README section 3."
}GET /api/v1/admin/me 仅测试机内部 getAdmin
{
"operationId": "getAdmin",
"summary": "getAdmin",
"security": [
{
"AdminBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/AdminResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN"
}GET /api/v1/admin/config/telegram-first-login-bonus 仅测试机内部 getTelegramBonus
{
"operationId": "getTelegramBonus",
"summary": "getTelegramBonus",
"security": [
{
"AdminBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/BonusConfigResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"x-permission": "admin.telegram_bonus.manage"
}PUT /api/v1/admin/config/telegram-first-login-bonus 仅测试机内部 updateTelegramBonus
{
"operationId": "updateTelegramBonus",
"summary": "updateTelegramBonus",
"security": [
{
"AdminBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/BonusConfigResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
},
"202": {
"description": "UNKNOWN：原键查证，无token/牌面或新业务效果。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"503": {
"description": "仅已证明未受理或全回滚才KNOWN_ROLLED_BACK；否则202。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/BonusUpdate"
}
}
}
},
"x-permission": "admin.telegram_bonus.manage"
}POST /api/v1/admin/wallet-adjustments 仅测试机内部 adjustWallet
{
"operationId": "adjustWallet",
"summary": "adjustWallet",
"security": [
{
"AdminBearer": []
}
],
"parameters": [
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/AdjustmentResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
},
"202": {
"description": "UNKNOWN：原键查证，无token/牌面或新业务效果。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"503": {
"description": "仅已证明未受理或全回滚才KNOWN_ROLLED_BACK；否则202。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/AdjustmentRequest"
}
}
}
},
"x-permission": "admin.wallet_adjustments.execute"
}GET /api/v1/admin/command-results/{scope_kind}/{scope_id}/{action_id} 仅测试机内部 queryOwnAdminCommand
Only current Admin actor and original action permission. COMMITTED or proven KNOWN_ROLLED_BACK uses 200; unresolved/in-flight uses 202 UNKNOWN. Never execute from this GET.
{
"operationId": "queryOwnAdminCommand",
"summary": "queryOwnAdminCommand",
"security": [
{
"AdminBearer": []
}
],
"parameters": [
{
"name": "scope_kind",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"admin"
]
}
},
{
"name": "scope_id",
"in": "path",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "action_id",
"in": "path",
"required": true,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
},
{
"name": "X-Request-Id",
"in": "header",
"required": false,
"schema": {
"$ref": "./messages.schema.json#/$defs/Id"
}
}
],
"responses": {
"200": {
"description": "成功响应；数据结构见对应Schema。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
},
"default": {
"description": "请求拒绝；HTTP码与retry方式见README错误表。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ErrorResponse"
}
}
}
},
"202": {
"description": "UNKNOWN: query original actor/scope/action; no execution or permanent failure.",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/ReceiptResponse"
}
}
}
}
},
"x-review-status": "APPROVED_DESIGN",
"description": "Only current Admin actor and original action permission. COMMITTED or proven KNOWN_ROLLED_BACK uses 200; unresolved/in-flight uses 202 UNKNOWN. Never execute from this GET."
}GET /healthz healthz
{
"operationId": "healthz",
"summary": "healthz",
"security": [],
"responses": {
"200": {
"description": "进程活着/实例具备服务资格；不代表所有房间已恢复。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/Health"
}
}
}
},
"503": {
"description": "未就绪，不披露依赖拓扑。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/Health"
}
}
}
}
}
}GET /readyz readyz
{
"operationId": "readyz",
"summary": "readyz",
"security": [],
"responses": {
"200": {
"description": "进程活着/实例具备服务资格；不代表所有房间已恢复。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/Health"
}
}
}
},
"503": {
"description": "未就绪，不披露依赖拓扑。",
"content": {
"application/json": {
"schema": {
"$ref": "./messages.schema.json#/$defs/Health"
}
}
}
}
}
}