# 通知設計書 50-検索警告通知

## 概要

本ドキュメントは、検索画面においてカメラ検索（画像検索/テキスト検索）でエラーが発生した場合に表示される警告通知の設計について記述する。

### 本通知の処理概要

本通知は、検索画面（SearchScreen）においてカメラを使用した画像検索またはテキスト検索機能でプラットフォームエラーが発生した場合に表示される警告通知である。

**業務上の目的・背景**：ECアプリの検索画面では、テキスト入力による検索に加え、カメラを使用した画像検索（商品の写真から検索）やテキスト検索（カメラで文字を読み取って検索）機能が提供されている。これらの機能でエラーが発生した場合、ユーザーに適切にフィードバックを提供し、問題の内容を伝える必要がある。

**通知の送信タイミング**：検索画面においてカメラ機能を使用した際、プラットフォーム側でエラー（PlatformException）が発生した場合に即時表示される。

**通知の受信者**：検索画面を操作している現在のユーザー（アプリ操作者）。

**通知内容の概要**：警告メッセージとして、警告タイトルとプラットフォームから返却されたエラーメッセージが表示される。黄色の背景色で警告アイコン付きのオーバーレイ通知として表示される。

**期待されるアクション**：ユーザーはエラー内容を確認し、再度カメラ検索を試みるか、テキスト入力による検索に切り替える。

## 通知種別

アプリ内通知（オーバーレイ警告通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即時表示） |
| 優先度 | 中 |
| リトライ | 無し（即時1回表示） |

### 送信先決定ロジック

操作中のユーザーに対して即時表示。特定の送信先決定ロジックは不要。

## 通知テンプレート

### 警告通知

| 項目 | 内容 |
|-----|------|
| タイトル | Warning（StringConstants.warning のローカライズ値） |
| 背景色 | Colors.yellow（黄色） |
| アイコン | Icons.warning_amber（警告アイコン） |
| 形式 | オーバーレイ通知 |

### 本文テンプレート

