原廠金鑰的 AI 花費：每租戶、每人一個美金額度，超過只擋 AI

開啟 mockup：設定區塊／AI 用量頁／額度用完時的畫面（深色主題、配色照 FE design tokens，三個分頁切換）

一句話：用原廠金鑰打 AI 的花費，每個租戶一天（或一個月）最多花多少美金、每個人最多花多少美金、每分鐘最多送幾次，超過就只擋 AI；另外給一頁看「這段期間花了多少、誰花的」。

依賴：.12 是地基（額度怎麼算、存在哪）；.13 的進度條與 .14 的彙總都讀 .12 定下的設定與算法，可在 .12 的設定格式定案後平行開工。決策者功課：裁 D-a 預設數字（其他待裁項都有建議，照建議即可開工）。

抄什麼：「金額＋週期」的欄位形狀、多層任一超就擋、次數用 429＋還要等幾秒、軟上限只告警不擋。不抄什麼：多一個 proxy 服務。我們已有自己的閘道與 ai_call_log，額度是在閘道上多一道檢查，不是再疊一層。

來源：https://docs.litellm.ai/docs/proxy/users、https://docs.litellm.ai/docs/proxy/team_budgets、https://docs.getbifrost.ai/features/governance/budget-and-limits

以下每一列都已開檔核對。

DEV 實測（本機 guidant_ai_dev，356 筆）：原廠鑰成功呼叫 306 筆全有美金估價；失敗 3 筆、被擋 47 筆估價為空（沒真的打到 AI，本來就不該計錢）。每次平均：小幫手 0.0015、儀表板挑圖 0.005＋排版 0.028（一次生成約 0.034）、分類每份 0.016 美金。今天花最多的一位測試帳號一天 3.68 美金。加總查詢實測走索引 0.1 毫秒。

設定存哪

system_configs 新群組 AI_QUOTA，兩個 key：

CONFIG 的值（JSONB）：

{
  "tenant_budget": {"usd": 5.00, "period": "day"},
  "user_budget":   {"usd": 1.00, "period": "day"},
  "user_rpm": 20,
  "warn_ratio": 0.8
}

• period 只能是 day／month。
• usd 填 0 ＝這一層不准用原廠鑰；不提供「無上限」（已裁：預設要保守）。平台管理員要給某租戶很大的額度，就填一個大數字。
• warn_ratio 先寫死 0.8，不在畫面上開。

🔵 預留（日後 SaaS）：license limits 將帶同一個形狀 {"ai_quota": {"tenant_budget": …, "user_budget": …, "user_rpm": …}}，當作「上限的上限」——生效值＝min(授權檔, CEILING, CONFIG)。這版不讀 license，只把欄位名定成一樣，日後接上不必轉換。

繼承規則

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart TB
  CODE["程式內建預設<br/>（ROOT 也沒設時的最後防線）"] --> ROOT
  ROOT["ROOT（tenant 1）AI_QUOTA/CONFIG<br/>＝全系統預設"] --> CEIL
  CEIL["該租戶 AI_QUOTA/CEILING<br/>平台管理員設；沒填＝ROOT 的值"] --> TEN
  TEN["該租戶 AI_QUOTA/CONFIG<br/>租戶管理員設；沒填＝上限值"] --> EFF
  EFF["生效額度<br/>＝min(上限, 租戶設定)"] --> T1["租戶層：本租戶全部人加總"]
  EFF --> U1["使用者層：每個人各自算<br/>（同一個數，不逐人設）"]
  EFF --> R1["每分鐘次數：每個人各自算"]
  LIC["license limits.ai_quota<br/>（預留，這版不讀）"] -. 日後 SaaS .-> CEIL

• 逐欄位往上找：租戶只填了租戶額度，每人額度與每分鐘次數照樣繼承上一層。
• 讀法照抄 resolve_retention()（租戶→ROOT→預設），用 read_tenant_config_value。
• 子租戶：只往 ROOT 繼承，不往父租戶繼承、也不把子租戶花費算進父租戶（D-i）。

算法：每次呼叫前加總（已裁）

-- 租戶層（使用者層多一個 AND user_id = :uid）
SELECT COALESCE(SUM(estimated_usd), 0)
  FROM public.ai_call_log
 WHERE tenant_id = :tid
   AND key_source IN ('root' /* , 'env' 見 D-j */)
   AND created_at >= :period_start;   -- 本地零點或月初，Python 端依 TZ 算好再傳入

