# Xboard API 返回 JSON 结构

基于 `reference/Xboard` 控制器、资源类、服务类静态分析整理。

说明：
- `T` 代表具体数据类型。
- “标准成功壳子”来自 `App\Helpers\ApiResponse::success()`。
- “标准失败壳子”来自 `App\Helpers\ApiResponse::fail()` 和全局异常处理。
- 少量接口直接 `response()->json()` 或返回文本/文件，不走统一壳子。
- 后台前缀统一记为 `/api/v2/{admin_secure_path}`。

## 统一返回壳子

### 标准成功壳子 `StandardSuccess<T>`

```json
{
  "status": "success",
  "message": "操作成功",
  "data": "<T>",
  "error": null
}
```

### 标准失败壳子 `StandardFail`

```json
{
  "status": "fail",
  "message": "错误信息",
  "data": null,
  "error": null
}
```

如果抛出 `ApiException`，`error` 可能带校验细节：

```json
{
  "status": "fail",
  "message": "错误信息",
  "data": null,
  "error": {
    "field": [
      "具体错误"
    ]
  }
}
```

### 分页壳子 `Paginate<T>`

```json
{
  "total": 100,
  "current_page": 1,
  "per_page": 10,
  "last_page": 10,
  "data": [
    "<T>"
  ]
}
```

### 简单列表壳子 `DataTotal<T>`

```json
{
  "data": [
    "<T>"
  ],
  "total": 100
}
```

### 自定义分页壳子 `DataPagination<T>`

```json
{
  "data": [
    "<T>"
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 15,
    "total": 150
  }
}
```

### 裸 `data` 壳子 `BareData<T>`

```json
{
  "data": "<T>"
}
```

### 仅消息 `MessageOnly`

```json
{
  "message": "文本消息"
}
```

## 共享数据结构

### `AuthData`

```json
{
  "token": "用户订阅 token",
  "auth_data": "Bearer <sanctum_token>",
  "is_admin": false
}
```

### `SessionToken`

来自 Sanctum token 原始序列化，核心字段通常包含：

```json
{
  "id": 1,
  "name": "随机 token 名称",
  "abilities": ["*"],
  "last_used_at": "2026-04-18T00:00:00.000000Z",
  "expires_at": "2027-04-18T00:00:00.000000Z",
  "created_at": "2026-04-18T00:00:00.000000Z",
  "updated_at": "2026-04-18T00:00:00.000000Z"
}
```

### `PlanResource`

```json
{
  "id": 1,
  "group_id": 1,
  "name": "套餐名",
  "tags": ["tag1"],
  "content": "展示文案",
  "month_price": 1000,
  "quarter_price": 2000,
  "half_year_price": 3000,
  "year_price": 4000,
  "two_year_price": 5000,
  "three_year_price": 6000,
  "onetime_price": 7000,
  "reset_price": 800,
  "capacity_limit": 100,
  "transfer_enable": 107374182400,
  "speed_limit": 100,
  "device_limit": 3,
  "show": true,
  "sell": true,
  "renew": true,
  "reset_traffic_method": 0,
  "sort": 1,
  "created_at": 1710000000,
  "updated_at": 1710000000
}
```

### `OrderResource`

`Order` 原始字段加两个派生字段：

```json
{
  "id": 1,
  "user_id": 1,
  "plan_id": 1,
  "trade_no": "uuid",
  "total_amount": 1000,
  "balance_amount": 0,
  "status": 0,
  "type": 1,
  "period": "month_price",
  "coupon_id": null,
  "payment_id": null,
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "plan": "<PlanResource|null>"
}
```

### `TicketResource`

```json
{
  "id": 1,
  "level": 1,
  "reply_status": 0,
  "status": 0,
  "subject": "主题",
  "message": [
    "<MessageResource>"
  ],
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "user_id": 1
}
```

### `MessageResource`

```json
{
  "id": 1,
  "ticket_id": 1,
  "is_me": true,
  "message": "正文",
  "created_at": 1710000000,
  "updated_at": 1710000000
}
```

