# 通知設計書 3-Warning

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるWarning（警告）通知の設計について記述する。Warning通知は、注意が必要な状況をユーザーに通知するためのUI通知であり、NotificationType.Warning として定義されている。

### 本通知の処理概要

Warning通知は、アプリケーションにおいて潜在的な問題、注意事項、または確認が必要な状況をユーザーに視覚的に伝えるための仕組みである。

**業務上の目的・背景**：アプリケーション運用において、即座にエラーとはならないが注意を要する状況をユーザーに伝える必要がある。例えば、ディスク容量が残り少ない、接続が不安定、設定が推奨値と異なる、などの状況である。警告通知により、ユーザーは問題が深刻化する前に対処することができる。黄色/オレンジ色を基調としたビジュアルにより、注意を促す意図を直感的に伝える。

**通知の送信タイミング**：システムリソースの閾値超過検知時、接続不安定状態の検知時、非推奨設定の使用検知時、バックグラウンド処理での軽微な問題発生時など、ユーザーの注意を喚起すべき状況が発生したとき。

**通知の受信者**：アプリケーションのUI上で通知が表示されるウィンドウを視認しているエンドユーザー。特に、システム管理者や設定変更を行うユーザーが主な対象となることが多い。

**通知内容の概要**：タイトル（Title）とメッセージ（Message）の2つのテキスト要素で構成される。NotificationType.Warning として識別され、UIテーマに応じた警告アイコン（三角形に感嘆符など）や黄色/オレンジ系の配色で表示されることが一般的。デフォルトでは5秒間表示された後に自動的に閉じる。

**期待されるアクション**：ユーザーは警告内容を確認し、必要に応じて対処を行う。通知をクリックして詳細画面や設定画面に遷移するなどの追加機能を設定することが推奨される。

## 通知種別

アプリ内通知（In-Window Notification）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（UIスレッド上で実行） |
| 優先度 | 通常（ただし視覚的に目立つスタイル） |
| リトライ | なし |

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

WindowNotificationManager が配置されている TopLevel の AdornerLayer 上に通知カードが追加される。表示位置は Position プロパティにより決定され、TopRight（右上）がデフォルト。

## 通知テンプレート

### アプリ内通知の場合

| 項目 | 内容 |
|-----|------|
| 表示位置 | NotificationPosition で指定（デフォルト: TopRight） |
| 最大表示数 | MaxItems で指定（デフォルト: 5） |
| スタイル | `:warning` 疑似クラスが適用される |

### 本文テンプレート

