API
默认模板已注册的 API 路径、请求方法和访问要求。
默认模板在 src/api/routes.ts 中集中注册 API。普通业务接口使用 /api 前缀，内置 OAuth 2.0 服务使用 /oauth 前缀。
通用响应
src/types.ts 提供了 APIResponse<T>，下表描述该类型的约定。当前业务接口并未全部采用这个完整结构，部分成功响应只返回 success 和 data，全局异常处理也可能不返回 error。调用时应以具体接口的响应为准，不能假定所有响应都有下表标记为必填的字段。OAuth 2.0 Token 等协议接口按 OAuth 2.0 规范返回自己的响应结构，不使用这一封装。
成功响应
Prop
Type
失败响应
Prop
Type
/api/auth
认证路由由 src/core/services/auth/const.ts 和 src/core/services/auth/routes.tsx 注册。
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /api/auth/logout | 退出当前账号 |
GET | /api/auth/step-up/status | 查询敏感操作的二次验证状态 |
POST | /api/auth/step-up/challenge | 发起二次验证 |
POST | /api/auth/step-up/verify | 完成二次验证 |
POST | /api/auth/login | 登录 |
POST | /api/auth/login-modal | 在弹窗流程中登录 |
POST | /api/auth/google-one-tap | 处理 Google One Tap 登录 |
POST | /api/auth/signup | 注册账号 |
POST | /api/auth/verify-email | 提交邮箱验证码 |
POST | /api/auth/resend-email | 重新发送邮箱验证码 |
POST | /api/auth/setup-2fa | 完成双重验证设置 |
POST | /api/auth/verify-2fa | 校验双重验证码 |
POST | /api/auth/verify-recovery-code | 校验恢复码 |
POST | /api/auth/forgot-password | 发起密码重置 |
POST | /api/auth/reset-password | 设置新密码 |
POST | /api/auth/reset-password/verify-email | 在密码重置流程中校验邮箱验证码 |
POST | /api/auth/reset-password/verify-2fa | 在密码重置流程中校验双重验证码 |
POST | /api/auth/reset-password/verify-recovery-code | 在密码重置流程中校验恢复码 |
GET | /api/auth/oauth2/github | 处理 GitHub OAuth 回调 |
GET | /api/auth/oauth2/google | 处理 Google OAuth 回调 |
GET | /api/auth/current-user | 返回当前登录用户 |
生产环境会根据 src/core/services/auth/const.ts 中的 middlewares 配置，为登录、注册、验证码和密码重置等接口加载拦截或限流中间件。每项认证操作使用哪些中间件，以各自的配置为准。
/api/account
这些接口供登录用户管理个人资料、安全设置、产品、支付、联盟推广和站内通知。
资料和安全
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /api/account/profile | 更新姓名等个人资料 |
GET | /api/account/profile/email-verification | 查询修改邮箱流程的验证状态 |
POST | /api/account/profile/send-update-email | 发送修改邮箱所需的验证码 |
POST | /api/account/security/initiate-2fa | 开始设置双重验证 |
POST | /api/account/security/enable-2fa | 启用双重验证 |
POST | /api/account/security/disable-2fa | 停用双重验证 |
POST | /api/account/security/regenerate-recovery-codes | 重新生成恢复码 |
GET | /api/account/security/delete-account | 查询注销账号所需信息 |
POST | /api/account/security/delete-account | 注销当前账号 |
产品、支付和菜单
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /api/account/products | 返回当前用户可见的产品信息 |
GET | /api/account/payments | 返回当前用户的购买和订阅信息 |
GET | /api/account/menu-indicators | 返回账号菜单的提示数量 |
联盟推广
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /api/account/affiliate | 返回当前用户的联盟推广概况 |
GET | /api/account/affiliate/commission-summary | 返回佣金汇总 |
GET | /api/account/affiliate/invalid-commissions | 返回未计入结算的佣金 |
POST | /api/account/affiliate/email-verification | 为启用联盟推广校验邮箱 |
POST | /api/account/affiliate/enable | 启用联盟推广 |
GET | /api/account/affiliate/payout-profile | 读取收款资料 |
POST | /api/account/affiliate/payout-profile | 保存收款资料 |
站内通知
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /api/account/notifications | 返回当前用户的通知列表 |
POST | /api/account/notifications/read | 把通知标记为已读 |
POST | /api/account/notifications/:notificationId/open | 记录通知已打开 |
支付、工单和邮件订阅
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /api/payments/checkout/:productId/:planId | 创建支付结账会话 |
POST | /api/payments/:provider/billing | 创建支付服务商的账单管理入口 |
POST | /api/webhooks/:provider | 接收支付服务商 Webhook |
POST | /api/ticket | 创建工单 |
GET | /api/ticket/:key | 按访问 Key 读取工单 |
POST | /api/ticket/:key/reply | 回复工单 |
POST | /api/ticket/:key/close | 关闭工单 |
POST | /api/newsletter/subscriptions | 订阅邮件列表 |
Webhook 不依赖浏览器登录态，但必须通过对应支付服务商的签名校验。:provider 的实际可用值由 config/payment.ts 中启用的支付服务商决定。
/api/analytics/collect
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /api/analytics/collect | 接收第一方访问统计数据 |
只有 config/deploy.ts 中的 analytics.enabled 为 true 时才会注册该路由；关闭后访问此路径会直接返回 404。
/oauth
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /oauth/token | 交换授权码或刷新 Token |
POST | /oauth/token/revoke | 撤销 Token |
POST | /oauth/authorize/consent | 确认授权请求 |
POST | /oauth/authorize/dismiss | 拒绝授权请求 |
GET | /oauth/current-user | 返回当前 OAuth 授权页使用的用户信息 |
这些接口属于默认模板内置的 OAuth 2.0 服务。OAuth 客户端、授权码和 Token 分别保存在 oauth_client、oauth_auth_code 和 oauth_token。
/api/dashboard
整个后台路由组都会先经过 requireDashboardAdmin 检查，未通过管理员校验的用户不能访问以下接口。
用户、角色和权益
| 路径前缀 | 支持的操作 |
|---|---|
/api/dashboard/users | 用户列表、搜索、详情、停用、启用、软删除和撤销会话 |
/api/dashboard/roles | 角色列表、创建、启用、停用和撤销 |
/api/dashboard/entitlements | 权益列表、创建、调整、启用、停用和刷新订阅周期 |
/api/dashboard/entitlement-events | 查询权益额度事件 |
支付和 OAuth 客户端
| 路径前缀 | 支持的操作 |
|---|---|
/api/dashboard/payments/subscriptions | 订阅列表和订阅详情 |
/api/dashboard/payments/purchases | 一次性购买列表和购买详情 |
/api/dashboard/oauth-clients | OAuth 客户端列表、创建、修改、启用、停用、删除和重新生成 Secret |
Reaction、工单和日志
| 路径前缀 | 支持的操作 |
|---|---|
/api/dashboard/reaction/events | Event 执行列表和详情 |
/api/dashboard/reaction/commands | Command 执行列表、详情和手动重试 |
/api/dashboard/tickets | 工单列表、详情、回复、修改消息、隐藏、取消隐藏和更新状态 |
/api/dashboard/logger/system | 查询系统日志 |
/api/dashboard/logger/audit | 查询审计日志 |
/api/dashboard/logger/alert | 查询告警日志 |
统计和联盟推广
| 路径前缀 | 支持的操作 |
|---|---|
/api/dashboard/stats | 用户、订阅、工单、Reaction 执行和日志的后台统计 |
/api/dashboard/analytics | 访问概况、事件、会话、性能、漏斗、筛选项和客户端 IP |
/api/dashboard/affiliates/users | 联盟用户列表、详情、佣金、停用和恢复 |
/api/dashboard/affiliates/payouts | 月度结算列表、概况、佣金、付款记录和重新汇总 |
后台统计查询和前端数据采集共用 analytics.enabled 开关。关闭访问统计后，/api/dashboard/analytics 下不会注册查询接口。
通知
| 路径前缀 | 支持的操作 |
|---|---|
/api/dashboard/notifications | 通知列表、创建、详情和状态更新 |
源码位置
| 内容 | 位置 |
|---|---|
| API 总入口 | src/api/routes.ts |
| 认证动作和路径 | src/core/services/auth/const.ts、src/core/services/auth/routes.tsx |
| 账号接口 | src/api/account/ |
| 后台接口 | src/api/dashboard/ |
| 支付接口 | src/api/payments/ |
| OAuth 2.0 服务 | src/api/oauth2-server/ |
| 请求参数校验 | 各接口目录中的 schema.ts 或路由文件 |