# MC Report System API 文档

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 | 网易端必填 |
| 同来源重复 | 拒绝(先删除再重新绑定) |
| 至少保留一个 | 解绑时若只剩一个身份则拒绝 |

### 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)*
用户列表 / 详情(含管辖子服务器)。

### POST /users *(admin/owner)*
创建用户(自动写入 user_identities 主身份)。角色 owner 仅服主可建。

### PUT /users/:id *(admin/owner)*
更新邮箱/游戏名/UID/来源/角色/状态/密码/管辖服务器。主身份字段变化自动同步 `user_identities`。

### 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 | 控制台统计(总数/类型/状态/今日/用户数/月度趋势) |

---

## 十、验证码与文件

| 端点 | 说明 |
|------|------|
| GET /captcha | SVG 验证码 `{ id, svg }`(5 分钟有效) |
| GET /uploads/:storedName | 附件下载(鉴权;玩家仅可访问自己工单附件) |

---

## 十一、外部 API(游戏插件 / Java 服务器)

认证:`x-external-key: <external_api_key>`(安装时生成)。插件登录后可携带 Bearer JWT。

| 端点 | 认证 | 说明 |
|------|------|------|
| POST /external/auth/register | external-key | 插件注册(邮箱验证链接) |
| POST /external/auth/login | external-key | 插件登录,返回 JWT |
| GET /external/my-tickets | external-key + Bearer | 我的工单列表(limit ≤50) |
| GET /external/my-tickets/:id | external-key + Bearer | 我的工单详情 |
| POST /external/tickets | external-key | 游戏内提交工单(自动写主身份) |
| GET /external/all-tickets | external-key | 全部工单(分页 page/limit ≤200) |
| GET /external/all-tickets/:id | external-key | 工单详情(含回复/附件) |
| GET /external/reported-players | external-key | 被举报统计 |
| GET /external/stats | external-key | 工单统计 |

---

## 十二、安装与健康

| 端点 | 说明 |
|------|------|
| 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` 表原有字段(主身份)保持不变,完全向后兼容。