Saavo

管理後台

管理員專用的 /dashboard。透過 admin 角色進入既有後台，再依產品需求擴充頁面，不必另外建立後台框架。

Saavo 範本內建完整的管理員主控台，涵蓋使用者、付款、角色、使用權益、客服案件、通知、聯盟行銷、統計與記錄等常見營運功能。

開發自己的產品時，通常不必重新建立後台。只要將管理員電子郵件地址加入設定，再使用該地址註冊並完成驗證，就能進入 /dashboard 使用既有管理功能。只有現有後台無法滿足業務需求時，才需要繼續新增管理頁面、路由與 API。

既有功能

範本初始化後，即可使用下列管理功能：

模組預設入口說明
總覽/dashboard營運統計
使用者/dashboard/users使用者管理
訂閱/dashboard/payments/subscriptions訂閱快照
單次購買/dashboard/payments/purchases單次購買快照
角色/dashboard/roles查看與手動調整角色
使用權益/dashboard/entitlement/list查看與手動授予權益
額度事件/dashboard/entitlement/events發放與消耗稽核
Reaction/dashboard/reaction/events、/dashboard/reaction/commands背景事件與命令執行
OAuth 用戶端/dashboard/oauth-server授權伺服器用戶端
客服案件/dashboard/tickets處理使用者案件
通知/dashboard/notifications向使用者發布站內通知
聯盟行銷使用者/dashboard/affiliates/users推薦使用者
聯盟行銷月結/dashboard/affiliates/payouts佣金結算審核
統計/dashboard/analytics/*第一方統計，受 analytics.enabled 控制
記錄/dashboard/logs/system、/alert、/audit系統、警示與稽核記錄

頁面入口統一為 /dashboard，相關 API 集中在 /api/dashboard/*，並透過統一的管理員驗證程序檢查權限。

管理後台總覽

先體驗管理後台

修改後台前，建議先使用管理員帳號，逐一操作現有模組。

  1. 將 config/base.ts 的 adminEmails 改為自己能接收驗證郵件的地址，或先使用預設的 admin@saavo.dev 在本機註冊。
  2. 管理員帳號也需要完成電子郵件驗證，取得管理員身分前，不會略過這項驗證流程。
  3. 開啟 /dashboard，確認能看到使用者、付款、客服案件等模組。
  4. 再使用一般帳號開啟相同位址，應被帶回首頁。

預設的管理員帳號建立流程如下：

將電子郵件地址寫入 adminEmails
↓
該帳號註冊並完成電子郵件驗證
↓
系統授予 admin 角色
↓
可以存取 /dashboard

非管理員存取後台頁面時，會被重新導向首頁或登入頁面。

提示

開發人員通常不必重新實作這些後台頁面。先確認管理員入口可用，再依產品需求新增少數管理功能即可。

設定管理後台

預設管理後台用來營運範本已有的模組。正式上線前，至少應確認由誰擔任管理員。

新增管理員

Saavo 透過 config/base.ts 的 adminEmails 設定管理員：

adminEmails: ['admin@your-domain.com'],

使用該電子郵件地址註冊帳號並完成驗證後，即可取得 admin 角色。地址必須完全相符，不會將 admin+test@example.com 視為 admin@example.com。

adminEmails 不會建立能略過身分驗證的超級帳號。管理員首先是一般使用者，只有已驗證的電子郵件地址與設定一致，才會取得管理員身分。

建議產品初始化後，及早建立自己的管理員帳號，並確認能正常進入後台。

隱藏不需要的管理模組

統計功能由 config/deploy.ts 的 analytics.enabled 控制。停用第一方統計後，後台就不會再顯示統計入口。

其他管理模組目前沒有獨立的後台頁面開關。即使產品暫時不使用客服案件、聯盟行銷或 OAuth 用戶端等功能，管理員仍可能看得到對應頁面。如果需要完全隱藏這些入口，可以調整 Dashboard 的導覽設定。

新增員工角色前，先設計權限

目前管理後台只接受 admin 角色。單純修改 roles.ts，不會讓新角色進入 /dashboard，也不會自動限制該角色可以操作哪些模組。

如果產品不需要權限分級，管理後台繼續使用 admin 即可，新增的管理 API 也使用相同驗證程序。如果確實需要員工分級，必須視為完整的授權需求處理，包括定義能力、調整伺服器端驗證程序、限制 API，以及驗證每個後台頁面。只透過前端隱藏入口來限制不同角色的存取，並不安全。

擴充管理後台

設定好管理員後，產品自己的管理功能應串接至既有的 /dashboard。你需要依業務需求，實作後台、前台與 API 的權限控制。

保護管理頁面

獨立的伺服器端頁面可參考 src/pages/dashboard.tsx，先通過權限檢查，再透過管理員驗證程序確認管理員身分。

const guardResult = authenticatedGuard(c);

if (!guardResult.success) {
    return c.redirect(
        getFullPath(guardResult.details?.redirectUrl as string, locale),
    );
}

if (!await authz.isAdmin(c)) {
    return c.redirect(getFullPath('/', locale));
}

完整範例請參考：

管理員頁面

保護管理 API

管理 API 使用 requireDashboardAdmin。掛載於 /api/dashboard 後，所有子路由都會自動受到保護：

dashboardApi.use('*', requireDashboardAdmin);

不要只在 React 元件中判斷 roles.includes('admin')。用戶端的角色清單只能控制顯示內容，不能作為安全邊界。

新增管理頁面

需要新管理功能時，沿用既有的 SPA 頁面呈現方式：

  1. 在 src/components/client/Dashboard/pages/ 新增頁面元件。
  2. 在 Dashboard/index.tsx 新增路由。
  3. 在 Dashboard/const.ts 新增導覽項目。
  4. 將對應 API 放在 src/api/dashboard/，自動使用管理員驗證程序。

如果只是查看或調整既有的使用者、角色、權益與付款資料，優先使用現有模組，不必另外建立列表頁面。如果確實需要新的列表頁面，則需自行實作權限控制。

上線檢查

後台是高權限入口，上線前建議至少確認：

  • adminEmails 已改為自己能完成驗證的地址，不再使用 admin@saavo.dev。
  • 管理員可以正常開啟 /dashboard，並看到預期模組。
  • 一般使用者存取 /dashboard 時，會被帶回首頁。
  • 一般使用者呼叫 /api/dashboard/* 時，會收到 401 或 403。
  • 新增的管理 API 已掛載於 dashboard 路由下，或明確使用 requireDashboardAdmin。
  • 若已停用統計，後台不再顯示統計選單。

建議使用新建立的管理員帳號與一般帳號分別測試，不要只依賴開發期間一直沿用的本機使用者。

常見問題

接下來

依接下來要開發的功能，可以繼續閱讀：

大多數產品完成本章後，只需要將管理員電子郵件地址改為自己的地址。

產品實際需要的管理功能，再依既有 Dashboard 的方式新增頁面即可。