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 或路由檔案 |