### `KnowledgeResource`

```json
{
  "id": 1,
  "category": "分类",
  "title": "标题",
  "body": "正文，可选",
  "updated_at": 1710000000
}
```

### `InviteCodeResource`

```json
{
  "user_id": 1,
  "code": "ABCDEFGH",
  "pv": 12,
  "status": 0,
  "created_at": 1710000000,
  "updated_at": 1710000000
}
```

### `CommissionLogResource`

```json
{
  "id": 1,
  "order_amount": 1000,
  "trade_no": "uuid",
  "get_amount": 100,
  "created_at": 1710000000
}
```

### `TrafficLogResource`

```json
{
  "d": 1024,
  "u": 2048,
  "record_at": 1710000000,
  "server_rate": 1,
  "user_id": 1
}
```

### `NodeResource`

```json
{
  "id": 1,
  "type": "vmess",
  "version": 2,
  "name": "香港 01",
  "rate": 1,
  "tags": ["hk"],
  "is_online": true,
  "cache_key": "hash",
  "last_check_at": 1710000000
}
```

### `NodeConfig`

节点配置的公共骨架如下，具体字段按协议追加：

```json
{
  "protocol": "vmess|trojan|vless|shadowsocks|hysteria|tuic|anytls|socks|naive|http|mieru",
  "listen_ip": "0.0.0.0",
  "server_port": 443,
  "network": "tcp|ws|grpc|...",
  "networkSettings": {},
  "base_config": {
    "push_interval": 60,
    "pull_interval": 60
  },
  "routes": [],
  "custom_outbounds": [],
  "custom_routes": [],
  "cert_config": {}
}
```

协议常见追加字段：
- `shadowsocks`: `cipher`, `plugin`, `plugin_opts`, `server_key`
- `vmess`: `tls`, `multiplex`
- `trojan`: `host`, `server_name`, `tls`, `tls_settings`, `multiplex`
- `vless`: `tls`, `flow`, `decryption`, `tls_settings`, `multiplex`
- `hysteria`: `version`, `host`, `server_name`, `up_mbps`, `down_mbps`, `obfs`, `obfs-password`
- `tuic`: `version`, `server_name`, `congestion_control`, `tls_settings`, `auth_timeout`, `zero_rtt_handshake`, `heartbeat`
- `anytls`: `server_name`, `padding_scheme`

## V1 Guest

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `GET /api/v1/guest/plan/fetch` | `StandardSuccess<PlanResource[]>` | `StandardFail` |
| `POST /api/v1/guest/telegram/webhook` | 空响应体，`200` | `StandardFail`，常见为 `401` |
| `GET/POST /api/v1/guest/payment/notify/{method}/{uuid}` | 可能是 `StandardFail`，也可能是纯文本 `"success"`，也可能是支付插件自定义返回 | 失败时通常 `StandardFail` |
| `GET /api/v1/guest/comm/config` | `StandardSuccess<{ tos_url, is_email_verify, is_invite_force, email_whitelist_suffix, is_captcha, captcha_type, recaptcha_site_key, recaptcha_v3_site_key, recaptcha_v3_score_threshold, turnstile_site_key, app_description, app_url, logo, is_recaptcha }>` | `StandardFail` |

## V1 Passport

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `POST /api/v1/passport/auth/register` | `StandardSuccess<AuthData>` | `StandardFail` |
| `POST /api/v1/passport/auth/login` | `StandardSuccess<AuthData>` | `StandardFail` |
| `GET /api/v1/passport/auth/token2Login` | 分支 1: `302` 跳转；分支 2: `BareData<AuthData>` | 参数错误时 `{"message":"Invalid request"}` 或 `{"message":"Token error"}` |
| `POST /api/v1/passport/auth/forget` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/passport/auth/getQuickLoginUrl` | `StandardSuccess<string>` | 未授权时 `401`，格式为 `{"message":[401001,"..."]}` 或 `{"message":[401200,"..."]}` |
| `POST /api/v1/passport/auth/loginWithMailLink` | `StandardSuccess<string|object>` | `StandardFail` |
| `POST /api/v1/passport/comm/sendEmailVerify` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/passport/comm/pv` | `StandardSuccess<true>` | `StandardFail` |

