Hugging Face's logo

Spaces:
KazukiWatanabe
/
FE_Stage
Sleeping

App Files Community
FE_Stage / docs /web-push-poc-verification-plan.md
GitHub Actions
Deploy from GitHub Actions [DEV] - 2025-10-30 13:18:59
01c0359
preview code
|
raw
history blame contribute delete
9.2 kB

Web Push通知 PoC検証計画書

1. 概要

目的

Web Push通知機能の基本動作検証をするためのシンプルなPoC（Proof of Concept）を作成し、既存の/sample/html-preview-fvページに統合する。

検証対象

  • ブラウザでのWeb Push通知許可取得
  • PushSubscriptionオブジェクトの取得・表示
  • カスタムメッセージ通知送信機能

2. UI設計

2.1 表示要素

Web Push PoC画面には以下の4つの要素を配置する：

通知ステータス表示

  • 内容: 現在の通知許可状態をテキストで表示
  • 状態値: default（初期状態）、granted（許可済み）、denied（拒否済み）
  • 表示例: 「通知ステータス: default」

「通知を許可する」ボタン

  • 機能: ブラウザの通知許可ダイアログを呼び出す
  • 初期状態: 有効
  • 許可後状態: 無効（非活性）

「テスト通知を送信」ボタン

  • 機能: APIを呼び出して、自身のブラウザにテスト通知を送信
  • 初期状態: 無効（非活性）
  • 許可後状態: 有効

購読情報表示エリア

  • 内容: フロントエンドが取得したPushSubscriptionオブジェクトをJSON形式で表示
  • 用途: デバッグおよび動作確認用
  • 表示形式: 読み取り専用のテキストエリア

2.2 レイアウト 

┌─────────────────────────────────────┐
│ 通知ステータス: default              │
├─────────────────────────────────────┤
│ [通知を許可する] [テスト通知を送信]   │
├─────────────────────────────────────┤
│ 購読情報:                           │
│ ┌─────────────────────────────────┐ │
│ │ (PushSubscription JSON)         │ │
│ │                                 │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

3. 機能要件とユーザー操作フロー

3.1 初期表示

  • 通知ステータス: defaultと表示
  • 「通知を許可する」ボタン: 有効な状態
  • 「テスト通知を送信」ボタン: 無効（非活性）な状態
  • 購読情報表示エリア: 空欄

3.2 通知の許可

  1. ユーザーが「通知を許可する」ボタンをクリック
  2. ブラウザ標準の通知許可を求めるダイアログが表示
  3. ユーザーがダイアログで「許可」を選択

3.3 許可後の画面状態

  • 通知ステータス: grantedに更新
  • PushSubscriptionオブジェクト: 取得され、「購読情報表示エリア」にJSON形式で表示
  • 「通知を許可する」ボタン: 無効になる
  • 「テスト通知を送信」ボタン: 有効になる

3.4 テスト通知の送信

  1. ユーザーが「テスト通知を送信」ボタンをクリック
  2. フロントエンドは、保持しているPushSubscriptionオブジェクトをペイロードに含めて、Honoで実装したバックエンドAPI（/api/send-notification）にPOSTリクエストを送信
  3. サーバーはWeb Push通知を送信
  4. ブラウザがバックグラウンドでも通知を受信・表示

4. 技術仕様

4.1 フロントエンド実装

  • コンポーネント: components/notifications/push-notification-poc.tsx
  • 使用フック:
    • useNotificationPermission - 通知許可管理
    • 既存のPush APIクライアント
  • 状態管理: React State（シンプルな状態のみ）

4.2 バックエンドAPI

  • エンドポイント: /api/send-notification
  • メソッド: POST
  • ペイロード: PushSubscriptionオブジェクト
  • 実装: 既存のHono Push API

4.3 Service Worker

  • ファイル: public/sw.js（既存）
  • 登録: app/layout.tsxに追加
  • 機能: Web Push通知の受信・表示

5. 実装手順

Phase 1: 基盤準備

  1. Service Worker登録

    • app/layout.tsxにService Worker登録コード追加
    • 初期化エラーハンドリング

  2. 既存実装確認

    • /sample/html-preview-fvの現在の構成
    • 既存のコンポーネント構造とスタイリング

