Gemini API の月額上限に当てた瞬間、有料ユーザーまで止まる — Project Spend Caps の影響範囲をプロジェクト分割で閉じ込める

// project-router.ts
// ユーザーのティアごとに、独立した GCP プロジェクトのキーへ振り分ける。
// 各プロジェクトには別々の Project Spend Cap を当てておく。
 
type Tier = "free" | "paid";
 
interface ProjectBinding {
  apiKey: string;       // プロジェクトごとに発行した API キー
  projectId: string;    // 観測・照合のためのラベル
  softBudgetUsd: number; // ソフト予算（後述。プラットフォーム上限より低く置く）
}
 
const PROJECTS: Record<Tier, ProjectBinding> = {
  free: {
    apiKey: process.env.GEMINI_KEY_FREE!,
    projectId: "myapp-free",
    softBudgetUsd: 25, // ハード上限 $30 に対し、手前の $25 で先に絞る
  },
  paid: {
    apiKey: process.env.GEMINI_KEY_PAID!,
    projectId: "myapp-paid",
    softBudgetUsd: 270, // ハード上限 $300 に対し $270 で警戒に入る
  },
};
 
export function resolveProject(tier: Tier): ProjectBinding {
  return PROJECTS[tier];
}

// cost.ts
// 100万トークンあたりの単価（USD）。最新の料金に合わせて更新する。
interface ModelPrice { inPerM: number; outPerM: number; }
 
const PRICES: Record<string, ModelPrice> = {
  "gemini-3.5-flash": { inPerM: 0.30, outPerM: 2.50 },
  "gemini-3-flash":   { inPerM: 0.15, outPerM: 0.60 },
  // 価格は必ず公式の Billing ドキュメントで確認して更新すること
};
 
interface UsageMetadata {
  promptTokenCount?: number;
  candidatesTokenCount?: number;
}
 
export function estimateCostUsd(model: string, usage: UsageMetadata): number {
  const p = PRICES[model];
  if (!p) return 0; // 未知モデルは 0 でなく別途アラートを上げる運用が望ましい
  const inTok = usage.promptTokenCount ?? 0;
  const outTok = usage.candidatesTokenCount ?? 0;
  return (inTok / 1_000_000) * p.inPerM + (outTok / 1_000_000) * p.outPerM;
}

// budget-gate.ts
import { resolveProject, type Tier } from "./project-router";
import { estimateCostUsd } from "./cost";
 
interface Counter {
  get(key: string): Promise<number>;
  add(key: string, delta: number): Promise<void>;
}
 
function monthKey(projectId: string): string {
  const now = new Date();
  const ym = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}`;
  return `spend:${projectId}:${ym}`;
}
 
export type Decision =
  | { action: "proceed"; model: string }
  | { action: "degrade"; model: string } // 下位モデルへ降格
  | { action: "serve_cache" }            // キャッシュ応答に切り替え
  | { action: "soft_block" };            // 丁重に待っていただく
 
export async function decideBeforeCall(
  tier: Tier,
  requestedModel: string,
  counter: Counter,
): Promise<Decision> {
  const proj = resolveProject(tier);
  const spent = await counter.get(monthKey(proj.projectId));
  const ratio = spent / proj.softBudgetUsd;
 
  if (ratio < 0.8) return { action: "proceed", model: requestedModel };
  if (ratio < 0.95) return { action: "degrade", model: "gemini-3-flash" };
  if (ratio < 1.0) return { action: "serve_cache" };
  return { action: "soft_block" };
}
 
// 呼び出し後に概算コストを積む
export async function recordCost(
  tier: Tier,
  model: string,
  usage: { promptTokenCount?: number; candidatesTokenCount?: number },
  counter: Counter,
): Promise<void> {
  const proj = resolveProject(tier);
  const cost = estimateCostUsd(model, usage);
  await counter.add(monthKey(proj.projectId), cost);
}

// reconcile.ts
// 1日1回などの頻度で、概算累計と請求の実値を突き合わせる。
// 請求側の実値は Cloud Billing の集計や、AI Studio の Spend 表示から取得する。
 
interface ReconcileInput {
  projectId: string;
  estimatedUsd: number; // 自前カウンタの当月累計
  billedUsd: number;    // 請求側の当月実値
  hardCapUsd: number;   // 当てている Project Spend Cap
}
 
export function reconcile(input: ReconcileInput): {
  divergencePct: number;
  alerts: string[];
} {
  const { estimatedUsd, billedUsd, hardCapUsd } = input;
  const base = Math.max(billedUsd, 1e-6);
  const divergencePct = Math.abs(estimatedUsd - billedUsd) / base * 100;
 
  const alerts: string[] = [];
  if (divergencePct > 15) {
    alerts.push(`推定と請求の乖離が ${divergencePct.toFixed(1)}% — 価格表か計装を点検`);
  }
  if (billedUsd / hardCapUsd > 0.85) {
    alerts.push(`請求実値がハード上限の ${(billedUsd / hardCapUsd * 100).toFixed(0)}% — 上限調整を検討`);
  }
  return { divergencePct, alerts };
}