小枫_QWQ 项目文档站

Appearance

2026-08-13
2288
10m

HTTP API 文档 ​

项目：对面是AI吗
协议：HTTP/1.1
Content-Type：application/json（除标注外）
基础URL：https://game.xfcode.top
更新日期：2026-08-10

认证机制 ​

大部分需要身份的 API 使用 Bearer Token 认证：

  • 请求头：Authorization: Bearer <token>
  • Token 类型：JWT（HMAC-SHA256，密钥为玩家的 password_hash，有效期 365 天）
  • 获取方式：创建/恢复身份时下发
  • 特点：修改密码后旧 token 自动失效（密钥变化）

需要认证的 API（共 12 个）： /api/upload-userdata、/api/chat-history、/api/chat-history/detail、/api/chat-history/collect、/api/collection/like、/api/player-messages、/api/player-message/hide、/api/player-message/settings、/api/sticker/list、/api/sticker/upload、/api/sticker/delete、/api/generate-player-id（仅 action=change_password 时需要）

不需要认证的 API：其余为公开接口或通过昵称+密码手动验证。

通用错误响应 ​

所有 API 在认证失败时返回：

json
{"error": "缺少 token"}
{"error": "token 无效或已过期"}

1. 身份与账号 ​

1.1 获取/恢复玩家身份 ​

GET /api/generate-player-id

说明：创建新身份、恢复已有身份、修改密码、查询战绩的复合接口。

请求参数（Query）：

参数类型必填说明
actionstring否recover（恢复）、change_password（改密码）、空（查询）
nicknamestring条件恢复时必填，1-16 字符
passwordstring条件恢复时必填（原密码），改密码时传 old_password 和 new_password
old_passwordstring条件改密码时的旧密码
new_passwordstring条件改密码时的新密码，至少 6 位
fpstring否设备指纹，用于 IP+指纹联合查找

请求头：改密码时必须带 Authorization: Bearer <token>

场景一：通过 Token 查询战绩

bash
curl "https://game.xfcode.top/api/generate-player-id" \
  -H "Authorization: Bearer <token>"

响应 200：game.xfcode.top

json
{
  "stats": {
    "total_games": 42,
    "wins": 18,
    "losses": 20,
    "draws": 4,
    "style_tags": ["理性", "幽默"],
    "title": "老玩家"
  }
}

场景二：通过 IP+指纹恢复战绩

bash
curl "https://game.xfcode.top/api/generate-player-id?fp=<设备指纹>"

响应 200：

json
{
  "stats": { "total_games": 42, "wins": 18, "losses": 20, "draws": 4 }
}

场景三：密码恢复身份

bash
curl "https://game.xfcode.top/api/generate-player-id?action=recover&nickname=小明&password=123456"

成功 200：

json
{
  "token": "eyJ...",
  "nickname": "小明",
  "stats": { "total_games": 42, "wins": 18, "losses": 20, "draws": 4 }
}

玩家不存在 200：

json
{"error": "玩家不存在"}

密码错误 200：

json
{"error": "密码不正确"}

场景四：修改密码

bash
curl "https://game.xfcode.top/api/generate-player-id?action=change_password&old_password=123456&new_password=654321" \
  -H "Authorization: Bearer <token>"

成功 200：

json
{"ok": true}

密码过短 200：

json
{"error": "新密码至少 6 位"}

旧密码错误 200：

json
{"error": "旧密码不正确"}

场景五：无匹配

json
{"error": "未找到玩家"}

1.2 查询玩家战绩 ​

GET /api/player-stats

说明：通过昵称+密码查询战绩（不依赖 Token，适用于换了设备/浏览器的情况）。

请求参数（Query）：

参数类型必填说明
nicknamestring是昵称，1-16 字符
passwordstring是密码

请求示例：

bash
curl "https://game.xfcode.top/api/player-stats?nickname=小明&password=123456"

成功 200：

json
{
  "player_id": "abc123...",
  "stats": { "total_games": 42, "wins": 18, "losses": 20, "draws": 4 }
}

