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

// 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

// 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 通知許可管理フック ✅

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フック ✅

// ステータス取得
export function usePushStatus(enabled?: boolean);

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

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

7.3 通知管理コンポーネント (予定)

interface PushNotificationManagerProps {
  onPermissionGranted?: () => void;
  onSubscriptionChange?: (subscription: PushSubscription | null) => void;
}

export function PushNotificationManager(props: PushNotificationManagerProps)

8. 環境設定

8.1 VAPID キー

# .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設定

// 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統合版)