## V1 User

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `GET /api/v1/user/resetSecurity` | `StandardSuccess<string>`，即新的订阅地址 | `StandardFail` |
| `GET /api/v1/user/info` | `StandardSuccess<{ email, transfer_enable, last_login_at, created_at, banned, remind_expire, remind_traffic, expired_at, balance, commission_balance, plan_id, discount, commission_rate, telegram_id, uuid, avatar_url }>` | `StandardFail` |
| `POST /api/v1/user/changePassword` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/user/update` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v1/user/getSubscribe` | `StandardSuccess<{ plan_id, token, expired_at, u, d, transfer_enable, email, uuid, device_limit, speed_limit, next_reset_at, plan?, subscribe_url, reset_day }>` | `StandardFail` |
| `GET /api/v1/user/getStat` | `StandardSuccess<[pending_order_count, pending_ticket_count, invite_user_count]>` | `StandardFail` |
| `GET /api/v1/user/checkLogin` | `StandardSuccess<{ is_login: true, is_admin?: true }>` | `StandardFail` |
| `POST /api/v1/user/transfer` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/user/getQuickLoginUrl` | `StandardSuccess<string>` | `StandardFail` |
| `GET /api/v1/user/getActiveSession` | `StandardSuccess<SessionToken[]>` | `StandardFail` |
| `POST /api/v1/user/removeActiveSession` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/user/order/save` | `StandardSuccess<string>`，即 `trade_no` | `StandardFail` |
| `POST /api/v1/user/order/checkout` | `{"type": -1|0|1|2, "data": true|string|object}` | `StandardFail` |
| `GET /api/v1/user/order/check` | `StandardSuccess<number>`，即订单状态码 | `StandardFail` |
| `GET /api/v1/user/order/detail` | `StandardSuccess<OrderResource>`，可能附加 `try_out_plan_id`、`surplus_orders` | `StandardFail` |
| `GET /api/v1/user/order/fetch` | `StandardSuccess<OrderResource[]>` | `StandardFail` |
| `GET /api/v1/user/order/getPaymentMethod` | `StandardSuccess<Array<{ id, name, payment, icon, handling_fee_fixed, handling_fee_percent }>>` | `StandardFail` |
| `POST /api/v1/user/order/cancel` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v1/user/plan/fetch` | `StandardSuccess<PlanResource[]|PlanResource>` | `StandardFail` |
| `GET /api/v1/user/invite/save` | `StandardSuccess<boolean>` | `StandardFail` |
| `GET /api/v1/user/invite/fetch` | `StandardSuccess<{ codes: InviteCodeResource[], stat: [invite_user_count, commission_sum, uncheck_commission_balance, commission_rate, commission_balance] }>` | `StandardFail` |
| `GET /api/v1/user/invite/details` | `DataTotal<CommissionLogResource>` | 通常无统一失败壳子 |
| `GET /api/v1/user/notice/fetch` | `DataTotal<NoticeModel>` | 通常无统一失败壳子 |
| `POST /api/v1/user/ticket/reply` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/user/ticket/close` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/user/ticket/save` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v1/user/ticket/fetch` | `StandardSuccess<TicketResource[]|TicketResource>` | `StandardFail` |
| `POST /api/v1/user/ticket/withdraw` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v1/user/server/fetch` | `{"data": NodeResource[]}`，带 `ETag`，命中时返回 `304` 空体 | 无节点时仍是空数组 |
| `POST /api/v1/user/coupon/check` | `StandardSuccess<CouponModel>`，其中 `limit_plan_ids`、`limit_period` 已被格式化 | `StandardFail` |
| `POST /api/v1/user/gift-card/check` | `StandardSuccess<{ code_info: { code, template: { name, description, type, type_name, icon, background_image, theme_color }, status, status_name, expires_at, usage_count, max_usage, plan_info? }, reward_preview: object, can_redeem: boolean, reason: string|null }>` | `StandardFail` |
| `POST /api/v1/user/gift-card/redeem` | `StandardSuccess<{ message, rewards, invite_rewards, template_name }>` | `StandardFail` |
| `GET /api/v1/user/gift-card/history` | `DataPagination<{ id, code, template_name, template_type, template_type_name, rewards_given, invite_rewards, multiplier_applied, created_at }>` | 校验失败时框架默认校验 JSON |
| `GET /api/v1/user/gift-card/detail` | `StandardSuccess<{ id, code, template: { name, description, type, type_name, icon, theme_color }, rewards_given, invite_rewards, invite_user, user_level_at_use, plan_id_at_use, multiplier_applied, notes, created_at }>` | `StandardFail` |
| `GET /api/v1/user/gift-card/types` | `StandardSuccess<{ types: object }>` | `StandardFail` |
| `GET /api/v1/user/telegram/getBotInfo` | `StandardSuccess<{ username: string }>` | `StandardFail` |
| `GET /api/v1/user/comm/config` | `StandardSuccess<{ is_telegram, telegram_discuss_link, stripe_pk, withdraw_methods, withdraw_close, currency, currency_symbol, commission_distribution_enable, commission_distribution_l1, commission_distribution_l2, commission_distribution_l3 }>` | `StandardFail` |
| `POST /api/v1/user/comm/getStripePublicKey` | `StandardSuccess<string>` | `StandardFail` |
| `GET /api/v1/user/knowledge/fetch` | `StandardSuccess<KnowledgeResource|{ [category: string]: KnowledgeResource[] }>` | `StandardFail` |
| `GET /api/v1/user/knowledge/getCategory` | 路由存在，但控制器中无该方法 | 实际调用大概率 `500` |
| `GET /api/v1/user/stat/getTrafficLog` | `StandardSuccess<TrafficLogResource[]>` | `StandardFail` |

## V1 Server

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `GET /api/v1/server/UniProxy/config` | `NodeConfig`，带 `ETag`，命中时 `304` 空体 | 非统一壳子 |
| `GET /api/v1/server/UniProxy/user` | `{"users":[{ "id":1, "uuid":"...", "speed_limit":100, "device_limit":3 }]}`，带 `ETag` | 非统一壳子 |
| `POST /api/v1/server/UniProxy/push` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v1/server/UniProxy/alive` | `{"data": true}` | 解析失败时 `{"error":"Invalid online data"}` |
| `GET /api/v1/server/UniProxy/alivelist` | `{"alive": { "uid": ["1.1.1.1"] }}` | 非统一壳子 |
| `POST /api/v1/server/UniProxy/status` | `{"data": true, "code": 0, "message": "success"}` | 校验失败时为框架校验 JSON |
| `GET /api/v1/server/ShadowsocksTidalab/user` | `{"data":[{ "id":1, "port":443, "cipher":"aes-256-gcm", "secret":"uuid" }]}`，带 `ETag` | 非统一壳子 |
| `POST /api/v1/server/ShadowsocksTidalab/submit` | `{"ret":1,"msg":"ok"}` | 非统一壳子 |
| `GET /api/v1/server/TrojanTidalab/config` | 原始 JSON 字符串，核心字段为 `run_type/local_addr/local_port/remote_addr/remote_port/password/ssl/api` | 失败时 `StandardFail` |
| `GET /api/v1/server/TrojanTidalab/user` | `{"msg":"ok","data":[{...用户原始字段..., "trojan_user":{"password":"uuid"}}]}`，带 `ETag` | 非统一壳子 |
| `POST /api/v1/server/TrojanTidalab/submit` | `{"ret":1,"msg":"ok"}` | 非统一壳子 |

