# 機能設計書 115-Notifications

## 概要

本ドキュメントは、Avaloniaフレームワークの通知機能について、その設計と実装を詳細に記述する機能設計書である。トースト形式のウィンドウ内通知を表示するためのコントロールとマネージャーを提供する。

### 本機能の処理概要

Notificationsは、Avaloniaアプリケーションにおいて、ユーザーへのフィードバックメッセージやアラートを画面内にポップアップ表示するための通知システムである。情報、成功、警告、エラーの4種類の通知タイプをサポートし、自動消去や手動クローズが可能である。

**業務上の目的・背景**：アプリケーションのユーザーエクスペリエンス向上のため、操作結果やシステム状態をユーザーにわかりやすく伝える必要がある。ダイアログボックスは操作を中断させるが、トースト通知は非侵入的にメッセージを表示でき、ユーザーの作業フローを妨げない。また、複数の通知を同時に表示し、自動的に消去することで、情報過多を防ぐ。

**機能の利用シーン**：ファイル保存完了通知、エラー発生時のアラート、バックグラウンド処理完了通知、新着メッセージ通知、設定変更の確認など、様々な場面でユーザーへのフィードバックとして使用される。

**主要な処理内容**：
1. 通知の表示（Show）
2. 通知の自動消去（Expiration）
3. 通知のクローズ処理
4. 通知位置の管理（Position）
5. 最大表示数の制御（MaxItems）

**関連システム・外部連携**：Avalonia.Controls（TopLevel、AdornerLayer）

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 40 | Notifications | 主機能 | 通知のデモ。トースト通知とウィンドウ通知 |

## 機能種別

UIコントロール / 通知表示 / ユーザーフィードバック

## 入力仕様

### 入力パラメータ

#### WindowNotificationManagerプロパティ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Position | NotificationPosition | No | 通知表示位置（TopLeft/TopRight/BottomLeft/BottomRight/TopCenter/BottomCenter） | 列挙値 |
| MaxItems | int | No | 最大表示数（デフォルト: 5） | 1以上 |

#### Show()メソッドパラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| content | object | Yes | 通知の内容 | - |
| type | NotificationType | No | 通知タイプ（Information/Success/Warning/Error） | 列挙値 |
| expiration | TimeSpan | No | 自動消去までの時間（デフォルト: 5秒、Zero=自動消去なし） | - |
| onClick | Action | No | クリック時のコールバック | - |
| onClose | Action | No | クローズ時のコールバック | - |
| classes | string[] | No | 追加するスタイルクラス | - |

#### INotificationインターフェース

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Title | string | No | 通知タイトル | - |
| Message | string | No | 通知メッセージ | - |
| Type | NotificationType | Yes | 通知タイプ | 列挙値 |
| Expiration | TimeSpan | Yes | 有効期限 | - |
| OnClick | Action | No | クリックコールバック | - |
| OnClose | Action | No | クローズコールバック | - |

### 入力データソース

- コードからのShow()メソッド呼び出し
- INotificationオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| NotificationCard | Control | 表示される通知カードコントロール |
| NotificationClosedEvent | RoutedEvent | 通知クローズ時に発火するイベント |

### 出力先

- AdornerLayer上への通知カード表示
- イベントハンドラへのコールバック

## 処理フロー

### 処理シーケンス

```
1. WindowNotificationManagerの初期化
   └─ InstallFromTopLevel()でAdornerLayerに追加
2. 通知の表示要求
   └─ Show()メソッド呼び出し
3. NotificationCardの生成
   └─ 通知タイプに応じたスタイル適用
4. 通知の追加
   └─ _itemsコレクションに追加
5. 最大数チェック
   └─ MaxItemsを超えた場合は最も古い通知をクローズ
6. 自動消去タイマー設定
   └─ DispatcherTimer.RunOnce()で遅延クローズ
7. 通知のクローズ
   └─ NotificationClosedEvent発火
   └─ コレクションから削除
```

### フローチャート

