# 通知設計書 1-Information

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるInformation（情報）通知の設計について記述する。Information通知は、ユーザーへの一般的な情報提供を目的としたUI通知であり、NotificationType.Information として定義されている。

### 本通知の処理概要

Information通知は、アプリケーションからユーザーに対して一般的な情報を視覚的に伝えるための仕組みである。

**業務上の目的・背景**：アプリケーションにおいて、ユーザーに対して処理の状態、ヒント、一般的なお知らせなどの情報を非侵入的な方法で伝える必要がある。従来のダイアログボックスとは異なり、通知はユーザーの作業を中断させることなく情報を表示し、一定時間後に自動的に消える。これにより、ユーザーエクスペリエンスを向上させながら必要な情報を確実に伝達できる。

**通知の送信タイミング**：アプリケーションコードから `INotificationManager.Show()` または `IManagedNotificationManager.Show()` メソッドが呼び出されたとき。開発者が任意のタイミングで通知を発生させることができる。例えば、データのロード完了、設定の保存完了、バックグラウンド処理の進捗状況などのイベント発生時に使用される。

**通知の受信者**：アプリケーションのUI上で通知が表示されるウィンドウを視認しているエンドユーザー。WindowNotificationManager が配置されている TopLevel（通常はメインウィンドウ）の AdornerLayer 上に通知が表示される。

**通知内容の概要**：タイトル（Title）とメッセージ（Message）の2つのテキスト要素で構成される。NotificationType.Information として識別され、UIテーマに応じた情報アイコンや青系の配色で表示されることが一般的。デフォルトでは5秒間表示された後に自動的に閉じる。

**期待されるアクション**：ユーザーは通知内容を確認し、必要に応じて通知をクリックして追加のアクション（OnClickコールバック）を実行するか、自動的に消えるまで待つか、明示的に閉じるボタンで通知を閉じることができる。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（UIスレッド上で実行） |
| 優先度 | 通常 |
| リトライ | なし |

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
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.Information | 標準的な通知表示 |
| API呼び出し | IManagedNotificationManager.Show(object) | INotification でない場合デフォルトで Information | カスタムコンテンツの場合 |
| API呼び出し | WindowNotificationManager.Show(object, NotificationType) | type == NotificationType.Information | 直接指定 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| UIスレッド外からの呼び出し | Dispatcher.UIThread.VerifyAccess() で検証され、UIスレッド外からの呼び出しは例外となる |
| WindowNotificationManager 未配置 | 通知マネージャーがウィンドウに配置されていない場合は表示されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[INotificationManager.Show 呼び出し] --> B[UIスレッド検証]
    B -->|OK| C[NotificationCard 作成]
    B -->|NG| D[例外スロー]
    C --> E[NotificationType設定]
    E --> F[:information 疑似クラス適用]
    F --> G[イベントハンドラ登録]
    G --> H[_items に追加]
    H --> I{MaxItems 超過?}
    I -->|Yes| J[最古の通知をクローズ]
    I -->|No| K{Expiration == 0?}
    J --> K
    K -->|Yes| L[手動クローズまで表示]
    K -->|No| M[DispatcherTimer でクローズ予約]
    L --> N[表示完了]
    M --> N
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- 通知内容にユーザー入力が含まれる場合はXSS対策としてエスケープ処理を行うこと
- 機密情報（パスワード、個人情報等）は通知に含めないこと
- 通知は画面上に表示されるため、肩越しに覗き見される可能性を考慮すること

## 備考

- Information通知はNotificationTypeの中でデフォルト値として扱われる
- FluentテーマとSimpleテーマで異なるビジュアルスタイルが適用される
- 通知クリック時のコールバック（OnClick）と通知クローズ時のコールバック（OnClose）を設定可能

---

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

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

### 推奨読解順序

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

まず、通知の基本データ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | NotificationType.cs | `src/Avalonia.Controls/Notifications/NotificationType.cs` | NotificationType列挙型の定義。Information は最初の値（デフォルト） |
| 1-2 | INotification.cs | `src/Avalonia.Controls/Notifications/INotification.cs` | 通知インターフェース。Title, Message, Type, Expiration, OnClick, OnClose を定義 |
| 1-3 | Notification.cs | `src/Avalonia.Controls/Notifications/Notification.cs` | INotification の標準実装クラス。INotifyPropertyChanged も実装 |