Phase 2: コンポーネント実装

  1. PoCコンポーネント作成
    • components/notifications/push-notification-poc.tsx
    • 4つの表示要素の実装
    • 基本的なエラーハンドリング

Phase 3: 統合

  1. ページ統合
    • /sample/html-preview-fvにコンポーネント追加
    • レスポンシブデザイン対応
    • 既存UIとの調和

Phase 4: 動作確認

  1. 検証シナリオ実行
    • 成功基準に基づく動作確認
    • エラーケースの基本確認

6. PoCの成功基準

以下の3点がすべて確認できれば、このPoCは成功とみなす：

✅ 基準1: 通知許可ダイアログの表示

「通知を許可する」ボタンを押下後、ブラウザの許可ダイアログが正常に表示されること

✅ 基準2: PushSubscriptionオブジェクトの取得

ユーザーが許可した後、PushSubscriptionオブジェクトが取得され画面に表示されること

✅ 基準3: デスクトップ通知の表示

「テスト通知を送信」ボタンを押下後、ブラウザのウィンドウが非アクティブな状態でもデスクトップにテスト通知が表示されること

7. ファイル構成

7.1 新規作成ファイル 

├── components/notifications/
│   └── push-notification-poc.tsx       # PoCメインコンポーネント

7.2 修正対象ファイル 

├── app/
│   ├── layout.tsx                       # SW登録追加
│   └── sample/html-preview-fv/
│       └── page.tsx                     # PoCコンポーネント統合

7.3 活用する既存実装 

├── hooks/
│   └── use-notification-permission.ts   # 通知許可管理
├── api-client/push/
│   ├── index.ts                         # Push APIクライアント
│   └── queries.ts                       # TanStack Queryフック
├── server/routes/
│   └── push.ts                          # Hono Push API
├── lib/
│   └── webpush-config.ts                # VAPID設定
└── public/
    └── sw.js                            # Service Worker

8. コンポーネント設計

8.1 PushNotificationPoC インターフェース 

interface PushNotificationPoCProps {
  className?: string;
}

export function PushNotificationPoC(props: PushNotificationPoCProps) {
  // 2つのボタンと2つの表示エリアを含む
  // 既存フックを活用したシンプルな実装
}

8.2 状態管理

  • 通知許可状態: useNotificationPermissionフックの活用
  • PushSubscription: React Stateで管理
  • API送信: 既存のPush APIクライアント使用

9. 統合方針

9.1 既存ページとの統合

  • /sample/html-preview-fvの既存レイアウトを尊重
  • サイドバーまたは専用セクションとして配置
  • 既存のスタイリング（Tailwind CSS）に準拠

9.2 視覚的優先度

  • 主機能: HTML プレビュー（既存）
  • 副機能: Web Push PoC（新規追加）
  • 既存機能の視認性を損なわない配置

10. 実装チェックリスト

10.1 Phase 1: 基盤準備

  • Service Worker登録コード追加（layout.tsx）
  • 既存ページ構造の確認
  • 統合方針の決定

10.2 Phase 2: コンポーネント実装

  • PushNotificationPoCコンポーネント作成
  • 通知許可機能実装
  • テスト送信機能実装
  • 購読情報表示機能実装

10.3 Phase 3: 統合

  • /sample/html-preview-fvにコンポーネント統合
  • レスポンシブ対応確認
  • 既存UIとの調和確認

10.4 Phase 4: 動作確認

  • 成功基準1: 許可ダイアログ表示確認
  • 成功基準2: PushSubscription取得・表示確認
  • 成功基準3: デスクトップ通知表示確認

11. エラーハンドリング（最小限）

11.1 基本的なエラーケース

  • ブラウザ非対応: 適切なメッセージ表示
  • 許可拒否: 状態表示の更新
  • API通信エラー: エラーメッセージ表示

11.2 ログ出力

  • 重要な状態変更とエラーをコンソールに出力
  • デバッグ用の詳細情報表示

作成日: 2025-09-21 最終更新: 2025-09-21 バージョン: 2.0（シンプル化版） 関連ドキュメント: docs/web-push-implementation-plan.md