## V1 Client

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `GET /api/v1/client/subscribe` | 非 JSON；返回订阅文本，具体格式取决于客户端协议类 | 不可用时 `403` 空文本 |
| `GET /{subscribe_path}/{token}` | 同上 | 同上 |
| `GET /api/v1/client/app/getConfig` | 非 JSON；返回 Clash YAML 文本 | 非统一壳子 |
| `GET /api/v1/client/app/getVersion` | `StandardSuccess<{ windows_version, windows_download_url, macos_version, macos_download_url, android_version, android_download_url }>`；对旧 UA 会退化为 `{ version, download_url }` | `StandardFail` |

## V2 Passport / User / Client / Server

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `/api/v2/passport/*` | 与对应 `/api/v1/passport/*` 完全相同 | 同 V1 |
| `GET /api/v2/user/resetSecurity` | 与 `/api/v1/user/resetSecurity` 相同 | 同 V1 |
| `GET /api/v2/user/info` | 与 `/api/v1/user/info` 相同 | 同 V1 |
| `GET /api/v2/client/app/getConfig` | `{"data": { app_info, features, ui_config, business_rules, server_config, security_config, payment_config, notification_config, cache_config, last_updated, config_hash }}` | 非统一壳子 |
| `GET /api/v2/client/app/getVersion` | 与 `/api/v1/client/app/getVersion` 相同 | 同 V1 |
| `POST /api/v2/server/handshake` | `{"websocket":{"enabled":true,"ws_url":"wss://example.com:8076"}}` 或 `{"websocket":{"enabled":false}}` | 非统一壳子 |
| `POST /api/v2/server/report` | `{"data": true}` | 非统一壳子 |
| 其余 `/api/v2/server/config|user|push|alive|alivelist|status` | 与对应 `/api/v1/server/UniProxy/*` 相同 | 同 V1 |

