# Posimai — API キー・認証アーキテクチャ整理

> 他の AI エージェントへの引き継ぎ用ドキュメント。
> 最終更新: 2026-03-19

---

## 1. 現状のAPI キー全体マップ

### Gemini API キー

| アプリ | キーの場所 | 変数名 | 誰が管理 | アクセス範囲 |
|--------|-----------|--------|---------|------------|
| posimai-brain（記事保存時 AI 要約） | Synology `.env` | `GEMINI_API_KEY` | サーバー側 | Tailscale 内のみ |
| posimai-journal（AI タグ提案） | Synology `.env` | `GEMINI_API_KEY` | サーバー側 | Tailscale 内のみ |
| posimai-together（アーカイブ AI 要約） | Synology `.env` | `GEMINI_TOGETHER_API_KEY`（→要復旧） | サーバー側 | Tailscale 内のみ |
| posimai-think | ブラウザ `localStorage` | `posimai-think-apikey` | ユーザーが設定画面で入力 | 誰でも（Tailscale 不要） |
| posimai-digest | ブラウザ `localStorage` | `gemini_api_key` | ユーザーが設定画面で入力 | 誰でも（Tailscale 不要） |

### その他の API キー

| アプリ | キー種別 | 場所 | 備考 |
|--------|---------|------|------|
| posimai-maps | `GOOGLE_PLACES_API_KEY` | Vercel 環境変数 | Vercel サーバーレス関数経由（Places API New） |
| posimai-reader | `posimai_api_key` | ブラウザ `localStorage` | Brain API キー（Gemini ではない） |
| posimai-brain / journal / together | `posimai_api_key` | ブラウザ `localStorage` | Brain API への認証キー（Magic Link 発行） |

---

## 2. Gemini キーの Google Cloud プロジェクト構成

| 変数名 | Google Cloud プロジェクト | 枠 | RPD（1日上限） |
|--------|--------------------------|-----|--------------|
| `GEMINI_API_KEY` | メインプロジェクト | 無料枠 | 20 |
| `GEMINI_TOGETHER_API_KEY` | `posimai-together` | 無料枠 | 20 |
| think/digest のユーザー入力キー | 各ユーザーが個別プロジェクトで発行 | 無料枠 | 20 |

**方針**: アプリごとに Google Cloud プロジェクトを分けてキーを発行し、それぞれ独立した無料枠（20 RPD）を持つ。必要になったら個別に有料化する。

---

## 3. 現在発生している問題（要対応）

### Together API キー問題（未解決）

**経緯**:
- 元の設定: `GEMINI_TOGETHER_API_KEY`（`posimai-together` プロジェクトのキー）を `.env` に設定
- server.js: `GEMINI_TOGETHER_API_KEY` があれば優先、なければ `GEMINI_API_KEY` にフォールバック（3行構造）
- 問題: server.js のモデルが `gemini-2.0-flash-lite`（`posimai-together` プロジェクトで割り当て 0）→ 429 エラー
- 別チャットでの対応: モデルを `gemini-2.5-flash` に変更（これ自体は正しい修正）
- **副作用**: 同時に `GEMINI_TOGETHER_API_KEY` を `.env` と `docker-compose.yml` から削除してしまった

**必要な修正**（別チャットで対応中）:
1. `GEMINI_TOGETHER_API_KEY=（posimai-together プロジェクトのキー）` を `.env` に再追加
2. `docker-compose.yml` に `GEMINI_TOGETHER_API_KEY` 行を再追加
3. server.js のフォールバック構造（下記）を元に戻す

```js
// 元の正しい構造（復元すべきコード）
const genAITogether = process.env.GEMINI_TOGETHER_API_KEY
    ? new GoogleGenerativeAI(process.env.GEMINI_TOGETHER_API_KEY)
    : genAI; // GEMINI_API_KEY にフォールバック
```

4. モデルは `gemini-2.5-flash` のまま（変更不要）

---

## 4. アーキテクチャの制約と今後の判断基準

### 現在の制約

| 制約 | 内容 |
|------|------|
| Tailscale 必須 | Synology の API（`posimai-lab.tail72e846.ts.net`）は Tailscale 接続端末のみアクセス可能 |
| think/digest の例外 | クライアント側で Gemini を直接呼ぶため Tailscale 不要。ただしユーザーがキーを入力する必要あり |
| 単一障害点 | Synology がオフライン → brain/journal/together の AI 機能が停止 |

### 将来の拡張パス（今はやらない）

| タイミング | 対応 |
|-----------|------|
| 知人・テストユーザーへの展開時 | Tailscale Funnel を有効化（設定数分、無料） |
| 商用展開時 | クラウドバックエンド（Vercel / Railway / Fly.io）に移行、独自ドメイン（api.posimai.app 等）に統一 |

### 理想的な最終形（商用時）

```
現状:
  browser → Gemini API 直接（think/digest）
  browser → Synology（Tailscale） → Gemini API（brain/journal/together）

理想:
  browser → api.posimai.app（クラウド） → Gemini API（全アプリ）

.env 構成（理想）:
  GEMINI_BRAIN_API_KEY=...
  GEMINI_TOGETHER_API_KEY=...
  GEMINI_THINK_API_KEY=...
  GEMINI_DIGEST_API_KEY=...
  GEMINI_JOURNAL_API_KEY=...
```

---

## 5. 現時点での推奨方針（やること・やらないこと）

### 今すぐやること
- [ ] Together: `GEMINI_TOGETHER_API_KEY` を `.env` に復活 + server.js フォールバック構造を復元（別チャット対応中）

### 現状維持（変更しない）
- brain / journal / together: server.js 経由（Tailscale 内）のまま
- think / digest: クライアント側 Gemini（ユーザーキー入力）のまま

### 将来検討（今はやらない）
- think/digest を server.js 経由に移行（Tailscale Funnel 有効化後に検討）
- クラウドバックエンドへの移行（商用展開時）
- `API_BASE_URL` を環境変数・設定ファイルで一元管理（移行コストを下げるため）

---

## 6. server.js の Gemini 関連コード現状

```js
// メイン Gemini インスタンス（brain/journal 用）
const genAI = process.env.GEMINI_API_KEY
    ? new GoogleGenerativeAI(process.env.GEMINI_API_KEY) : null;

// Together 専用インスタンス（要復元）
// 現在は genAI と同値になっている（GEMINI_TOGETHER_API_KEY 削除の副作用）
const genAITogether = genAI; // ← これを上記3行構造に戻す必要がある

// 使用モデル
// brain/journal: gemini-2.0-flash-lite（ライン 231, 867）
// together: gemini-2.5-flash（ライン 1338）← 別チャットで修正済み
```

---

## 7. 認証設計（Brain API キー）

| 項目 | 内容 |
|------|------|
| 認証方式 | Magic Link（メール送信）→ JWT トークン発行 |
| キー名 | `posimai_api_key`（localStorage に保存） |
| 適用アプリ | brain, reader, together, journal |
| 未認証時の動作 | 記事の閲覧は可能、保存・AI 機能は不可 |

---

*このドキュメントは `posimai-project/docs/api-key-architecture.md` に保存されています。*
*変更時は CLAUDE.md の担当 AI が更新してください。*