升級建議設定
config/upgrade.ts 中的 OAuth 授權範圍升級規則、方案資訊和預設行為。
config/upgrade.ts 匯出 websiteScopeUpgradePolicies，伺服器端透過 getServerConfig().upgrade 讀取。它讓 OAuth 授權頁面能在特定角色或權益條件下，展示方案升級建議。
預設設定
import type { OAuthUpgradeRule } from '@/core/services/oauth2-server/types';
import type { Scope } from './scopes';
export const websiteScopeUpgradePolicies = {
} as const satisfies Partial<Record<Scope, OAuthUpgradeRule[]>>;目前生效的值是空物件。原始檔案中的註解只是示意，不是已啟用的產品或升級規則，不應直接取消註解使用。
物件的鍵對應 config/scopes.ts 中的 Scope，每個鍵的值是一組規則。可以不為某個 Scope 設定規則，但設定後，規則陣列不能是空陣列，每條規則的 upgradePlans 也至少要有一個項目。
規則欄位
| 欄位 | 型別 | 說明 |
|---|---|---|
id | string，選用 | 規則識別字，填寫時不能為空 |
description | LocalizedText，選用 | 規則說明 |
trigger | Condition | 比對使用者目前有效角色或權益的條件 |
upgradePlans | OAuthUpgradePlan[] | 符合條件時展示的方案 |
trigger 支援下列條件：
| 形式 | 意義 |
|---|---|
{ type: 'role', operator: 'in', values: [...] } | 使用者擁有列出的任一角色 |
{ type: 'role', operator: 'not_in', values: [...] } | 使用者不擁有列出的任何角色 |
{ type: 'entitlement', operator: 'has', values: [...] } | 使用者擁有列出的任一權益 |
{ type: 'entitlement', operator: 'not_has', values: [...] } | 使用者不擁有列出的任何權益 |
{ anyOf: [...] } | 至少一個子條件成立 |
{ allOf: [...] } | 全部子條件成立 |
{ noneOf: [...] } | 全部子條件都不成立 |
條件陣列不能留空。條件描述的是「何時提示升級」，例如要為尚未擁有某項權益的使用者顯示升級建議，應使用 not_has。
方案欄位
| 欄位 | 型別 | 說明 |
|---|---|---|
productId | ProductId | 產品 ID，引用 products.ts |
planId | 對應產品的方案 ID | 必須屬於該產品 |
title、description | LocalizedText | 方案標題和介紹 |
salePrice | string | 顯示價格，例如 $9.99 |
listPrice | string，選用 | 顯示原價 |
discountLabel | string，選用 | 折扣文案 |
billingLabel | string，選用 | 計費週期文案 |
recommended | boolean，選用 | 推薦標記 |
priority | 整數，選用 | 顯示優先順序 |
platforms | readonly string[]，選用 | 平台標籤 |
價格字串只控制顯示，不會建立或修改 Stripe Price，也不會改變 Checkout 的實際收費。產品、方案、付款價格和顯示文案需要一起檢查。
授權頁面如何使用
授權頁面會逐項讀取請求的 Scope。如果沒有設定升級規則，該 Scope 會進入可授權清單。如果符合規則並回傳方案，該 Scope 會進入需要升級的清單，同時展示方案資訊。沒有符合條件的方案時，該 Scope 仍可進入可授權清單。
同一個 Scope 中，多條規則找到相同的產品和方案時，比對函式會依產品與方案的組合去除重複項目，保留最先出現的方案資訊。
這份設定負責授權頁面的升級引導，不會自動授予角色或權益。業務 API 仍須檢查登入狀態、授權範圍和業務權限，購買後的權益則由付款流程處理。
修改後請執行 npm run typecheck，並分別使用符合與不符合條件的帳號檢查授權頁面。重新命名或刪除 Scope、角色、權益、產品、方案時，也要更新這裡的引用。