first commit

2026-04-17 09:49:16 +08:00
commit 1ed31b9292
73 changed files with 16458 additions and 0 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -0,0 +1,330 @@
+# API 文档
+
+本文档覆盖当前 Go 重构版本中已经接入并可用于前台/后台重构联调的主要接口。
+
+## 认证与通用约定
+
+- 基础前缀：`/api`
+- 用户接口：`/api/v1/user/*`
+- 后台配置接口：`/api/v2/{secure_path}/*`
+- plugin 后台接口：`/api/v1/{secure_path}/*`
+- 鉴权方式：`Authorization: Bearer <jwt>`
+- 标准成功响应：
+
+```json
+{
+  "data": {}
+}
+```
+
+## Supplementary Parity Endpoints
+
+The current Go backend also exposes these Xboard-compatible endpoints:
+
+- `POST /api/v1/passport/auth/getQuickLoginUrl`
+- `POST /api/v1/passport/auth/loginWithMailLink`
+- `POST /api/v1/passport/comm/pv`
+- `GET /api/v1/user/comm/config`
+- `POST /api/v1/user/transfer`
+- `POST /api/v1/user/getQuickLoginUrl`
+- `GET /api/v1/user/notice/fetch`
+- `GET /api/v1/user/stat/getTrafficLog`
+- `GET /api/v1/user/invite/save`
+- `GET /api/v1/user/invite/fetch`
+- `GET /api/v1/user/invite/details`
+- `POST /api/v1/user/order/save`
+- `POST /api/v1/user/order/checkout`
+- `GET /api/v1/user/order/check`
+- `GET /api/v1/user/order/detail`
+- `GET /api/v1/user/order/fetch`
+- `GET /api/v1/user/order/getPaymentMethod`
+- `POST /api/v1/user/order/cancel`
+- `POST /api/v1/user/coupon/check`
+- `GET /api/v1/user/telegram/getBotInfo`
+- `POST /api/v1/user/comm/getStripePublicKey`
+- `POST /api/v1/user/gift-card/check`
+- `POST /api/v1/user/gift-card/redeem`
+- `GET /api/v1/user/gift-card/history`
+- `GET /api/v1/user/gift-card/detail`
+- `GET /api/v1/user/gift-card/types`
+- `POST /api/v2/{secure_path}/config/save`
+
+Notes:
+
+- order APIs now cover create, query, cancel, payment-method lookup, and zero-amount completion
+- invite APIs now read/write the existing `v2_*` tables directly
+- gift card routes are no longer `501`, but full reward-application business logic still needs a later dedicated migration
+
+- 标准失败响应：
+
+```json
+{
+  "message": "error message"
+}
+```
+
+## Passport
+
+### POST `/api/v1/passport/auth/login`
+
+登录。
+
+请求：
+
+```json
+{
+  "email": "admin@example.com",
+  "password": "password123"
+}
+```
+
+响应：
+
+```json
+{
+  "data": {
+    "token": "<jwt>",
+    "auth_data": "<jwt>",
+    "is_admin": true
+  }
+}
+```
+
+### POST `/api/v1/passport/auth/register`
+
+注册并直接返回登录态。
+
+### GET `/api/v1/passport/auth/token2Login?verify=<token>`
+
+使用一次性 `verify` 令牌换取登录态。
+
+### POST `/api/v1/passport/comm/sendEmailVerify`
+
+生成邮箱验证码。
+
+请求：
+
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+响应中会返回 `debug_code`，便于当前开发阶段联调。
+
+### POST `/api/v1/passport/auth/forget`
+
+使用邮箱验证码重置密码。
+
+请求：
+
+```json
+{
+  "email": "user@example.com",
+  "email_code": "123456",
+  "password": "new-password"
+}
+```
+
+## 用户前台接口
+
+### GET `/api/v1/user/info`
+
+返回当前用户信息。
+
+### GET `/api/v1/user/getSubscribe`
+
+返回订阅信息与订阅链接。
+
+### GET `/api/v1/user/getStat`
+
+返回 `[待支付订单数, 打开工单数, 邀请人数]`。
+
+### GET `/api/v1/user/server/fetch`
+
+返回当前用户可用节点列表。
+
+### GET `/api/v1/user/checkLogin`
+
+返回当前登录状态与管理员标记。
+
+### GET `/api/v1/user/resetSecurity`
+
+重置订阅令牌与 UUID。
+
+### POST `/api/v1/user/changePassword`
+
+修改密码。
+
+### POST `/api/v1/user/update`
+
+更新 `remind_expire` / `remind_traffic`。
+
+## 知识库
+
+### GET `/api/v1/user/knowledge/fetch`
+
+返回知识库文章列表。
+
+查询参数：
+
+- `language`: 可选，默认 `zh-CN`
+
+### GET `/api/v1/user/knowledge/getCategory`
+
+返回知识库分类列表。
+
+## 工单
+
+### GET `/api/v1/user/ticket/fetch`
+
+不带 `id` 时返回当前用户工单列表。
+
+### GET `/api/v1/user/ticket/fetch?id=<ticketId>`
+
+返回工单详情与消息列表。
+
+### POST `/api/v1/user/ticket/save`
+
+创建工单。
+
+请求：
+
+```json
+{
+  "subject": "节点异常",
+  "level": 1,
+  "message": "请帮我检查节点状态"
+}
+```
+
+### POST `/api/v1/user/ticket/reply`
+
+回复工单。
+
+### POST `/api/v1/user/ticket/close`
+
+关闭工单。
+
+### POST `/api/v1/user/ticket/withdraw`
+
+撤回工单，当前实现为将工单状态置为关闭。
+
+## 活跃会话
+
+### GET `/api/v1/user/getActiveSession`
+
+返回当前用户活跃 JWT 会话列表。
+
+### POST `/api/v1/user/removeActiveSession`
+
+撤销指定会话。
+
+请求：
+
+```json
+{
+  "session_id": "uuid"
+}
+```
+
+## Plugin: Real Name Verification
+
+### GET `/api/v1/user/real-name-verification/status`
+
+返回实名状态、是否可提交、实名信息掩码、审核结果等。
+
+### POST `/api/v1/user/real-name-verification/submit`
+
+提交实名信息。
+
+请求：
+
+```json
+{
+  "real_name": "张三",
+  "identity_no": "110101199001011234"
+}
+```
+
+管理端：
+
+- `GET /api/v1/{secure_path}/realname/records`
+- `POST /api/v1/{secure_path}/realname/review/{userId}`
+- `POST /api/v1/{secure_path}/realname/reset/{userId}`
+- `POST /api/v1/{secure_path}/realname/sync-all`
+- `POST /api/v1/{secure_path}/realname/approve-all`
+- `POST /api/v1/{secure_path}/realname/clear-cache`
+
+## Plugin: User Online Devices
+
+### GET `/api/v1/user/user-online-devices/get-ip`
+
+返回：
+
+- 在线 IP 列表
+- `session_overview`
+  - 在线设备数
+  - 设备限制
+  - 活跃会话列表
+
+管理端：
+
+- `GET /api/v1/{secure_path}/user-online-devices/users`
+
+## Plugin: User Add IPv6 Subscription
+
+### GET `/api/v1/user/user-add-ipv6-subscription/check`
+
+检查当前用户是否允许启用 IPv6 子账号。
+
+### POST `/api/v1/user/user-add-ipv6-subscription/enable`
+
+启用或同步 IPv6 影子账号。
+
+### POST `/api/v1/user/user-add-ipv6-subscription/sync-password`
+
+将主账号密码同步到 IPv6 子账号。
+
+## 后台统一接口
+
+### GET `/api/v2/{secure_path}/config/fetch`
+
+返回应用名称、站点 URL、后台路径、节点拉取/推送周期。
+
+### GET `/api/v2/{secure_path}/system/getSystemStatus`
+
+返回系统时间与站点基础信息。
+
+### GET `/api/v2/{secure_path}/plugin/getPlugins`
+
+返回 `v2_plugins` 列表。
+
+### GET `/api/v2/{secure_path}/plugin/types`
+
+返回插件类型。
+
+### GET `/api/v2/{secure_path}/plugin/integration-status`
+
+返回当前 plugin 在 Go 后端中的整合完成度说明。
+
+示例字段：
+
+```json
+{
+  "data": {
+    "real_name_verification": {
+      "enabled": true,
+      "status": "complete"
+    },
+    "user_online_devices": {
+      "enabled": true,
+      "status": "complete"
+    },
+    "user_add_ipv6_subscription": {
+      "enabled": true,
+      "status": "integrated_with_runtime_sync"
+    }
+  }
+}
+```