## V2 Admin - Config / Plan / Server

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `GET /api/v2/{admin_secure_path}/config/fetch` | `StandardSuccess<ConfigMappings>`；带 `key` 时仅返回单组 | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/config/save` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/config/getEmailTemplate` | `StandardSuccess<string[]>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/config/getThemeTemplate` | `StandardSuccess<string[]>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/config/setTelegramWebhook` | `StandardSuccess<{ success: true, webhook_url: string, webhook_base_url: string|null }>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/config/testSendMail` | `{"data": <MailLogModel>}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/plan/fetch` | `StandardSuccess<PlanModel[]>`，每项额外带 `group/users_count/active_users_count` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/plan/save` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/plan/drop` | `StandardSuccess<boolean>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/plan/update` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/plan/sort` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/server/group/fetch` | `StandardSuccess<ServerGroupModel[]>`，含 `users_count/server_count` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/group/save` | `StandardSuccess<boolean>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/group/drop` | `StandardSuccess<boolean>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/server/route/fetch` | `{"data": <ServerRouteModel[]>}` | 非统一壳子 |
| `POST /api/v2/{admin_secure_path}/server/route/save` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/route/drop` | `{"data": true}` | 失败时 `StandardFail` |
| `GET /api/v2/{admin_secure_path}/server/manage/getNodes` | `StandardSuccess<ServerModel[]>`，附加 `groups/parent/last_check_at/last_push_at/online/is_online/available_status/cache_key/load_status/metrics/online_conn` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/sort` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/update` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/save` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/drop` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/copy` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/batchDelete` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/resetTraffic` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/server/manage/batchResetTraffic` | `StandardSuccess<true>` | `StandardFail` |

`ConfigMappings` 的顶层 key 为：
- `invite`
- `site`
- `subscribe`
- `server`
- `email`
- `telegram`
- `app`
- `safe`
- `subscribe_template`

