Sea-Studio/MC_Report
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4dfc30ce892fd76a40d2834a8c1f5d8d452fa6f3
MC_Report/docs/API.md
canglan 4dfc30ce89 docs: standalone external API doc for bots/third-party 
- docs/EXTERNAL-API.md: auth matrix (ID+Secret / legacy key / JWT),
  Python+Node quickstart, server alias syntax, 9 endpoints with
  request/response examples, status flow, error codes, troubleshooting,
  typical scenarios (QQ bot ticket flow, plugin ban sync)
- README + API.md link to the standalone doc
- verified: 24 checks, endpoints cross-checked doc vs code
2026-08-19 19:40:25 +08:00

404 lines
15 KiB
Markdown
Raw Blame History

# MC Report System API 文档
> 面向**机器人 / 第三方系统**的免登录 API(鉴权方式、请求示例、子服定位语法)见独立文档 **[EXTERNAL-API.md](EXTERNAL-API.md)**。
Base URL: `http://<host>:3100/api`
## 通用约定
| 项 | 说明 |
|----|------|
| 认证头 | `Authorization: Bearer <JWT>`(登录后获得) |
| API 密钥头 | `x-api-key: <api_key>`(安装时生成,注入前端页面,所有请求需携带) |
| 外部密钥头 | `x-external-key: <external_api_key>`(仅 /api/external 插件接口) |
| 内容类型 | `application/json`(文件上传用 `multipart/form-data`) |
| 错误格式 | `{ "error": "错误信息" }` |
| 限流 | 登录 8/min、注册 3/min、工单 500/min、匿名提交 5/min、全局 300/min |
**角色**:`owner`(服主) / `admin`(管理员) / `player`(玩家)
---
## 一、认证 Auth
### POST /auth/send-verify-code
发送邮箱验证码(注册前校验邮箱归属)。
```json
{ "email": "player@example.com" }
```
响应: `{ "code_id": "uuid", "message": "验证码已发送" }`
> 若 SMTP 未配置,返回 `{ code_id, code, dev: true }`(开发模式直显验证码)。
### POST /auth/register
注册账号(需先获取邮箱验证码)。
```json
{
"username": "player1", "password": "******", "email": "p@example.com",
"game_name": "Steve", "game_uid": "NETEASE_UID_001",
"source": "netease", // netease | skin(皮肤站可不填 UID)
"captcha_id": "uuid", "captcha_answer": "abcd",
"code_id": "uuid", "code": "123456"
}
```
响应 201: `{ "message": "注册成功，请登录" }`
> 注册时自动在 `user_identities` 中创建主身份记录。
### POST /auth/login
```json
{ "username": "player1", "password": "******" }
```
响应:
```json
{
"token": "<JWT>",
"user": { "id": 1, "username": "player1", "email": "p@example.com",
"game_name": "Steve", "game_uid": "NETEASE_UID_001",
"role": "player", "source": "netease" }
}
```
### GET /auth/me *(认证)*
返回当前用户完整信息,含 `identities` 数组(全部已绑定身份)。
### GET /auth/identities *(认证)*
列出当前账号绑定的全部身份(一个账号可同时绑定网易端 + 皮肤站)。
响应:
```json
[
{ "id": 1, "source": "netease", "game_name": "Steve", "game_uid": "NETEASE_UID_001", "created_at": "..." },
{ "id": 2, "source": "skin", "game_name": "Alex", "game_uid": "SKIN_UUID_002", "created_at": "..." }
]
```
### POST /auth/identities *(认证)*
绑定新来源身份(同来源仅能绑一个,游戏名全局唯一)。
```json
{ "source": "skin", "game_name": "Alex", "game_uid": "SKIN_UUID_002" }
```
| 规则 | 说明 |
|------|------|
| source | 必填,`netease` 或 `skin` |
| game_name | 必填,不能与其他账号已绑定的游戏名重复 |
| game_uid | 网易端必填 |
| 同来源重复 | 拒绝(先删除再重新绑定) |
| 至少保留一个 | 解绑时若只剩一个身份则拒绝 |
**皮肤站 UUID 自动查询**:皮肤站来源时,可通过 `GET /settings/uuid-lookup?site=<皮肤站地址>&name=<用户名>` 自动获取 UUID(调 Yggdrasil API `POST {site}/api/yggdrasil/api/profiles/minecraft`,带 SSRF 防护与 10s 超时)。站点皮肤站地址可在系统设置配置,前端绑定弹窗自动带出。
### DELETE /auth/identities/:id *(认证)*
解绑身份。响应: `{ "message": "已解绑" }`
### PUT /auth/profile *(认证)*
更新个人资料(game_name / game_uid / email)。主身份变更会同步到 `user_identities`。
### PUT /auth/password *(认证)*
```json
{ "oldPassword": "旧密码", "newPassword": "新密码" }
```
### POST /auth/forgot-password
```json
{ "email": "p@example.com" }
```
发送重置链接(使用 `reset_password` 模板,1 小时有效)。
### POST /auth/reset-password
```json
{ "token": "<reset_token>", "password": "新密码" }
```
### POST /auth/verify-email
验证邮箱(token 或 6 位验证码):
```json
{ "code": "<verify_token 或 6 位验证码>" }
```
---
## 二、工单 Tickets
状态机:`pending → processing → awaiting_info → resolved / rejected → closed(7天自动关闭)`;结果申诉 `appealing`。
### GET /tickets *(认证)*
工单列表(带过滤)。Query: `type` / `status` / `priority` / `claimed=0|1` / `search`。
- player: 仅自己的工单
- admin: 待处理 + 自己接的(建议/投诉管理员/结果申诉不可见)
- owner: 全部
### GET /tickets/stats *(认证)*
```json
{ "total": 12, "byStatus": { "pending": 3, "processing": 2 } }
```
### GET /tickets/unclaimed *(admin/owner)*
待认领工单。Query: `type`。
### GET /tickets/reported-players *(admin/owner)*
被举报人聚合统计(次数/处理中/已解决/已驳回/最近时间/常见原因)。
### GET /tickets/tracking?token=xxx
凭追踪标识查工单(匿名追踪用,无需登录)。
### GET /tickets/:id *(认证)*
工单详情(含 responses / attachments / transfers / parent_ticket)。
### POST /tickets *(可选认证)*
提交工单(支持匿名;登录用户可选用任一已绑定身份)。
`multipart/form-data` 或 JSON:
```json
{
"type": "report", // report | suggestion | appeal | result_appeal
"title": "标题",
"reporter_game_name": "Steve", // 登录用户可传自己的任一身份,后端校验归属
"reporter_game_uid": "UID",
"target_game_name": "Alex", // 举报必填(与 UID 至少一项)
"target_game_uid": "UID",
"reason": "举报原因", // report/appeal 必填
"description": "详细描述", // suggestion/appeal 必填
"priority": "medium", // low|medium|high|urgent
"is_admin_complaint": 0, // 投诉管理员(仅服主可见)
"parent_ticket_id": null // result_appeal 必填(原工单)
}
```
响应 201: `{ "id": 8, "tracking_token": "uuid", "message": "提交成功" }`(Set-Cookie 留存 tracking_token)
### PUT /tickets/:id *(admin/owner)*
更新状态/优先级/处理备注。
```json
{ "status": "processing", "priority": "high", "claim_note": "内部备注" }
```
### POST /tickets/:id/claim *(admin/owner)*
接单认领(建议/投诉管理员/结果申诉仅服主可认领)。
```json
{ "claim_note": "内部备注", "initial_reply": "给玩家的初始回复" }
```
### POST /tickets/:id/transfer *(admin/owner)*
转单。`{ "to_user_id": 2, "reason": "原因" }`
### POST /tickets/:id/response *(认证)*
回复/补充。`{ "content": "内容" }`
### POST /tickets/:id/anon-response
匿名补充(凭 tracking_token Cookie)。
### POST /tickets/batch *(admin/owner)*
批量操作。`{ "ids": [1,2], "action": "delete|status|close", "status": "resolved" }`
---
## 三、封禁 Bans *(owner)*
### GET /bans、GET /bans/active、GET /bans/min-duration *(认证)*
封禁列表 / 生效中 / 最短时长校验。
### POST /bans *(owner)*
```json
{ "player_name": "Alex", "player_uid": "UID", "source": "netease|skin",
"type": "ban|mute|warn|other", "duration": "7天", "reason": "原因",
"ticket_id": null }
```
### PUT /bans/:id *(owner)*
更新状态(`active|expired|appealed|lifted`)/原因/时长。
### DELETE /bans/:id *(owner)*
删除记录。
---
## 四、用户管理 Users *(admin/owner)*
### GET /users *(admin/owner)*、GET /users/:id *(admin/owner)*
用户列表(含 `identity_count` 身份数)/ 详情(含 `identities` 全部身份、管辖子服务器)。
### POST /users *(admin/owner)*
创建用户(自动写入 user_identities 主身份)。角色 owner 仅服主可建。
### PUT /users/:id *(admin/owner)*
更新邮箱/游戏名/UID/来源/角色/状态/密码/管辖服务器。主身份字段变化自动同步 `user_identities`。
### POST /users/:id/identities *(admin/owner)*
管理员为用户绑定额外来源身份(多身份管理)。
```json
{ "source": "skin", "game_name": "Alex", "game_uid": "SKIN_UUID" }
```
规则同 `POST /auth/identities`(同来源唯一、游戏名全局唯一、网易端必填 UID)。皮肤站来源同样支持「获取 UUID」辅助查询。
### DELETE /users/:id/identities/:identityId *(admin/owner)*
管理员解绑用户身份(至少保留一个)。
### GET /users/:id/servers *(admin/owner)*
管辖子服务器列表。
---
## 五、系统设置 Settings *(admin/owner)*
| 端点 | 说明 |
|------|------|
| GET /settings/settings | 全部设置(站点名称/地址/版权/ICP/SMTP) |
| PUT /settings/settings | 批量更新设置 |
| GET /settings/email-templates | 邮件模板列表 |
| GET /settings/email-templates/:code | 模板详情 |
| PUT /settings/email-templates/:code | 更新模板(subject/body,支持 HTML 与 {{变量}}) |
可用模板: `verify_email` / `email_code` / `ticket_created` / `ticket_updated` / `ticket_claimed` / `ticket_transferred` / `reset_password`
---
## 六、通知 Notifications *(admin/owner)*
### GET/POST /notifications
列表 / 创建 `{ name, type: "webhook|email", webhook_url, events: "all|ticket_created,..." }`
### PUT/DELETE /notifications/:id
更新(名称/地址/类型/启用)/删除。
### POST /notifications/:id/test
发送测试 Webhook。
---
## 七、投票 Polls
| 端点 | 认证 | 说明 |
|------|------|------|
| GET /polls/groups | 认证 | 分组/子服列表 |
| POST /polls/groups | owner | 添加分组 |
| DELETE /polls/groups/:id | owner | 删除分组 |
| GET /polls/active | 认证 | 当前生效投票(按分组聚合,含票数/我的投票) |
| GET/PUT/DELETE /polls/:id | owner | 详情/更新/删除 |
| POST /polls | owner | 创建(≥2选项,同子服仅一个进行中) |
| POST /polls/:id/vote | 认证 | 投票(管理员 1.5 票权,一人一票) |
---
## 八、更新内容 Features
| 端点 | 认证 | 说明 |
|------|------|------|
| GET /features | 认证 | 列表(状态: 待定/计划中/已完成) |
| POST /features | owner | 创建 |
| PUT/DELETE /features/:id | owner | 更新/删除 |
| POST /features/:id/vote | 认证 | 点赞 |
| POST /features/:id/comment | 认证 | 发表评论 |
---
## 九、导出 Export *(owner)*
| 端点 | 说明 |
|------|------|
| GET /export/tickets?type=&status=&start_date=&end_date=&format=csv | 工单导出 |
| GET /export/reported-players?format=csv | 被举报人统计导出 |
| GET /export/audit-logs?start_date=&end_date=&format=csv | 操作日志导出 |
| GET /export/dashboard | 控制台统计(总数/类型/状态/今日/用户数/月度趋势) |
---
## 九·五、日志 Logs *(admin/owner)*
系统自动记录邮件发送结果、Webhook 调用、服务器错误,后台「系统日志」页可查,方便排查。
| 端点 | 说明 |
|------|------|
| GET /logs/emails?status=sent\|failed&email=&limit= | 邮件日志(收件人/模板/主题/状态/错误) |
| GET /logs/system?level=info\|warn\|error&source=&limit= | 系统日志(级别/来源/消息/详情) |
记录来源:mailer(SMTP 未配置/发送成功/失败)、webhook(拦截内网/非2xx/发送失败)、server(500 错误中间件)。日志写库失败不影响主流程,表自动迁移创建。
---
## 十、验证码与文件
| 端点 | 说明 |
|------|------|
| GET /captcha | SVG 验证码 `{ id, svg }`(5 分钟有效) |
| GET /uploads/:storedName | 附件下载(鉴权;玩家仅可访问自己工单附件) |
---
## 十一、外部 API(游戏插件 / Java 服务器)
认证:`x-external-key: <external_api_key>`(安装时生成)。插件登录后可携带 Bearer JWT。
| 端点 | 认证 | 说明 |
|------|------|------|
| POST /external/auth/register | — | 插件注册(邮箱验证链接) |
| POST /external/auth/login | — | 插件登录,返回 JWT |
| GET /external/my-tickets | Bearer | 我的工单列表(limit ≤50) |
| GET /external/my-tickets/:id | Bearer | 我的工单详情 |
| POST /external/tickets | client | 提交工单(带 `server` 可选;返回 id + tracking_token) |
| GET /external/tickets/track?token= | client | 按追踪码查工单状态+回复(提交→处理→结束全流程) |
| GET /external/all-tickets | client | 全部工单(分页 page/limit ≤200,可按 `server`/`status`/`type` 过滤) |
| GET /external/all-tickets/:id | client | 工单详情(含回复/附件) |
| GET /external/bans?server=&status=&player= | client | 拉取封禁列表(可按子服/状态/玩家过滤) |
| POST /external/bans | client | 新增封禁(可带 `server`) |
| GET /external/reported-players?server= | client | 被举报统计(可按子服过滤) |
| GET /external/servers | client | 服务器列表(含外部别名) |
| GET /external/stats?server= | client | 工单统计(可按子服过滤) |
| POST /external/clients | Bearer(owner/admin) | 创建 API 客户端,返回 client_id + secret(仅显示一次) |
| GET /external/clients | Bearer(owner/admin) | 客户端列表 |
| PUT /external/clients/:id | Bearer(owner/admin) | 启用/停用客户端 |
| DELETE /external/clients/:id | Bearer(owner/admin) | 删除客户端 |
### 外部鉴权(三选一)
| 方式 | 请求头 | 适用 |
|------|--------|------|
| 多客户端(推荐) | `x-api-client-id` + `x-api-secret` | QQ机器人等外部系统,后台可创建/停用多个客户端 |
| 旧版单 key | `x-external-key` | 兼容旧部署(`config.external_api_key`) |
| 用户 JWT | `Authorization: Bearer <jwt>` | 插件/已登录用户 |
### 子服务器定位(`server` 参数)
每个子服可在「服务器管理」配置**外部别名(alias)**,外部 API 的 `server` 参数支持三种写法:
- **别名**: `survival`(推荐,改名不影响)
- **分组/子服**: `网易服务器/生存服`
- **子服名**: `生存服`(同名时取第一个)
工单/封禁按提交时的 `server` 归属存储,查询时用同一参数即可精确拉取对应子服数据。
---
## 十二、安装与健康
| 端点 | 说明 |
|------|------|
| GET /install/status | `{ installed: true|false }` |
| POST /install/check-db | 测试数据库连接(不存在则自动建库;库名仅字母数字下划线) |
| POST /install/complete | 完成安装:建表 + 创建服主 + 生成密钥(完成后无需重启,自动加载业务路由) |
| GET /health | `{ status: "ok", installed: true|false }` |
安装流程(两步):`check-db` → `complete` → 前端自动刷新并跳转登录。
---
## 数据兼容与迁移
新增多来源身份功能时,`backend/db.js` 的 `migrateAdditions` 自动执行(幂等):
1. 创建 `user_identities` 表(UNIQUE(user_id, source))
2. 从 `users` 表回填主身份:`INSERT IGNORE ... SELECT id, source, game_name, game_uid FROM users`
3. 注册/插件注册/管理员创建用户时自动写入主身份记录
4. 管理员编辑主身份字段时自动同步 `user_identities`
5. 工单提交:登录用户可选择任一已绑定身份(后端校验归属);匿名仍走表单字段
> 老数据无需手工处理,服务启动时自动迁移;`users` 表原有字段(主身份)保持不变,完全向后兼容。
外部 API 功能新增迁移(幂等,服务启动自动执行):
1. 创建 `api_clients` 表(多客户端鉴权)
2. `server_groups` 加 `alias` 列(子服外部别名)
3. `tickets` / `bans` 加 `server_name` 列(按子服归属存储)
> 老工单/封禁 `server_name` 为空串,不影响原有查询;新提交的数据自动带子服归属。
Reference in New Issue View Git Blame Copy Permalink