docs/web-push-implementation-plan.md

# Webプッシュ通知実装計画書

## 1. プロジェクト概要

### 現在のアーキテクチャ分析結果
- **フレームワーク**: Next.js 15 (App Router)
- **言語**: TypeScript
- **バックエンド**: **Hono** (型安全なAPI層) ✅
- **API統合**: `/api/rpc/[...route]/route.ts` 経由のHono統合 ✅
- **UI**: Tailwind CSS + Radix UI
- **状態管理**: Zustand
- **データフェッチング**: TanStack Query
- **その他**: React Hook Form, Zod, Sonner (通知)

### 実装対象
ブラウザ（Chrome）におけるWebプッシュ通知機能を既存のLP生成システムに統合

### アーキテクチャ整合性確保 🔧
**重要**: 既存システムはHonoバックエンドを使用しているため、プッシュ通知機能も同様の設計パターンに従って実装済み

## 2. 要件定義

### 機能要件
1. **通知許可トリガー**: ユーザーがブラウザにWebプッシュ許可を求めるUI
2. **API完了通知**: API通信完了時の任意メッセージ通知
3. **ブラウザ表示**: カスタムメッセージのプッシュ通知をブラウザで確認

### 非機能要件
- 永続化層は使用しない（メモリベース）
- 現行アーキテクチャとの整合性維持
- セキュリティ（VAPID認証）対応

## 3. 技術仕様

### 3.1 使用技術
- **Service Worker**: プッシュイベント受信・通知表示
- **Push API**: ブラウザネイティブプッシュ通知
- **VAPID**: サーバー認証（Voluntary Application Server Identification）
- **web-push**: Node.js用プッシュ通知ライブラリ
- **Hono**: 型安全なAPIルート実装 ✅
- **Zod**: スキーマ検証とバリデーション ✅

### 3.2 通信フロー（Hono統合版）
```
1. ユーザー操作 → 通知許可要求
2. ブラウザ許可 → Service Worker登録
3. 購読情報取得 → Honoクライアント経由でサーバーに送信
4. API処理完了 → Hono API経由でプッシュ通知送信
5. Service Worker → 通知表示
```

### 3.3 型安全性の確保
- **スキーマ駆動開発**: Zodによるリクエスト/レスポンス検証
- **エンドツーエンド型安全性**: HonoクライアントによるAPIの型推論
- **実行時検証**: バリデーションエラーの適切なハンドリング

## 4. 実装手順

### Phase 1: 基盤構築
1. **依存関係追加**
   - `web-push` パッケージをpackage.jsonに追加

2. **Service Worker実装**
   - `public/sw.js` 作成
   - プッシュイベントハンドリング
   - 通知クリック処理

### Phase 2: サーバーサイド
3. **VAPID設定**
   - 環境変数設定（`.env.local`）
   - `lib/webpush-config.ts` 作成

4. **Hono API実装** ✅
   - `server/routes/push.ts` (Honoルート実装)
   - `/api/rpc/[...route]/route.ts` への統合

### Phase 3: クライアントサイド
5. **型安全クライアント実装** ✅
   - `api-client/push/index.ts` (Honoクライアント)
   - `api-client/push/queries.ts` (TanStack Queryフック)

6. **許可管理フック** ✅
   - `hooks/use-notification-permission.ts` 作成・更新
   - 許可状態管理・監視・Honoクライアント統合

7. **通知管理コンポーネント**
   - `components/notifications/push-notification-manager.tsx` 作成
   - 購読・送信インターフェース

### Phase 4: 統合
8. **レイアウト統合**
   - `app/layout.tsx` にService Worker登録
   - 通知管理コンポーネント配置

9. **機能統合**
   - `app/refresh-moments/improvement-result/page.tsx` 修正
   - API完了時の通知トリガー追加

## 5. ファイル構成

```
project-root/
├── public/
│   └── sw.js                          # Service Worker ✅
├── lib/
│   └── webpush-config.ts             # VAPID設定・ユーティリティ ✅
├── server/routes/
│   └── push.ts                       # Hono プッシュ通知ルート ✅
├── api-client/push/
│   ├── index.ts                      # 型安全Honoクライアント ✅
│   └── queries.ts                    # TanStack Queryフック ✅
├── hooks/
│   └── use-notification-permission.ts # 通知許可管理フック ✅
├── components/notifications/
│   └── push-notification-manager.tsx  # 通知管理コンポーネント (予定)
├── app/
│   ├── layout.tsx                    # (修正予定) SW登録追加
│   ├── api/rpc/[...route]/route.ts   # (修正済) Honoルート統合 ✅
│   ├── api/push/                     # ⚠️ 削除が必要 (旧実装)
│   └── refresh-moments/improvement-result/
│       └── page.tsx                 # (修正予定) 通知トリガー追加
└── .env.local                       # (追加) VAPID環境変数
```

### ✅ 実装完了済み項目
- Service Worker基盤
- VAPID設定・ユーティリティ
- Honoルート統合
- 型安全クライアント
- 通知許可管理フック

### 🔄 アーキテクチャ修正済み
- **Direct API → Hono統合**: 既存の`/api/push/`を削除し、Honoルート(`/api/rpc/push/`)に移行
- **型安全性強化**: Zodスキーマによるバリデーション
- **エンドツーエンド型推論**: HonoクライアントによるAPIの完全な型安全性

## 6. API設計（Hono統合版）

