← 一覧に戻る

Phase 2a 運用基盤: バジェット管理 + 利用データ計測

Context

クローズドベータ（月¥5,000予算）を安全に運用するために、2つの仕組みが必要:

1. バジェット管理: 月間通話コストを把握し、予算超過で新規受付を自動停止
2. 利用データ計測: Phase 2.5 のシグナル判断（D7継続率・無料上限到達率）に必要なファネルデータを集計

どちらも既存テーブル（reminders / users）から集計。新テーブルは作らない。

TDD イテレーション

Iteration 36: バジェット計算の純関数（src/budget.ts）

新ファイル src/budget.ts + src/budget.test.ts

// 定数
export const CALL_COST_YEN = 13;
export const NUMBER_MONTHLY_FEE_YEN = 165;

// 月間コスト = リマインダー通話数 × ¥13 + ¥165
export function calculateMonthlyCost(reminderCalls: number): number

// コスト >= 実効予算 なら超過
// 実効予算 = budgetYen × SAFETY_MARGIN_RATIO（認証コール分のバッファ）
export const SAFETY_MARGIN_RATIO = 0.8;
export function isBudgetExceeded(cost: number, budgetYen: number): boolean

認証コールの扱い: verification call は既存データから正確にカウントできない（verification_request_count は認証成功時にリセットされ、再試行や番号変更も追跡不能）。新テーブル不要の方針のため、SAFETY_MARGIN_RATIO = 0.8（予算の20%を認証コール用に留保）で安全側に倒す。Admin stats では tracked（リマインダー通話のみ）と effective budget（80%適用後）を明示する。

テストケース:

• 0通話 → ¥165（固定費のみ）
• 100通話 → ¥1,465
• 境界値: コスト = budget × 0.8 → exceeded
• コスト < budget × 0.8 → not exceeded

Iteration 37: バジェット超過時にリマインダー登録 + 認証コールを拒否

変更ファイル: src/index.ts, wrangler.toml

• MONTHLY_BUDGET_YEN env var を追加（wrangler.toml の [vars] に "5000"）
• バジェットチェック関数を作成（DB集計 → isBudgetExceeded）
• 当月の通話数を集計するクエリ:

  SELECT COUNT(*) FROM reminders
  WHERE status IN ('calling','completed','unanswered')
  AND called_at >= ?  -- 当月1日 0:00 JST の unix timestamp
  

• 2箇所でバジェットチェック:
  1. 電話番号登録フロー（認証コール前）: isPhoneNumber(text) 分岐の先頭でチェック。超過時は認証コールを発信せず「現在新規受付を停止しています」と返信
  2. リマインダー登録フロー（月間使用制限チェックの直前）: 超過時は「現在新規受付を停止しています」と返信
• オーナー / VIP は両方とも免除（既存の isUnlimited ロジックを拡張）

Iteration 38: /admin/stats エンドポイント（認証 + バジェット JSON）

変更ファイル: src/index.ts

• ADMIN_API_KEY は wrangler secret put で設定（wrangler.toml にコミットしない）
• worker-configuration.d.ts の Env に ADMIN_API_KEY を手動追加（wrangler types では secret は出力されない）
• GET /admin/stats エンドポイント追加
• Bearer 認証: Authorization: Bearer <ADMIN_API_KEY>
• ADMIN_API_KEY 未設定 → 404（エンドポイントの存在を隠す）
• 認証失敗 → 401
• レスポンス:

  {
    "budget": {
      "reminderCalls": 42,
      "trackedCost": 711,
      "budgetTotal": 5000,
      "effectiveBudget": 4000,
      "remaining": 3289,
      "exceeded": false
    }
  }
  

  • trackedCost: リマインダー通話のみ（認証コールは含まない）
  • effectiveBudget: budgetTotal × 0.8（認証コール用20%留保後）
  • remaining: effectiveBudget - trackedCost

Iteration 39: /admin/stats にファネルメトリクス追加

変更ファイル: src/index.ts

既存テーブルから集計するクエリ:

メトリクス	説明	クエリ
phoneSubmitted	電話番号を送信したユーザー数	SELECT COUNT(*) FROM users
verified	電話認証を完了したユーザー数	SELECT COUNT(*) FROM users WHERE phone_verified = 1
hasUsed	1回以上リマインダーを作成したユーザー数	SELECT COUNT(DISTINCT line_user_id) FROM reminders
retainedD7	登録7日以上前のユーザーで、登録日+7日以降にもリマインダーを作成した数	下記参照
quotaReached	無料枠（3回）に到達したユーザー数（オーナー/VIP除外）	下記参照

注意: phoneSubmitted は友達追加しただけのユーザーを含まない（users テーブルは電話番号送信時に初めてINSERTされるため）。真のファネル起点（友達追加数）の計測には follow イベントのハンドリングが必要（Phase 2a 機能実装の「LINE イベント型の厳密化」で対応予定）。

quotaReached クエリ（実際の制限ロジックと完全に一致）:

実際のコード: effectiveCalls = (month_key === currentMonth ? calls_this_month : 0) + pendingCount >= 3 → 月跨ぎ時は calls_this_month を0にリセット。オーナー/VIPは免除。

quotaReached は JS で計算する（オーナー/VIPのフィルタリングに env var が必要なため、純SQLでは完結しない）:

1. 全 verified ユーザーと pending 件数を取得
2. JS でオーナー/VIP を除外
3. effectiveCalls + pendingCount >= 3 でフィルタ
4. カウントを返す

レスポンスに funnel フィールドを追加:

{
  "budget": { ... },
  "funnel": {
    "phoneSubmitted": 50,
    "verified": 35,
    "hasUsed": 28,
    "retainedD7": 12,
    "quotaReached": 8
  }
}

関連ファイル

ファイル	役割
src/index.ts	webhook + cron + admin エンドポイント
src/index.test.ts	統合テスト
src/budget.ts	バジェット計算純関数（新規）
src/budget.test.ts	バジェット計算テスト（新規）
wrangler.toml	env var 追加
schema.sql	変更なし

設計判断

• 新テーブル不要: reminders.called_at でリマインダー通話数を集計、users + reminders の既存データでファネル算出
• verification call は直接追跡不能: verification_request_count は認証成功時にリセットされ、再試行・番号変更も既存データから正確にカウントできない。SAFETY_MARGIN_RATIO = 0.8 で予算の20%を留保し安全側に倒す（Codex P1 指摘対応）
• quotaReached は pending 込み: 実際の制限ロジック（calls_this_month + pending >= 3）と一致させる（Codex P2 指摘対応）
• オーナー/VIP 免除: バジェット超過時もオーナー・VIPはリマインダー登録可能
• cron は止めない: バジェット超過でも既存の予約済みリマインダーは実行する（"新規受付停止" のみ）
• 当月の起点: JST の月初（getCurrentMonthKey() と同じロジック）
• ADMIN_API_KEY はシークレット: wrangler secret put で設定。wrangler.toml にコミットしない
• 認証コールもバジェットで制御: 予算超過時は verification call も止める（Codex P1 指摘）

検証

tsc --noEmit && pnpm test

全4イテレーション完了後、~/bin/codex-full review で Codex レビュー → LGTM まで修正。