```
[タイトル]: Warning
[メッセージ]: {プラットフォームエラーメッセージ}（PlatformException.message）
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| warning | 警告タイトル | StringConstants.warning | Yes |
| message | エラーメッセージ | PlatformException.message | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 例外処理 | PlatformException キャッチ | カメラ検索でプラットフォームエラー発生 | MethodChannel 呼び出し時の例外 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| カメラ権限が許可されている | 正常にカメラが起動し、検索が実行される |
| プラットフォーム側でエラーなし | 正常に画像/テキストが認識され、検索が実行される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[カメラ検索アイコンタップ] --> B[DialogHelper.searchDialog表示]
    B --> C{検索種別選択}
    C -->|画像検索| D[_checkPermission（searchImage）]
    C -->|テキスト検索| E[_checkPermission（searchText）]
    D --> F{カメラ権限確認}
    E --> F
    F -->|許可| G[MethodChannel.invokeMethod呼び出し]
    F -->|拒否| H[再度権限要求 / 設定画面へ]
    G --> I{プラットフォーム処理}
    I -->|成功| J[検索テキスト取得 → 検索実行]
    I -->|例外発生| K[PlatformException キャッチ]
    K --> L[ShowMessage.showNotification呼び出し]
    L --> M[警告通知表示]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本通知はクライアント側のみで完結するため、データベース参照は発生しない。

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| PlatformException | ネイティブプラットフォーム側でエラー発生 | 警告通知を表示 |
| カメラ権限拒否 | ユーザーがカメラ権限を拒否 | 再度権限要求、または設定画面を開く |
| 永続的権限拒否 | ユーザーが永続的にカメラ権限を拒否 | openAppSettings() で設定画面を開く |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（24時間）

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

- カメラ権限は明示的にユーザーに要求される
- プラットフォームエラーメッセージにはセンシティブ情報を含めない

## 備考

- 画像検索とテキスト検索の切り替えは DialogHelper.searchDialog で行われる
- MethodChannel（defaultChannelName）を使用してネイティブ側の画像認識/OCR機能を呼び出す
- 音声検索（SpeechToText）は別の機能で、本通知の対象外
- 検索結果は FetchSearchEvent で取得される

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、検索画面で使用される状態と定数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | search_screen.dart | `lib/screens/search_screen/view/search_screen.dart` | searchImage, searchText 変数（30-31行目）の定義を確認 |

**読解のコツ**: MethodChannel を使用したネイティブ連携のパターンに注目する。

#### Step 2: エントリーポイントを理解する

処理の起点となるカメラアイコンタップイベントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | search_screen.dart | `lib/screens/search_screen/view/search_screen.dart` | カメラアイコンの onPressed（205-218行目）を確認 |

**主要処理フロー**:
1. **205-218行目**: カメラアイコンタップでダイアログ表示
2. **210行目**: 画像検索選択時の _checkPermission 呼び出し
3. **214行目**: テキスト検索選択時の _checkPermission 呼び出し

#### Step 3: 権限確認と例外処理を理解する

カメラ権限確認とエラー処理のフローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | search_screen.dart | `lib/screens/search_screen/view/search_screen.dart` | _checkPermission メソッド（288-308行目）を確認 |

**主要処理フロー**:
- **289行目**: permission.request() でカメラ権限を要求
- **290行目**: 権限許可時（PermissionStatus.granted）の処理
- **291-296行目**: MethodChannel.invokeMethod 呼び出しと結果取得
- **297-301行目**: PlatformException キャッチと ShowMessage.showNotification 呼び出し

#### Step 4: 通知表示処理を理解する

ShowMessage クラスの showNotification メソッドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | show_message.dart | `lib/widgets/show_message.dart` | showNotification メソッド（79-94行目）の実装詳細を確認 |

#### Step 5: 文字列定数を理解する

通知に使用される文字列定数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | string_constants.dart | `lib/utils/string_constants.dart` | warning（134行目）の定義を確認 |

### プログラム呼び出し階層図

```
SearchScreen
    │
    ├─ _setAppBarView
    │      └─ IconButton (カメラアイコン)
    │             └─ onPressed
    │                    └─ DialogHelper.searchDialog
    │                           ├─ 画像検索選択 → _checkPermission (searchImage)
    │                           └─ テキスト検索選択 → _checkPermission (searchText)
    │
    └─ _checkPermission
           └─ permission.request()
                  ├─ PermissionStatus.granted
                  │      └─ MethodChannel.invokeMethod
                  │             ├─ 成功 → onImageSearch → FetchSearchEvent
                  │             └─ PlatformException
                  │                    └─ ShowMessage.showNotification
                  │                           (warning, e.message, Colors.yellow)
                  ├─ PermissionStatus.denied
                  │      └─ _checkPermission (再帰呼び出し)
                  └─ PermissionStatus.permanentlyDenied
                         └─ openAppSettings()
```

### データフロー図

```
[入力]                      [処理]                         [出力]

カメラアイコンタップ ───▶ 検索種別選択ダイアログ
                              │
                       ┌──────┴──────┐
                       ▼             ▼
                   画像検索      テキスト検索
                       │             │
                       └──────┬──────┘
                              ▼
                        権限要求
                              │
                       ┌──────┼──────┐
                       ▼      ▼      ▼
                    許可   拒否   永続拒否
                       │      │      │
                       ▼      ▼      ▼
                   ネイティブ 再要求 設定画面
                    呼び出し
                       │
                ┌──────┴──────┐
                ▼             ▼
             成功          例外発生
                │             │
                ▼             ▼
           検索実行     警告通知表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| search_screen.dart | `lib/screens/search_screen/view/search_screen.dart` | ソース | 検索画面のWidget、通知トリガーの発火元 |
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 通知表示ユーティリティクラス |
| string_constants.dart | `lib/utils/string_constants.dart` | ソース | 文字列定数の定義 |
| dialog_helper.dart | `lib/widgets/dialog_helper.dart` | ソース | ダイアログヘルパー（searchDialog） |
| search_bloc.dart | `lib/screens/search_screen/bloc/search_bloc.dart` | ソース | 検索画面のBLoC |