错误 200：

json
{"error": "昵称不能为空"}
{"error": "密码不能为空"}
{"error": "玩家不存在"}
{"error": "密码不正确"}

1.3 上传本地用户数据 ​

POST /api/upload-userdata

说明：将本地 UserData 同步到服务端。

认证：需要 Authorization 请求头。

请求体（JSON）：

字段类型必填说明
nicknamestring是昵称，1-16 字符
fpstring否设备指纹
statsarray否统计数据数组

请求示例：

bash
curl -X POST "https://game.xfcode.top/api/upload-userdata" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"nickname":"小明","fp":"abc123","stats":[{"key":"wins","value":10}]}'

成功 200：

json
{"success": true, "message": "数据上传成功"}

失败 200：

json
{"error": "上传失败: <错误详情>"}

2. 聊天记录 ​

2.1 聊天记录列表 ​

GET /api/chat-history

认证：需要 Authorization 请求头。

请求参数（Query）：

参数类型必填说明
pageint否页码，默认 1

请求示例：

bash
curl "https://game.xfcode.top/api/chat-history?page=1" \
  -H "Authorization: Bearer <token>"

成功 200：

json
{
  "list": [
    {
      "id": 1,
      "opponent_name": "小红",
      "truth": "ai",
      "guess": "human",
      "result": "lose",
      "duration": 600,
      "created_at": "2026-08-10 14:30:00"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 10
}

2.2 聊天记录详情 ​

GET /api/chat-history/detail

认证：需要 Authorization 请求头。

请求参数（Query）：

参数类型必填说明
idint是聊天记录 ID

请求示例：

bash
curl "https://game.xfcode.top/api/chat-history/detail?id=1" \
  -H "Authorization: Bearer <token>"

成功 200：

json
{
  "id": 1,
  "opponent_name": "小红",
  "messages": [...],
  "truth": "ai",
  "guess": "human"
}

参数错误 200：

json
{"error": "参数错误"}

未找到 200：

json
{"error": "未找到该记录"}

2.3 收藏聊天记录 ​

POST /api/chat-history/collect

认证：需要 Authorization 请求头。

请求体（JSON）：

字段类型必填说明
idint是聊天记录 ID
titlestring否收藏标题，最多 100 字符
is_publicbool否是否公开分享

请求示例：

bash
curl -X POST "https://game.xfcode.top/api/chat-history/collect" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"id":1,"title":"精彩对局","is_public":true}'

成功 200：

json
{"ok": true, "token": "public_token_xxx"}

3. 收藏 ​

3.1 通过 Token 获取收藏 ​

GET /api/collection/by-token

说明：无需登录，通过公开令牌查看收藏。

⚠️ 已知问题：此接口当前存在 bug，无法正常工作（$token 变量未从请求中获取）。

请求参数（Query）：

参数类型必填说明
tokenstring是公开令牌

成功 200：

json
{ "id": 1, "title": "精彩对局", "messages": [...] }

错误：

json
{"error": "参数错误"}
{"error": "该链接已失效或不存在"}

3.2 玩家公开收藏列表 ​

GET /api/player-collections

说明：公开接口，无需认证。

请求参数（Query）：

参数类型必填说明
nicknamestring是玩家昵称
pageint否页码，默认 1

3.3 收藏详情 ​

GET /api/collection/detail

说明：公开接口，无需认证。仅返回公开的收藏。

请求参数（Query）：

参数类型必填说明
idint是收藏 ID

错误：

json
{"error": "该收藏不存在或未公开"}

3.4 点赞收藏 ​

POST /api/collection/like

认证：需要 Authorization 请求头。

请求体（JSON）：

字段类型必填说明
idint是收藏 ID

4. 留言 ​

4.1 我的留言列表 ​

GET /api/player-messages

认证：需要 Authorization 请求头。

说明：获取其他玩家给自己的留言列表（含隐藏状态）。

4.2 隐藏/显示留言 ​

POST /api/player-message/hide

认证：需要 Authorization 请求头。

请求体（JSON）：

字段类型必填说明
message_idstring是留言 ID
hiddenbool是true=隐藏，false=显示

错误：

json
{"error": "参数不完整"}

4.3 留言设置 ​

POST /api/player-message/settings

认证：需要 Authorization 请求头。

请求体（JSON）：

字段类型必填说明
allow_messagesbool是是否允许他人留言

成功 200：

json
{"success": true, "message": "设置已更新"}

5. 表情 ​

5.1 表情列表 ​

GET /api/sticker/list

认证：需要 Authorization 请求头。

成功 200：

json
{
  "stickers": [
    { "id": "s1", "name": "大笑", "url": "/stickers/xxx.png" }
  ]
}

5.2 上传表情 ​

POST /api/sticker/upload

认证：需要 Authorization 请求头。

限制：

  • 单张图片 base64 解码前不超过约 2MB
  • 每个用户最多 100 个自定义表情

请求体（JSON）：

字段类型必填说明
image_datastring是Base64 图片数据（可带 data:image/xxx;base64, 前缀）
file_extstring否文件扩展名，默认 png

成功 200：

json
{"success": true, "sticker": {"id": "s1", "name": "自定义", "url": "/stickers/xxx.png"}}

错误：

json
{"error": "图片数据不能为空"}
{"error": "图片大小不能超过 2MB"}
{"error": "自定义表情已达上限（50个），请先删除旧表情"}

5.3 删除表情 ​

POST /api/sticker/delete

认证：需要 Authorization 请求头。

请求体（JSON）：

字段类型必填说明
sticker_idstring是表情 ID

成功 200：

json
{"success": true}

6. 公开档案 ​

6.1 玩家公开档案 ​

GET /api/player-profile

说明：公开接口，无需认证。

请求参数（Query）：

参数类型必填说明
nicknamestring是昵称，1-16 字符

成功 200：

json
{
  "nickname": "小明",
  "style_tags": ["理性", "幽默"],
  "title": "老玩家",
  "total_games": 42
}

7. 管理员 ​

7.1 管理员登录 ​

POST /{adminPath}/api/login

说明：{adminPath} 默认值为 /admin，可在配置中修改。注意此接口不走 Bearer Token，使用用户名+密码。

请求体（JSON）：

字段类型必填说明
usernamestring是管理员用户名
passwordstring是管理员密码

请求示例：

bash
curl -X POST "https://你的域名/admin/api/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"xxx"}'

成功 200：

json
{
  "ok": true,
  "token": "eyJ...",
  "username": "admin",
  "role": "super_admin"
}

失败：

json
{"ok": false, "error": "用户名和密码不能为空"}
{"ok": false, "error": "用户名或密码错误"}
{"ok": false, "error": "该账号已被禁用"}

Token 说明：

  • 管理员 Token 有效期 24 小时
  • 签名密钥为 Admin.Password 配置项
  • Payload 包含 admin_id、username、role

附录：完整 API 索引 ​

方法路径认证说明
GET/api/generate-player-id条件获取/恢复身份、改密码、查战绩
GET/api/player-stats密码通过昵称+密码查战绩
GET/api/player-profile无玩家公开档案
POST/api/upload-userdataBearer上传本地用户数据
GET/api/chat-historyBearer聊天记录列表
GET/api/chat-history/detailBearer聊天记录详情
POST/api/chat-history/collectBearer收藏聊天记录
GET/api/collection/by-token无通过 Token 获取收藏（已知 bug）
GET/api/player-collections无玩家公开收藏列表
GET/api/collection/detail无收藏详情
POST/api/collection/likeBearer点赞收藏
GET/api/player-messagesBearer我的留言列表
POST/api/player-message/hideBearer隐藏/显示留言
POST/api/player-message/settingsBearer留言设置
GET/api/sticker/listBearer表情列表
POST/api/sticker/uploadBearer上传表情
POST/api/sticker/deleteBearer删除表情
POST/{adminPath}/api/login密码管理员登录
最近更新