```mermaid
flowchart TD
    A[Show呼び出し] --> B[NotificationCard生成]
    B --> C[スタイルクラス適用]
    C --> D[イベントハンドラ登録]
    D --> E[_itemsに追加]
    E --> F{MaxItems超過?}
    F -->|Yes| G[最古の通知をクローズ]
    F -->|No| H{Expiration > 0?}
    G --> H
    H -->|Yes| I[タイマー設定]
    H -->|No| J[手動クローズ待ち]
    I --> K[タイマー発火]
    K --> L[Close呼び出し]
    J --> L
    L --> M[IsClosing = true]
    M --> N[アニメーション]
    N --> O[NotificationClosedEvent]
    O --> P[_itemsから削除]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルト有効期限 | 有効期限未指定時は5秒 | expiration == null |
| BR-002 | 無期限通知 | Expiration == TimeSpan.Zeroの場合は自動消去しない | 常時 |
| BR-003 | 最大数制御 | MaxItemsを超えた場合は最も古い通知をクローズ | 常時 |
| BR-004 | 重複クローズ防止 | IsClosing=trueの通知はClose()を無視 | 常時 |
| BR-005 | UIスレッド検証 | Show/Close/CloseAllはUIスレッドから呼び出す必要がある | 常時 |

### 計算ロジック

最大数チェック：
```csharp
if (Notifications.Count(i => !i.IsClosing) > MaxItems)
{
    Notifications.First(i => !i.IsClosing).Close();
}
```

## データベース操作仕様

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | UIスレッド外からの呼び出し | UIスレッドから呼び出す |

### リトライ仕様

該当なし。

## トランザクション仕様

該当なし。

## パフォーマンス要件

- DispatcherTimerによる効率的なタイマー管理
- OnDetachedFromVisualTreeで_itemsをクリアしてメモリリーク防止

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

特になし。

## 備考

- 通知タイプに応じた疑似クラス（:error、:information、:success、:warning）が自動適用される
- CloseOnClick添付プロパティにより、通知内のボタンクリックで自動クローズ可能

---

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

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

### 推奨読解順序

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

まず、通知システムで使用されるインターフェースと列挙型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | INotification.cs | `src/Avalonia.Controls/Notifications/INotification.cs` | 通知データのインターフェース |
| 1-2 | NotificationType.cs | `src/Avalonia.Controls/Notifications/NotificationType.cs` | 通知タイプの列挙型 |
| 1-3 | NotificationPosition.cs | `src/Avalonia.Controls/Notifications/NotificationPosition.cs` | 表示位置の列挙型 |
| 1-4 | INotificationManager.cs | `src/Avalonia.Controls/Notifications/INotificationManager.cs` | マネージャーインターフェース |

**読解のコツ**: INotificationインターフェースの各プロパティの意味を把握することで、通知システム全体の設計が理解しやすくなる。

#### Step 2: 通知マネージャーを理解する

処理の中核となるWindowNotificationManagerを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WindowNotificationManager.cs | `src/Avalonia.Controls/Notifications/WindowNotificationManager.cs` | 通知管理の中核クラス |

**主要処理フロー**:
1. **17-19行目**: _itemsコレクションの管理
2. **29-30行目**: PositionPropertyの定義
3. **45-46行目**: MaxItemsPropertyの定義（デフォルト5）
4. **61-67行目**: コンストラクタでTopLevelへのインストール
5. **97-100行目**: Show(INotification)メソッド
6. **124-174行目**: Show()メソッドの本体実装
7. **163-166行目**: MaxItems超過時の処理
8. **173行目**: DispatcherTimer.RunOnceによる自動クローズ
9. **177-186行目**: Close()とCloseAll()メソッド
10. **216-225行目**: InstallFromTopLevel()でAdornerLayerに追加

#### Step 3: 通知カードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | NotificationCard.cs | `src/Avalonia.Controls/Notifications/NotificationCard.cs` | 通知表示コントロール |

**主要処理フロー**:
- **12行目**: PseudoClasses属性で疑似クラス定義
- **13行目**: ContentControlの派生
- **33-37行目**: IsClosingプロパティ
- **42-43行目**: IsClosingPropertyの定義
- **63-67行目**: NotificationTypeプロパティ
- **78-79行目**: NotificationClosedEvent定義
- **133-144行目**: Close()メソッド
- **171-191行目**: UpdateNotificationType()で疑似クラス適用

#### Step 4: 補助クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Notification.cs | `src/Avalonia.Controls/Notifications/Notification.cs` | 標準通知実装 |
| 4-2 | ReversibleStackPanel.cs | `src/Avalonia.Controls/Notifications/ReversibleStackPanel.cs` | 逆順スタックパネル |

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

```
Application
    │
    └─ WindowNotificationManager
           ├─ InstallFromTopLevel()
           │      └─ AdornerLayer.Children.Add()
           │
           ├─ Show()
           │      ├─ new NotificationCard()
           │      ├─ _items.Add()
           │      └─ DispatcherTimer.RunOnce()
           │
           ├─ Close()
           │      └─ NotificationCard.Close()
           │             └─ IsClosing = true
           │
           └─ CloseAll()
                  └─ Notifications.Do(x => x.Close())
```

### データフロー図

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

INotification ──────▶ WindowNotificationManager ───▶ NotificationCard
    or                       │                              │
object content               ▼                              ▼
                        Show()                        AdornerLayer
                             │                        (画面表示)
                             ▼
                    NotificationCard生成
                             │
                             ▼
                    _items.Add()
                             │
                             ▼
TimeSpan expiration ──▶ DispatcherTimer ───────────▶ Close()
                                                         │
                                                         ▼
                                              NotificationClosedEvent
                                                         │
                                                         ▼
                                               onClose?.Invoke()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WindowNotificationManager.cs | `src/Avalonia.Controls/Notifications/WindowNotificationManager.cs` | ソース | 通知マネージャー |
| NotificationCard.cs | `src/Avalonia.Controls/Notifications/NotificationCard.cs` | ソース | 通知カードコントロール |
| INotification.cs | `src/Avalonia.Controls/Notifications/INotification.cs` | ソース | 通知インターフェース |
| INotificationManager.cs | `src/Avalonia.Controls/Notifications/INotificationManager.cs` | ソース | マネージャーインターフェース |
| IManagedNotificationManager.cs | `src/Avalonia.Controls/Notifications/IManagedNotificationManager.cs` | ソース | 拡張マネージャーインターフェース |
| Notification.cs | `src/Avalonia.Controls/Notifications/Notification.cs` | ソース | 標準通知実装 |
| NotificationType.cs | `src/Avalonia.Controls/Notifications/NotificationType.cs` | ソース | 通知タイプ列挙型 |
| NotificationPosition.cs | `src/Avalonia.Controls/Notifications/NotificationPosition.cs` | ソース | 表示位置列挙型 |
| ReversibleStackPanel.cs | `src/Avalonia.Controls/Notifications/ReversibleStackPanel.cs` | ソース | 逆順スタックパネル |