### 6.1 購読API (`/api/rpc/push/subscribe`)
**POST** `/api/rpc/push/subscribe`
```typescript
// Request
{
  subscription: {
    endpoint: string;
    keys: {
      p256dh: string;
      auth: string;
    };
  };
}

// Response
{
  success: boolean;
  message: string;
}
```

**DELETE** `/api/rpc/push/subscribe` (購読解除)

### 6.2 送信API (`/api/rpc/push/send`)
**POST** `/api/rpc/push/send`
```typescript
// Request
{
  title: string;
  body: string;
  data?: Record<string, any>;
}

// Response
{
  success: boolean;
  message: string;
  sent: number;
}
```

**GET** `/api/rpc/push/status` (ステータス確認)

### 6.3 型安全性の実装
全てのAPIエンドポイントは以下の特徴を持ちます：
- **Zodスキーマによるバリデーション**: リクエスト/レスポンスの型安全性
- **Honoによる型推論**: クライアントからサーバーまでの完全な型安全性
- **エラーハンドリング**: 統一されたエラーレスポンス形式

## 7. コンポーネント設計（型安全版）

### 7.1 通知許可管理フック ✅
```typescript
export function useNotificationPermission() {
  return {
    permission: NotificationPermission;
    isSupported: boolean;
    isServiceWorkerReady: boolean;
    requestPermission: () => Promise<NotificationPermission>;
    subscribe: () => Promise<PushSubscription | null>;
    unsubscribe: () => Promise<boolean>;
    getCurrentSubscription: () => Promise<PushSubscription | null>;
    sendTestNotification: (title: string, body: string) => Promise<boolean>;
  };
}
```

### 7.2 TanStack Queryフック ✅
```typescript
// ステータス取得
export function usePushStatus(enabled?: boolean);

// 購読操作
export function usePushSubscribe();
export function usePushUnsubscribe();

// 通知送信
export function usePushSendNotification();
export function usePushSendTestNotification();
```

### 7.3 通知管理コンポーネント (予定)
```typescript
interface PushNotificationManagerProps {
  onPermissionGranted?: () => void;
  onSubscriptionChange?: (subscription: PushSubscription | null) => void;
}

export function PushNotificationManager(props: PushNotificationManagerProps)
```

## 8. 環境設定

### 8.1 VAPID キー
```bash
# .env.local
VAPID_PUBLIC_KEY=your_public_key
VAPID_PRIVATE_KEY=your_private_key
VAPID_SUBJECT=mailto:your-email@example.com
```

### 8.2 Next.js設定
```typescript
// next.config.ts (修正不要、現行設定で対応可能)
```

## 9. セキュリティ考慮事項

### 9.1 VAPID認証
- 公開鍵をクライアントに安全に配信
- 秘密鍵をサーバーサイドでのみ使用
- subject（連絡先情報）を適切に設定

### 9.2 購読情報管理
- メモリベース管理（永続化なし）
- セッション単位でのスコープ管理
- 個人情報を含まない

## 10. 動作フロー

### 10.1 初期化フロー
1. ページロード時にService Worker登録
2. ブラウザサポート確認
3. 通知許可状態チェック
4. 必要に応じて許可要求UI表示

### 10.2 通知送信フロー
1. API処理開始（改善案生成など）
2. 処理完了検知
3. プッシュ通知送信API呼び出し
4. Service Workerでイベント受信
5. ブラウザ通知表示

## 11. テストシナリオ

### 11.1 基本機能テスト
- [ ] Service Worker正常登録
- [ ] 通知許可要求・承認
- [ ] 購読情報取得・送信
- [ ] プッシュ通知受信・表示

### 11.2 統合テスト
- [ ] 改善案生成完了時の通知
- [ ] 異なるブラウザでの動作確認
- [ ] エラーハンドリング

### 11.3 ユーザビリティテスト
- [ ] 許可要求UIの自然さ
- [ ] 通知メッセージの適切性
- [ ] 非対応ブラウザでの適切な処理

## 12. 実装優先度

### High Priority
1. Service Worker実装
2. 基本的なプッシュ通知機能
3. 改善案生成完了通知

### Medium Priority
4. エラーハンドリング強化
5. 通知設定UI
6. 複数通知タイプ対応

### Low Priority
7. 通知履歴機能
8. プッシュ通知の詳細カスタマイズ
9. 統計・分析機能

## 13. 実装状況サマリー

### ✅ Phase 2完了 (Hono統合版)
- **Service Worker**: プッシュ通知の受信・表示機能
- **VAPID設定**: 環境変数管理とwebpush統合
- **Hono API**: 型安全なプッシュ通知API実装
- **型安全クライアント**: HonoクライアントとTanStack Queryフック
- **通知許可管理**: ブラウザ統合とAPI連携

### 🔄 アーキテクチャ統合済み
- **Honoエコシステム**: 既存のAPIアーキテクチャに完全統合
- **型安全性**: エンドツーエンドの型推論とバリデーション
- **一貫性**: 既存のコードパターンとの整合性確保

### ⏭️ 次のフェーズ (Phase 3-4)
1. 通知管理UIコンポーネント作成
2. Service Worker登録 (layout.tsx)
3. 改善案生成完了時の通知トリガー統合
4. 旧実装ファイル削除 (`/api/push/`)

### 🚀 利用可能な機能
現在の実装により以下の機能が利用可能：
- ブラウザプッシュ通知許可要求
- 購読登録・解除
- カスタムメッセージ通知送信
- 通知ステータス確認
- 型安全なAPI通信

---

**作成日**: 2025-09-21
**最終更新**: 2025-09-21
**バージョン**: 2.0 (Hono統合版)