diff --git a/docs/adr/0012-agent-model-switching-and-prepaid-billing.md b/docs/adr/0012-agent-model-switching-and-prepaid-billing.md index f007c9fb..c429bced 100644 --- a/docs/adr/0012-agent-model-switching-and-prepaid-billing.md +++ b/docs/adr/0012-agent-model-switching-and-prepaid-billing.md @@ -2,7 +2,7 @@ ## ステータス -Accepted +Superseded by ADR-0023 ## コンテキスト @@ -113,3 +113,7 @@ DevForge Agent（ADR-0010）の LLM モデルは `claude-haiku-4-5` をハード - `.claude/rules/backend/agent.md`（Agent 実装の不変条件） - Stripe Checkout: https://docs.stripe.com/payments/checkout - Stripe Webhook 署名検証: https://docs.stripe.com/webhooks#verify-official-libraries + +--- + +2026-07-21: 機能整理（#517）でプリペイド課金・マルチプロバイダを撤去し Haiku 無料一本化 + レート制限へ縮退したため、[ADR-0023](0023-remove-billing-multiprovider.md) で Superseded とした。 diff --git a/docs/adr/0013-multi-provider-llm-selection.md b/docs/adr/0013-multi-provider-llm-selection.md index 29b7fb18..57e69b58 100644 --- a/docs/adr/0013-multi-provider-llm-selection.md +++ b/docs/adr/0013-multi-provider-llm-selection.md @@ -2,7 +2,7 @@ ## ステータス -Accepted +Superseded by ADR-0023 ## コンテキスト @@ -68,3 +68,7 @@ ADR-0010 の原則は維持する（切替キーがグローバル env → alias - ADR-0010（DevForge Agent）/ ADR-0012（モデル切り替えとプリペイド課金） - `backend/app/services/agent/llm/`（factory / 各 client）・`model_catalog.py`・`output_schema.py` + +--- + +2026-07-21: 機能整理（#517）でプリペイド課金・マルチプロバイダを撤去し Haiku 無料一本化 + レート制限へ縮退したため、[ADR-0023](0023-remove-billing-multiprovider.md) で Superseded とした。 diff --git a/docs/adr/0015-vertex-ai-for-gemini-anthropic.md b/docs/adr/0015-vertex-ai-for-gemini-anthropic.md index ec3c6c15..f7e29ac5 100644 --- a/docs/adr/0015-vertex-ai-for-gemini-anthropic.md +++ b/docs/adr/0015-vertex-ai-for-gemini-anthropic.md @@ -2,7 +2,7 @@ ## ステータス -Accepted +Superseded by ADR-0023 （ADR-0013 の認証部分「Gemini / OpenAI の API キーを Secret Manager で管理し Cloud Run に注入する」を更新する。プロバイダ抽象・モデルエイリアス・課金の仕組みは ADR-0013 を踏襲。） @@ -59,3 +59,7 @@ Cloud Run の SA には `roles/aiplatform.user` が既に付与済みで、IAM - `backend/app/core/{settings,env_keys}.py` / `infra/modules/cloud_run/main.tf` - [Claude on Vertex AI（model id 一覧）](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai) - [Anthropic Claude models | Vertex AI](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/partner-models/claude) + +--- + +2026-07-21: 機能整理（#517）でプリペイド課金・マルチプロバイダを撤去し Haiku 無料一本化 + レート制限へ縮退したため、[ADR-0023](0023-remove-billing-multiprovider.md) で Superseded とした。Gemini/OpenAI のマルチプロバイダ部分は撤去するが、**Anthropic を Vertex AI(ADC) で叩く中核判断（学習除外 + アジア圏データ所在）は ADR-0023 が継承する**。 diff --git a/docs/adr/0023-remove-billing-multiprovider.md b/docs/adr/0023-remove-billing-multiprovider.md new file mode 100644 index 00000000..8db93f32 --- /dev/null +++ b/docs/adr/0023-remove-billing-multiprovider.md @@ -0,0 +1,85 @@ +# ADR-0023: プリペイド課金・マルチプロバイダの撤去と Haiku 無料一本化 + +## ステータス + +Accepted + +## 関連 ADR + +- Supersedes: [ADR-0012](0012-agent-model-switching-and-prepaid-billing.md)（モデル切替 + プリペイド課金）、[ADR-0013](0013-multi-provider-llm-selection.md)（マルチプロバイダ選択）、[ADR-0015](0015-vertex-ai-for-gemini-anthropic.md)（Gemini/Anthropic の Vertex AI 経路。**ただし Anthropic を Vertex AI(ADC) で叩く認証判断は本 ADR に引き継ぐ**。撤去するのは Gemini/OpenAI マルチプロバイダ部分のみ） +- 関連: [ADR-0010](0010-devforge-agent.md)（Agent の不変条件・dev/prod 分離思想を継承）、[ADR-0018](0018-github-resume-draft-generation.md) / [ADR-0020](0020-async-resume-draft-generation.md)（ドラフト生成の課金配線を剥がす）、[ADR-0005](0005-cloudrun-single-instance.md)（レート制限の原子的カウントの前提） + +## コンテキスト + +機能整理（#517）でユーザ目線の障害を棚卸しした結果、**Agent 利用の最大の障害は「2 段落の文章改善のためにカード登録してチャージする」プリペイド課金の壁**だと判断した。 + +- Agent の実用途は小さな構造化 JSON（operations）の生成であり、ADR-0010 自身が `claude-haiku-4-5` で十分と判断していた。上位モデル（Sonnet）課金は「あると嬉しい」レベルで、壁のコストに見合わない。 +- マルチプロバイダ 3 社（ADR-0013: Anthropic / Gemini / OpenAI）+ Vertex 経路（ADR-0015）+ Stripe プリペイド（ADR-0012）は、個人開発規模（ADR-0005）に対して過剰装備。保守対象が広い（billing 348 行 + Stripe webhook + 3 プロバイダクライアント + Vertex/ADC + 複数 API キー env + 課金/使用ログテーブル）。 +- Haiku は安価（$1/$5 per 1M tokens）で、無料開放しても運営コストは限定的。ただし**クレジット残高が事実上の abuse 防止だった**ため、それが消える分の蓋（レート制限）が要る。 + +## 決定内容 + +**本番の Agent を Claude Haiku 無料一本化 + ユーザ単位レート制限に縮退する。** プリペイド課金・マルチプロバイダ抽象・モデル選択を撤去し、保守面を最小化しつつ「課金の壁」を除いて体験を上げる。 + +### 縮退後の構成 + +- **本番 LLM**: Claude Haiku 固定（モデル選択・エイリアス機構を撤去） +- **ローカル開発**: Ollama（`LLM_LOCAL_OLLAMA`。ADR-0010 の dev/prod 無料パスを維持） +- **abuse 防止**: ユーザ単位の日次レート制限（クレジット残高チェックの代替） +- **課金**: 撤去（Stripe / プリペイドクレジット / 使用ログ課金を全廃） + +### 撤去順序（後続 3 PR の指針。順序が重要） + +1. **#521 レート制限導入（先行必須）**: 課金撤去で消える abuse 防止の代替を**先に**入れる。`/agent/chat`・`/agent/resume-draft/pdf` にユーザ単位日次上限。決定論ロジックとして TDD（mutmut 対象）。上限は env 化。 +2. **#522 課金撤去**: `routers/billing.py`・`services/billing/`（`credit_service` / `pricing` / `stripe_service`、348 行）・Stripe webhook・課金/使用ログテーブルの drop マイグレーション・`stripe` 依存・Stripe env・web `BillingPage` を撤去。Agent / resume-draft から残高チェック・クレジット消費・使用量記録の配線を剥がす。 +3. **#523 マルチプロバイダ撤去**: `services/agent/llm/` から OpenAI / Gemini クライアントとプロバイダ切替を削除（**Anthropic(Vertex ADC) + Ollama のみ残す**）。`model_catalog` を Haiku 固定に縮退。`openai` / `google-genai` 依存とプロバイダ選択 UI を削除。**`anthropic[vertex]` と Anthropic 用 Vertex 設定は残す**（下記「残す Anthropic の認証方式」）。撤去する env は Gemini 用 `VERTEX_LOCATION` と OpenAI の `OPENAI_API_KEY` のみ。 + +### 残すもの（撤去しない不変条件） + +- **ローカル Ollama 経路**（ADR-0010 の dev/prod 分離思想） +- **Agent の不変条件**（ADR-0010 / `.claude/rules/backend/agent.md`）: LLM は `services/agent/` のみ・DB 非更新原則・エラー契約（`AGENT_LLM_ERROR` / `AGENT_PARSE_ERROR`）・構造化出力（tool use スキーマ）・リトライ 1 回 +- **`factory.get_llm_client()` の「切替 1 箇所」原則**（切替先が Anthropic + Ollama の 2 択に減るだけ） + +### ADR-0018 / 0020（ドラフト生成）への適用 + +経歴書ドラフト生成（ADR-0018 → 0020 で非同期化）は `run_task.py` に課金確定を持つ。#522 でこの課金配線（事前残高チェック 402・PDF レンダリング後の実課金・課金記録失敗時の dead_letter 化）を剥がす。ドラフト生成自体・最小永続化（`resume_draft_cache`）・非同期タスク構造は維持する。 + +### 残す Anthropic の認証方式: Vertex AI(ADC) を維持する + +マルチプロバイダ撤去後も、残る Anthropic-Haiku は **Vertex AI（Cloud Run の SA → ADC）経由を維持する**。ADR-0015 の PII データガバナンス（学習除外 + アジア圏データ所在）は、プロバイダが 1 社に減っても要件として有効なため、その認証判断を本 ADR に引き継ぐ。 + +- **残す**: `anthropic[vertex]` 依存 / `AsyncAnthropicVertex` 経路 / `VERTEX_ANTHROPIC_LOCATION` / `GCP_PROJECT_ID`（Cloud Tasks と共用）/ Cloud Run SA の `roles/aiplatform.user` +- **撤去する**: Gemini 用 `VERTEX_LOCATION` と `google-genai`、OpenAI の `OPENAI_API_KEY` と `openai`、および Gemini/OpenAI クライアント +- 経歴書（PII）を LLM に送るプロダクトとして、データ所在地（アジア圏）と学習除外を担保し続けることを優先する。`ANTHROPIC_API_KEY` 直キー方式には**戻さない**（データ所在地を失うため）。 + +これにより ADR-0015 は「Gemini の Vertex 経路・OpenAI の API キー継続・マルチプロバイダ前提」の部分が Superseded になり、「Anthropic を Vertex AI(ADC) で叩く」中核判断は本 ADR が継承する。 + +## 代替案 + +- **Sonnet 課金だけ残す**: 「壁」の本体が残る。用途（小さな JSON 生成）に Haiku で足りる以上、課金運用（Stripe / 未払いリスク）を残す利点は薄く却下。 +- **レート制限なしで無料開放**: 蓋ゼロの無料 LLM エンドポイントは abuse で運営コストが青天井になり得るため却下。レート制限を前提条件にする。 +- **マルチプロバイダを残す**: dev の従量課金抑制（ADR-0013 の動機）はローカル Ollama 無料パスで代替済み。品質差の選択肢は用途に対し過剰で、3 クライアント + Vertex/ADC + 複数 env の保守が勝つため却下。 + +## トレードオフ・既知のリスク + +- **Haiku の API コストが運営持ちになる**（従来はユーザのクレジットで相殺）。安価とはいえ無料開放のため、**ユーザ単位レート制限（日次上限）が実質必須の前提条件**。順序として #521（レート制限）を #522（課金撤去）より先に入れる。 +- **既存のクレジット残高データが消える**（#522 の drop マイグレーション）。破壊的変更。既存残高のユーザがいる場合はエクスポート/精算を #522 の stage で明示検討する。 +- Sonnet / Gemini / GPT を選べなくなる（品質を上げたい場面での選択肢喪失）。用途が Haiku で足りる前提のトレードオフ。 +- 公開 API（billing 系パス・model 選択パラメータ・課金 ErrorCode）の削除は OpenAPI 生成物・web 型に波及する破壊的変更。外部クライアント不在を前提とする。 + +## 将来の移行条件 + +- 上位モデルや課金を再導入する場合は、本 ADR を `Superseded` とした上で新規 ADR を起票し、ADR-0012 の課金設計（原子的 UPDATE・二重課金防止）を git 履歴から再評価する。 +- マルチプロバイダを再導入する場合は ADR-0013 の provider 抽象を、データガバナンスを再開する場合は ADR-0015 の Vertex/ADC 設計を、それぞれ再評価する。 + +## 設計原則との関係 + +- **P1（コスト最適化を第一制約にする）**: 過剰装備（3 プロバイダ + Vertex + Stripe）の保守コストを削り、個人開発規模（ADR-0005）に構成を合わせる。 +- **P6（可逆性を設計する）**: 撤退条件を明記し、git 履歴と旧 ADR から再構築可能な可逆撤去とする。 +- **P2（PII を信頼境界の外に出さない）**: 残す Anthropic を Vertex AI(ADC) 経由に維持し、ADR-0015 の PII データガバナンス（学習除外 + アジア圏データ所在）を単一プロバイダ構成でも継続する。 + +## 関連リンク + +- [#517 機能整理・体験改善ロードマップ](../../README.md)（親 issue） +- #520（本 ADR）／#521（レート制限）／#522（課金撤去）／#523（マルチプロバイダ撤去） +- [ADR-0012](0012-agent-model-switching-and-prepaid-billing.md) / [ADR-0013](0013-multi-provider-llm-selection.md) / [ADR-0015](0015-vertex-ai-for-gemini-anthropic.md)（撤去対象） diff --git a/docs/adr/README.md b/docs/adr/README.md index 4870e51d..1bfcd951 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -16,10 +16,7 @@ | [ADR-0007](./0007-openapi-typescript-codegen.md) | OpenAPI → TypeScript 型コード生成の導入（完全移行） | 開発プロセス / 品質 | Pydantic スキーマを正本に TS 型を自動生成し、drift を CI（codegen-drift）で機械検知 | | [ADR-0009](./0009-frontend-toast-notification.md) | フロントエンドの一時通知をトースト方式に統一する | フロントエンド | 外部ライブラリを足さず自前 Toast 基盤（Context + Portal）に一時通知を統一 | | [ADR-0010](./0010-devforge-agent.md) | DevForge Agent 機能の導入 | LLM / Agent | 対話型 LLM を再導入。DB 非更新原則・スキーマ/プロンプトの責務分離・失敗の明示的エラー化 | -| [ADR-0012](./0012-agent-model-switching-and-prepaid-billing.md) | Agent モデル切り替えとプリペイドクレジット課金 | LLM / Agent | モデルはエイリアス方式（実 ID はサーバー側 model_catalog が SSoT）+ プリペイド従量課金（Stripe） | -| [ADR-0013](./0013-multi-provider-llm-selection.md) | マルチプロバイダ LLM（ユーザー選択式） | LLM / Agent | プロバイダをモデルエイリアスの属性に移しユーザー選択式へ。グローバル `LLM_PROVIDER` 廃止 | | [ADR-0014](./0014-renovate-dependency-automation.md) | Renovate による依存更新の自動化 | 開発プロセス / 品質 | 依存の完全固定（SHA / `==` ピン）を維持したまま、追従だけを Renovate で自動化 | -| [ADR-0015](./0015-vertex-ai-for-gemini-anthropic.md) | Gemini / Anthropic を Vertex AI（SA→ADC）経由にする | LLM / Agent | API キー注入を廃止し ADC 認証へ。データ所在地（アジア圏）と学習除外を担保 | | [ADR-0016](./0016-github-skill-inference.md) | GitHub 連携によるスキル推論基盤 | LLM / Agent | スキルを 3 層に分離（機械=幅 / 人間=深さ）。推論パイプラインは決定論を維持 | | [ADR-0017](./0017-mutation-testing-and-slack-notifications.md) | ミューテーションテスト週次実行と Slack 通知チャンネル分割 | 開発プロセス / 品質 | テストの検出力を週次ミューテーションで可視化（warn-only）、CI 通知を用途別 Slack へ分割 | | [ADR-0018](./0018-github-resume-draft-generation.md) | GitHub 連携データからの経歴書ドラフト生成 | LLM / Agent | 構造はルールベース・自然文だけ LLM のハイブリッド。何も永続化せず PDF プレビューのみ返す | @@ -27,6 +24,7 @@ | [ADR-0020](./0020-async-resume-draft-generation.md) | 経歴書ドラフト生成の非同期化と最小永続化 | LLM / Agent | ドラフト生成を独立の非同期タスク化。payload だけを連携ドメインに最小永続化し DL 時に再レンダリング | | [ADR-0021](./0021-nix-managed-python-env.md) | backend Python 環境の Nix フルマネージド化（.venv 廃止） | 開発プロセス / 品質 | 依存 SSoT を pyproject + uv.lock に一本化し、devshell / CI / 本番イメージの 3 経路を uv2nix（flake）で統一 | | [ADR-0022](./0022-remove-blog-integration.md) | ブログ連携機能の撤去 | プロダクト / 機能整理 | 経歴書へ還流せずスコアが逆効果になり得るブログ連携（テーブル 3 つ・router / service / web 一式）を全量撤去 | +| [ADR-0023](./0023-remove-billing-multiprovider.md) | プリペイド課金・マルチプロバイダの撤去と Haiku 無料一本化 | LLM / Agent | 課金の壁を撤去し Haiku 無料一本化 + ユーザ単位レート制限へ縮退。Anthropic は Vertex(ADC) 維持、Gemini/OpenAI/Stripe を撤去 | ## 全 ADR 一覧 @@ -46,10 +44,10 @@ | [ADR-0009](./0009-frontend-toast-notification.md) | フロントエンドの一時通知をトースト方式に統一する | Accepted | フロントエンド | — | P6 | | [ADR-0010](./0010-devforge-agent.md) | DevForge Agent 機能の導入 | Accepted | LLM / Agent | Supersedes: 0008。関連: 0004（積み残しリスクを設計段階で解消）、0007 | P4・P5 | | [ADR-0011](./0011-frontend-textlint-proofread.md) | 職務経歴書のフロントエンド完結型 文章校正（textlint + kuromoji） | Deprecated | フロントエンド | 実装後に運用不要と判断し撤去。関連: 0008（PII 非送信・ルールベース志向） | P2 | -| [ADR-0012](./0012-agent-model-switching-and-prepaid-billing.md) | Agent モデル切り替えとプリペイドクレジット課金 | Accepted | LLM / Agent | 関連: 0010（チャット契約）、0005（原子的 UPDATE の前提） | P1 | -| [ADR-0013](./0013-multi-provider-llm-selection.md) | マルチプロバイダ LLM（ユーザー選択式） | Accepted | LLM / Agent | 関連: 0010（切替 1 箇所の原則を維持）、0012（課金・model_catalog） | P3 | +| [ADR-0012](./0012-agent-model-switching-and-prepaid-billing.md) | Agent モデル切り替えとプリペイドクレジット課金 | Superseded by ADR-0023 | LLM / Agent | 0023 が課金を撤去。関連: 0010（チャット契約）、0005（原子的 UPDATE の前提） | P1 | +| [ADR-0013](./0013-multi-provider-llm-selection.md) | マルチプロバイダ LLM（ユーザー選択式） | Superseded by ADR-0023 | LLM / Agent | 0023 がマルチプロバイダを撤去。関連: 0010、0012 | P3 | | [ADR-0014](./0014-renovate-dependency-automation.md) | Renovate による依存更新の自動化 | Accepted | 開発プロセス / 品質 | 関連: 0017（Actions の SHA ピン運用） | P7 | -| [ADR-0015](./0015-vertex-ai-for-gemini-anthropic.md) | Gemini / Anthropic を Vertex AI（SA→ADC）経由にする | Accepted | LLM / Agent | 0013 の認証部分を更新。関連: 0010、0012 | P2 | +| [ADR-0015](./0015-vertex-ai-for-gemini-anthropic.md) | Gemini / Anthropic を Vertex AI（SA→ADC）経由にする | Superseded by ADR-0023 | LLM / Agent | 0023 が Gemini/OpenAI マルチプロバイダを撤去。Anthropic の Vertex(ADC) 認証は 0023 が継承 | P2 | | [ADR-0016](./0016-github-skill-inference.md) | GitHub 連携によるスキル推論基盤 | Accepted | LLM / Agent | 関連: 0010（責務分離の元思想）、0013、0015 | P4 | | [ADR-0017](./0017-mutation-testing-and-slack-notifications.md) | ミューテーションテスト週次実行と Slack 通知チャンネル分割 | Accepted | 開発プロセス / 品質 | 関連: 0014 | P3 | | [ADR-0018](./0018-github-resume-draft-generation.md) | GitHub 連携データからの経歴書ドラフト生成 | Accepted | LLM / Agent | 関連: 0010（不変条件を継承し適用範囲を拡張）、0012（課金配線）、0013・0015（プロバイダ）、0016（データ供給源）、0020（非同期化・最小永続化で更新） | P4・P5 | @@ -57,6 +55,7 @@ | [ADR-0020](./0020-async-resume-draft-generation.md) | 経歴書ドラフト生成の非同期化と最小永続化 | Accepted | LLM / Agent | 関連: 0018（同期実装を更新）、0010（不変条件を継承）、0012（課金をタスク側へ移設）、0016（データ供給源） | P1・P4・P5 | | [ADR-0021](./0021-nix-managed-python-env.md) | backend Python 環境の Nix フルマネージド化（.venv 廃止） | Accepted | 開発プロセス / 品質 | 関連: 0017（uv 非管理前提を更新）、0014（依存固定・Renovate manager）、0007（Nix devshell 規約） | P7・P3・P6 | | [ADR-0022](./0022-remove-blog-integration.md) | ブログ連携機能の撤去 | Accepted | プロダクト / 機能整理 | 手本: 0008（撤去の流儀）。関連: 0010（Agent コンテキストの入力縮小）、0016 | P6・P1 | +| [ADR-0023](./0023-remove-billing-multiprovider.md) | プリペイド課金・マルチプロバイダの撤去と Haiku 無料一本化 | Accepted | LLM / Agent | Supersedes: 0012・0013・0015。関連: 0010（Agent 不変条件を継承）、0018・0020（課金配線を剥がす）、0005 | P1・P6・P2 | ## テーマ別の決定系統 @@ -71,6 +70,9 @@ graph LR A0010 -.-> A0012["0012
モデル切替 + 課金"] A0012 -.-> A0013["0013
マルチプロバイダ"] A0013 -.-> A0015["0015
Vertex AI (ADC)"] + A0012 -->|"撤去"| A0023["0023
Haiku 無料一本化
+ レート制限"] + A0013 -->|"撤去"| A0023 + A0015 -->|"撤去（Anthropic Vertex は継承）"| A0023 A0010 -.-> A0016["0016
スキル推論 3 層"] A0010 -.-> A0018["0018
経歴書ドラフト生成"] A0016 -.-> A0018