• 為什麼可行：索引 (tenant_id, created_at DESC) 已在，一天的量是幾百筆等級，實測 0.1 毫秒；每次 AI 呼叫本身要數秒，多這一句看不出來。
• 為什麼不用 Redis 計數器：計數器要處理「零點歸零」「和紀錄表對不起來」「Redis 重啟歸零＝額度被重置」三件事，換來的只是省一句已經很快的查詢。
• 🔴 期間起點在 Python 端算好再傳，不要寫 date_trunc('day', now())：那是資料庫連線的時區，與應用容器的 TZ 不一定一樣，兩邊差 8 小時的症狀是「每天早上 8 點才歸零」，而且不會報錯。
• 讀法走「顯式指定租戶、繞 RLS」的 infra 查詢（與 read_tenant_config_value 同一個樣板），因為分類的背景工作沒有請求脈絡。
• 🔴 紀錄保留天數與月額度的交互：AI_CALL_LOG_RETENTION_DAYS 若被設成 31 天以下，月初的紀錄會先被清掉，月額度就少算。設定頁要擋「週期選月、保留天數 < 31」。
• 反悔條件：單一租戶日呼叫量上萬筆，或 SaaS 版多租戶共用一個資料庫、加總開始拖慢呼叫時，在 IQuotaCounter 的實作層換成 Redis 計數器＋每日對帳，閘道介面不動。

閘道介面要改的地方（碰 jedi-ai-gateway 套件）

依 CLAUDE.md 外部套件規範，這張改動要在實作卡的計畫裡列明、等決策者點頭；其他 consumer 只有主專案自己（三支 AI 功能都經主專案接線），風險低。

計數的 key 用 ai_rate:{tenant_id}:{user_id}，數值取生效設定的 user_rpm。Redis 掛掉照現有做法放行並記 warning。

兩個套件內寫死的上限值（10、3）退場後變成沒人用的預設值，留在套件裡不影響行為；下次動這兩支套件時順手刪掉。

三支功能收到閘道擋下時，本來就各有「被擋」的呈現通道，不必新造：

句子由閘道放進 GatewayBlockedError.reply，兩支 AI 套件都已經「有 reply 就原樣回」，所以套件不必改就能講清楚是哪一層、何時恢復。

• 不存告警事件、不另算：畫面要顯示時，呼叫一支「我目前的額度」API，回傳租戶層與本人層的「已用／額度／重置時間」，前端自己比 80%。
• 出現在哪：小幫手視窗頂端、動態儀表板生成區、證據分類送出鈕旁，黃條一行字（mockup 第③頁）。租戶管理員多一個「調整額度」連結。
• 何時重讀：進頁面時一次、每次 AI 呼叫完一次。不輪詢。
• 客戶自帶金鑰的租戶：API 回「不計額度」，畫面不顯示黃條也不顯示進度條。

• 估法：該租戶近 30 天分類每份的平均花費 × 這批份數；租戶沒有歷史就用全系統平均；再沒有就用常數 0.02 美金／份。
• 「明顯不夠」＝預估 > 剩餘額度 × 1.5（租戶層、本人層都比）。差一點的照送，跑到一半用完照上面處理。1.5 這個數字放進 D-a 一起裁。
• 擋下時的說法：「這批 67 份預估約 1.05 美金，你今天只剩 0.40 美金，請減少到約 25 份以內或明天再送。」（mockup 第③頁）

• 使用者分組要同時回 user_name（暱稱），照 CLAUDE.md 審計欄位規範在 app service 批次查。
• 功能分組把 ai-dashboard.select／ai-dashboard.layout 合成一列「動態儀表板」，可展開看兩段。

見 mockup 第①頁。重點：

• 放在現有「AI 服務設定」頁（AiServiceConfigForm.vue，253 行，加一塊不會超過 800 行上限；建議新區塊拆成獨立子元件）。
• 🔴 頁面權限要拆開：現在整頁鎖平台管理員（AI_SERVICE_CONFIG_PLATFORM_ADMIN_ONLY，路由、選單、頁面三處同引）。額度區塊要讓租戶管理員進得來、但金鑰區塊仍只有平台管理員看得到——路由與選單改成「有 storage-config.read 就進得來」，頁內金鑰區塊照舊用那個旗標藏起來。
• 沒填的欄位用灰字顯示繼承來的值；「還原為系統預設」＝清掉本租戶這一列。
• 輸入超過上限時，存檔被擋並說明「平台給本租戶的上限是 20.00 美金／日」。
• 用 PrimeVue InputNumber（兩位小數）＋ Dropdown（日／月）＋ ProgressBar；色彩用 design tokens，80% 以上用 --color-orange、滿了用 --color-red。

以下各項決策者已裁定照「我的建議」走，保留原文供查理由。原列的 D-b（license 關係）、D-c（加總或計數器）、D-d（週期邊界）、D-e（分類預估）已由決策者裁定，見已裁。

以下是裁完後要落進 design.md 的文字，本稿不改 design.md 本體，由下一棒照抄並依最終裁示調整。

§3.2 成本（第三階段）— 取代原表

共同前提：第一版設定存 system_configs，license limits 預留（欄位名 ai_quota 已對齊，日後 SaaS 當上限的上限）；只計原廠鑰（key_source 為 root／env，依 D-j）用量，客戶自帶金鑰不計也不擋；80% 告警只在畫面；分類批次送出前用歷史平均預估、明顯不夠整批先擋。

§6.3 第三階段：成本 — 取代原表

§7.3 第三階段驗收 — 取代原表