## V2 Admin - Order / User / Stat

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `ANY /api/v2/{admin_secure_path}/order/fetch` | `Paginate<OrderModel>`；每项多出 `plan`，且 `period` 已转换成旧字段名 | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/order/update` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/order/assign` | `StandardSuccess<string>`，即 `trade_no` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/order/paid` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/order/cancel` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/order/detail` | `StandardSuccess<OrderModel>`，含 `user/plan/commission_log/invite_user/surplus_orders/period` | `StandardFail` |
| `ANY /api/v2/{admin_secure_path}/user/fetch` | `Paginate<AdminUser>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/user/update` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/user/getUserInfoById` | `StandardSuccess<UserModel>`，已加载 `invite_user` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/user/generate` | 单个生成: `StandardSuccess<true>`；批量生成 JSON: `{"code":0,"message":"批量生成成功","data":[{ email, password, expired_at, uuid, created_at, subscribe_url }]}`；也可能返回 CSV 文件 | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/user/dumpCSV` | 非 JSON；CSV 文件流 | 参数错误时 `StandardFail` |
| `POST /api/v2/{admin_secure_path}/user/sendMail` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/user/ban` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/user/resetSecret` | `StandardSuccess<boolean>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/user/setInviteUser` | 路由存在，但控制器无方法 | 实际调用大概率 `500` |
| `POST /api/v2/{admin_secure_path}/user/destroy` | `StandardSuccess<true>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/stat/getOverride` | `{"data": { month_income, month_register_total, ticket_pending_total, commission_pending_total, day_income, last_month_income, commission_month_payout, commission_last_month_payout, online_nodes, online_devices, online_users, today_traffic, month_traffic, total_traffic }}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/stat/getStats` | `{"data": { todayIncome, dayIncomeGrowth, currentMonthIncome, lastMonthIncome, monthIncomeGrowth, lastMonthIncomeGrowth, currentMonthCommissionPayout, lastMonthCommissionPayout, commissionGrowth, commissionPendingTotal, currentMonthNewUsers, totalUsers, activeUsers, userGrowth, onlineUsers, onlineDevices, ticketPendingTotal, onlineNodes, todayTraffic, monthTraffic, totalTraffic }}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/stat/getServerLastRank` | `StandardSuccess<array>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/stat/getServerYesterdayRank` | `StandardSuccess<array>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/stat/getOrder` | `{"code":0,"message":"success","data":{"list":[...],"summary":{...}}}` | 非统一壳子 |
| `ANY /api/v2/{admin_secure_path}/stat/getStatUser` | `{"data":[<StatUserModel>],"total":100}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/stat/getRanking` | 路由存在，但控制器无方法 | 实际调用大概率 `500` |
| `GET /api/v2/{admin_secure_path}/stat/getStatRecord` | `{"data": <service_result>}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/stat/getTrafficRank` | `{"timestamp":"2026-04-18T00:00:00+00:00","data":[{ id, name, value, previousValue, change, timestamp }]}` | 非统一壳子 |

`AdminUser` 为 `User` 原始字段加：

```json
{
  "balance": 12.34,
  "commission_balance": 1.23,
  "subscribe_url": "https://example.com/s/xxxxx",
  "plan": {
    "id": 1,
    "name": "套餐"
  },
  "invite_user": {
    "id": 2,
    "email": "a@example.com"
  },
  "group": {
    "id": 1,
    "name": "默认组"
  },
  "total_used": 123456789
}
```