**読解のコツ**: NotificationType.cs は4行のシンプルな列挙型定義だが、Information がデフォルト値（0）であることに注目。

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

処理の起点となる通知マネージャーのインターフェースと実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | INotificationManager.cs | `src/Avalonia.Controls/Notifications/INotificationManager.cs` | Show, Close, CloseAll メソッドを定義 |
| 2-2 | IManagedNotificationManager.cs | `src/Avalonia.Controls/Notifications/IManagedNotificationManager.cs` | Show(object) メソッドを追加定義 |
| 2-3 | WindowNotificationManager.cs | `src/Avalonia.Controls/Notifications/WindowNotificationManager.cs` | 実際の通知表示ロジック |

**主要処理フロー**:
1. **97-100行目**: Show(INotification) メソッドで通知を受け取り、内部の Show メソッドに委譲
2. **103-113行目**: Show(object) メソッドでオブジェクトを受け取り、INotification かどうかで分岐
3. **124-174行目**: 実際の表示処理。NotificationCard の作成、イベント登録、タイマー設定

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

通知の視覚的表現を担当するコントロールを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | NotificationCard.cs | `src/Avalonia.Controls/Notifications/NotificationCard.cs` | 通知を表示するコントロール。疑似クラスによるスタイル切り替え |

**主要処理フロー**:
- **12行目**: PseudoClasses属性で `:error`, `:information`, `:success`, `:warning` を定義
- **171-191行目**: UpdateNotificationType() メソッドで NotificationType に応じた疑似クラスを設定
- **136-144行目**: Close() メソッドで通知のクローズ処理

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

```
アプリケーションコード
    │
    ├─ INotificationManager.Show(INotification)
    │      │
    │      └─ WindowNotificationManager.Show(INotification, NotificationType, ...)
    │             │
    │             ├─ new NotificationCard()
    │             │      └─ UpdateNotificationType() → :information 疑似クラス設定
    │             │
    │             ├─ NotificationClosed イベント登録
    │             ├─ PointerPressed イベント登録
    │             ├─ _items.Add(notificationCard)
    │             │
    │             └─ DispatcherTimer.RunOnce(Close, expiration)
    │
    └─ IManagedNotificationManager.Show(object)
           │
           └─ 上記と同じフロー（INotification でない場合は Information がデフォルト）
```

### データフロー図

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

Notification             WindowNotificationManager          NotificationCard
├─ Title         ───▶   ├─ UIスレッド検証          ───▶    ├─ Content = Notification
├─ Message              ├─ NotificationCard 作成            ├─ NotificationType = Information
├─ Type=Information     ├─ 疑似クラス適用                   ├─ :information 疑似クラス
├─ Expiration           ├─ イベント登録                     ├─ 自動クローズタイマー
├─ OnClick              └─ タイマー設定                     └─ AdornerLayer 上に表示
└─ OnClose
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NotificationType.cs | `src/Avalonia.Controls/Notifications/NotificationType.cs` | ソース | 通知タイプ列挙型 |
| INotification.cs | `src/Avalonia.Controls/Notifications/INotification.cs` | ソース | 通知インターフェース |
| Notification.cs | `src/Avalonia.Controls/Notifications/Notification.cs` | ソース | 通知クラス |
| INotificationManager.cs | `src/Avalonia.Controls/Notifications/INotificationManager.cs` | ソース | 通知マネージャーIF |
| IManagedNotificationManager.cs | `src/Avalonia.Controls/Notifications/IManagedNotificationManager.cs` | ソース | 管理通知マネージャーIF |
| WindowNotificationManager.cs | `src/Avalonia.Controls/Notifications/WindowNotificationManager.cs` | ソース | ウィンドウ通知マネージャー |
| NotificationCard.cs | `src/Avalonia.Controls/Notifications/NotificationCard.cs` | ソース | 通知カードコントロール |
| NotificationCard.xaml | `src/Avalonia.Themes.Fluent/Controls/NotificationCard.xaml` | テンプレート | Fluentテーマのスタイル |
| NotificationCard.xaml | `src/Avalonia.Themes.Simple/Controls/NotificationCard.xaml` | テンプレート | Simpleテーマのスタイル |
| NotificationViewModel.cs | `samples/ControlCatalog/ViewModels/NotificationViewModel.cs` | サンプル | 使用例 |