```
NotificationCard
├── Title: {タイトルテキスト}（例：「接続不安定」）
├── Message: {メッセージテキスト}（例：「ネットワーク接続が不安定です。確認してください。」）
└── CloseButton（オプション）
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | UI通知のため添付ファイルは存在しない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| Title | 通知のタイトル | Notification.Title プロパティ | No |
| Message | 通知のメッセージ | Notification.Message プロパティ | No |
| Expiration | 自動クローズまでの時間 | Notification.Expiration プロパティ | No（デフォルト5秒） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | INotificationManager.Show(INotification) | Notification.Type == NotificationType.Warning | 標準的な警告通知表示 |
| API呼び出し | WindowNotificationManager.Show(object, NotificationType) | type == NotificationType.Warning | 直接タイプ指定 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| UIスレッド外からの呼び出し | Dispatcher.UIThread.VerifyAccess() で検証される |
| WindowNotificationManager 未配置 | 通知マネージャーがウィンドウに配置されていない場合は表示されない |
| 同一警告の重複 | アプリケーション側で重複排除ロジックを実装することを推奨 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[警告条件検知] --> B[Show メソッド呼び出し]
    B --> C[UIスレッド検証]
    C -->|OK| D[NotificationCard 作成]
    C -->|NG| E[例外スロー]
    D --> F[NotificationType.Warning 設定]
    F --> G[:warning 疑似クラス適用]
    G --> H[黄色/オレンジベースのスタイル適用]
    H --> I[_items に追加]
    I --> J{MaxItems 超過?}
    J -->|Yes| K[最古の通知をクローズ]
    J -->|No| L[タイマー設定]
    K --> L
    L --> M[表示完了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | UI通知のためデータベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | UI通知のためデータベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| InvalidOperationException | UIスレッド外からの呼び出し | Dispatcher.UIThread.Post() を使用 |
| NullReferenceException | NotificationManager が null | WindowNotificationManager を正しく配置 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（MaxItems で同時表示数を制限） |
| 1日あたり上限 | なし |

### 配信時間帯

特になし（アプリケーション実行中はいつでも表示可能）

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

- 通知内容にユーザー入力が含まれる場合はエスケープ処理を行うこと
- システム内部の詳細なエラー情報を警告に含めないこと
- セキュリティ関連の警告は適切なログにも記録すること

## 備考

- Warning通知は黄色/オレンジ系統のスタイルで表示され、注意を促す
- サンプルコード（NotificationViewModel.cs）では Warning タイプの使用例あり
- 警告の自動クローズ時間は状況に応じて延長を検討（Expiration = TimeSpan.Zero で手動クローズのみにすることも可能）

---

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

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

### 推奨読解順序

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

Warning タイプの定義と通知の基本構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | NotificationType.cs | `src/Avalonia.Controls/Notifications/NotificationType.cs` | Warning は enum の3番目の値（値 = 2） |
| 1-2 | Notification.cs | `src/Avalonia.Controls/Notifications/Notification.cs` | コンストラクタで NotificationType を指定可能 |

**読解のコツ**: NotificationType.cs の10行目に `Warning` が定義されている。

#### Step 2: 使用例を理解する

サンプルコードでの Warning 通知の使用方法を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NotificationViewModel.cs | `samples/ControlCatalog/ViewModels/NotificationViewModel.cs` | Warning タイプでの通知表示例 |

**主要処理フロー**:
- **14行目**: `NotificationType.Warning` を指定してカスタム通知を表示

#### Step 3: 疑似クラス適用を理解する

Warning タイプに対応するスタイルの適用を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | NotificationCard.cs | `src/Avalonia.Controls/Notifications/NotificationCard.cs` | `:warning` 疑似クラスの適用ロジック |

**主要処理フロー**:
- **12行目**: PseudoClasses属性で `:warning` を定義
- **186-188行目**: `case NotificationType.Warning` で `:warning` を追加

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

```
アプリケーションコード（警告条件検知時）
    │
    ├─ new Notification("警告", "注意が必要です", NotificationType.Warning)
    │
    └─ INotificationManager.Show(notification)
           │
           └─ WindowNotificationManager.Show()
                  │
                  ├─ new NotificationCard { NotificationType = Warning }
                  │      └─ UpdateNotificationType() → :warning 疑似クラス設定
                  │
                  └─ 黄色/オレンジベースのスタイルで表示
```

### データフロー図

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

Notification             WindowNotificationManager          NotificationCard
├─ Title         ───▶   ├─ UIスレッド検証          ───▶    ├─ Content = Notification
├─ Message              ├─ NotificationCard 作成            ├─ NotificationType = Warning
├─ Type=Warning         └─ 疑似クラス適用                   ├─ :warning 疑似クラス
└─ Expiration                                               └─ 黄色/オレンジスタイル適用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NotificationType.cs | `src/Avalonia.Controls/Notifications/NotificationType.cs` | ソース | Warning 列挙値の定義 |
| Notification.cs | `src/Avalonia.Controls/Notifications/Notification.cs` | ソース | 通知クラス |
| WindowNotificationManager.cs | `src/Avalonia.Controls/Notifications/WindowNotificationManager.cs` | ソース | 通知表示ロジック |
| NotificationCard.cs | `src/Avalonia.Controls/Notifications/NotificationCard.cs` | ソース | :warning 疑似クラス適用 |
| NotificationViewModel.cs | `samples/ControlCatalog/ViewModels/NotificationViewModel.cs` | サンプル | Warning通知の使用例 |
| NotificationCard.xaml | `src/Avalonia.Themes.Fluent/Controls/NotificationCard.xaml` | テンプレート | Fluentテーマのスタイル |
| NotificationCard.xaml | `src/Avalonia.Themes.Simple/Controls/NotificationCard.xaml` | テンプレート | Simpleテーマのスタイル |