## V2 Admin - Notice / Ticket / Coupon / Knowledge

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `GET /api/v2/{admin_secure_path}/notice/fetch` | `StandardSuccess<NoticeModel[]>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/notice/save` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/notice/update` | 路由存在，但控制器无方法 | 实际调用大概率 `500` |
| `POST /api/v2/{admin_secure_path}/notice/drop` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/notice/show` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/notice/sort` | `StandardSuccess<true>` | `StandardFail` |
| `ANY /api/v2/{admin_secure_path}/ticket/fetch` | 详情模式: `StandardSuccess<TicketModel>`，含 `messages/user`；列表模式: `{"data":[<TicketModel+user>],"total":100}` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/ticket/reply` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/ticket/close` | `StandardSuccess<true>` | `StandardFail` |
| `ANY /api/v2/{admin_secure_path}/coupon/fetch` | `Paginate<CouponModel>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/coupon/generate` | 单个/编辑时 `StandardSuccess<true>`；批量生成时直接输出 CSV 文本 | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/coupon/drop` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/coupon/show` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/coupon/update` | 源码成功路径未 `return`，实际大概率是 `200` 空响应体 | 失败时 `StandardFail` |
| `GET /api/v2/{admin_secure_path}/knowledge/fetch` | `StandardSuccess<KnowledgeModel[]|KnowledgeModel>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/knowledge/getCategory` | `StandardSuccess<string[]>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/knowledge/save` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/knowledge/show` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/knowledge/drop` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/knowledge/sort` | `StandardSuccess<true>` | `StandardFail` |

## V2 Admin - Gift Card / Payment

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `ANY /api/v2/{admin_secure_path}/gift-card/templates` | `Paginate<GiftCardTemplateModel>`；源码中自定义映射结果未真正返回 | 校验失败时为框架校验 JSON |
| `POST /api/v2/{admin_secure_path}/gift-card/create-template` | `StandardSuccess<GiftCardTemplateModel>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/gift-card/update-template` | `StandardSuccess<GiftCardTemplateModel>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/gift-card/delete-template` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/gift-card/generate-codes` | JSON 模式: `StandardSuccess<{ batch_id, count, message }>`；导出模式: CSV 文件流 | `StandardFail` |
| `ANY /api/v2/{admin_secure_path}/gift-card/codes` | `Paginate<GiftCardCodeModel>`；源码中自定义映射结果未真正返回 | 校验失败时为框架校验 JSON |
| `POST /api/v2/{admin_secure_path}/gift-card/toggle-code` | `StandardSuccess<{ message }>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/gift-card/export-codes` | 非 JSON；纯文本下载，每行一个 code | 校验失败时为框架校验 JSON |
| `POST /api/v2/{admin_secure_path}/gift-card/update-code` | `StandardSuccess<GiftCardCodeModel>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/gift-card/delete-code` | `StandardSuccess<{ message }>` | `StandardFail` |
| `ANY /api/v2/{admin_secure_path}/gift-card/usages` | `Paginate<GiftCardUsageModel|mapped_item>` | 校验失败时为框架校验 JSON |
| `ANY /api/v2/{admin_secure_path}/gift-card/statistics` | `StandardSuccess<{ total_stats, daily_usages, type_stats }>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/gift-card/types` | `StandardSuccess<object>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/payment/fetch` | `StandardSuccess<PaymentModel[]>`，每项附加 `notify_url` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/payment/getPaymentMethods` | `StandardSuccess<string[]>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/payment/getPaymentForm` | `StandardSuccess<array>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/payment/save` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/payment/drop` | `StandardSuccess<boolean>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/payment/show` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/payment/sort` | `StandardSuccess<true>` | `StandardFail` |

## V2 Admin - System / Theme / Plugin / Traffic Reset

| 接口 | 成功返回 | 失败/特殊返回 |
| --- | --- | --- |
| `GET /api/v2/{admin_secure_path}/system/getSystemStatus` | `StandardSuccess<{ schedule: boolean, horizon: boolean, schedule_last_runtime: mixed }>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/system/getQueueStats` | `StandardSuccess<{ failedJobs, jobsPerMinute, pausedMasters, periods, processes, queueWithMaxRuntime, queueWithMaxThroughput, recentJobs, status, wait }>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/system/getQueueWorkload` | `StandardSuccess<array>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/system/getQueueMasters` | 返回体由 Laravel Horizon 原生控制器决定；`reference/Xboard` 中未定义 | 无法仅凭仓库精确静态还原 |
| `GET /api/v2/{admin_secure_path}/system/getHorizonFailedJobs` | `{"data":[...],"total":100,"current":1,"page_size":20}` | 非统一壳子 |
| `ANY /api/v2/{admin_secure_path}/system/getAuditLog` | `{"data":[<AdminAuditLogModel>],"total":100}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/theme/getThemes` | `StandardSuccess<{ themes: string[], active: string }>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/theme/upload` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/theme/delete` | `StandardSuccess<true>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/theme/saveThemeConfig` | `StandardSuccess<object>` | `StandardFail` |
| `POST /api/v2/{admin_secure_path}/theme/getThemeConfig` | `StandardSuccess<object>` | `StandardFail` |
| `GET /api/v2/{admin_secure_path}/plugin/types` | `{"data":[{ value, label, description, icon }]}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/plugin/getPlugins` | `{"data":[{ code, name, version, description, author, type, is_installed, is_enabled, is_protected, can_be_deleted, config, readme, need_upgrade }]}` | 非统一壳子 |
| `POST /api/v2/{admin_secure_path}/plugin/upload` | `{"message":"插件上传成功"}` | 失败时 `400 {"message":"..."}` |
| `POST /api/v2/{admin_secure_path}/plugin/delete` | `{"message":"插件删除成功"}` | `400/403 {"message":"..."}` |
| `POST /api/v2/{admin_secure_path}/plugin/install` | `{"message":"插件安装成功"}` | `400 {"message":"..."}` |
| `POST /api/v2/{admin_secure_path}/plugin/uninstall` | `{"message":"插件卸载成功"}` | `400 {"message":"..."}` |
| `POST /api/v2/{admin_secure_path}/plugin/enable` | `{"message":"插件启用成功"}` | `400 {"message":"..."}` |
| `POST /api/v2/{admin_secure_path}/plugin/disable` | `{"message":"插件禁用成功"}` | 通常无统一失败壳子 |
| `GET /api/v2/{admin_secure_path}/plugin/config` | `{"data": { ...plugin_config }}` | `400 {"message":"..."}` |
| `POST /api/v2/{admin_secure_path}/plugin/config` | `{"message":"配置更新成功"}` | `400 {"message":"..."}` |
| `POST /api/v2/{admin_secure_path}/plugin/upgrade` | `{"message":"插件升级成功"}` | `400 {"message":"..."}` |
| `GET /api/v2/{admin_secure_path}/traffic-reset/logs` | `DataPagination<{ id, user_id, user_email, reset_type, reset_type_name, reset_time, old_traffic, new_traffic, trigger_source, trigger_source_name, metadata, created_at }>` | 校验失败时为框架校验 JSON |
| `GET /api/v2/{admin_secure_path}/traffic-reset/stats` | `{"data": { total_resets, auto_resets, manual_resets, cron_resets }}` | 非统一壳子 |
| `GET /api/v2/{admin_secure_path}/traffic-reset/user/{userId}/history` | `{"data": { user: { id, email, reset_count, last_reset_at, next_reset_at }, history: [{ id, reset_type, reset_type_name, reset_time, old_traffic, trigger_source, trigger_source_name, metadata }] }}` | 非统一壳子 |
| `POST /api/v2/{admin_secure_path}/traffic-reset/reset-user` | `{"message":"...","data": { user_id, email, reset_time, next_reset_at }}` | 失败时 `400/500 {"message":"..."}` |

## 已知源码级异常点

| 接口 | 源码现状 | 影响 |
| --- | --- | --- |
| `/api/v1/user/knowledge/getCategory` | 路由存在，控制器无方法 | 实际调用大概率 500 |
| `/api/v2/{admin_secure_path}/user/setInviteUser` | 路由存在，控制器无方法 | 实际调用大概率 500 |
| `/api/v2/{admin_secure_path}/stat/getRanking` | 路由存在，控制器无方法 | 实际调用大概率 500 |
| `/api/v2/{admin_secure_path}/notice/update` | 路由存在，控制器无方法 | 实际调用大概率 500 |
| `/api/v2/{admin_secure_path}/coupon/update` | 成功路径没有显式 `return` | 可能返回 `200` 空响应体 |
| `/api/v2/{admin_secure_path}/gift-card/templates` | 代码构造了映射后的 `$data`，但最终返回的是原始 paginator | 文档按“原始模型分页”处理 |
| `/api/v2/{admin_secure_path}/gift-card/codes` | 同上 | 文档按“原始模型分页”处理 |
| `/api/v2/{admin_secure_path}/system/getQueueMasters` | 指向 Horizon 外部控制器 | 仅能标记为“仓库外定义” |