# 通知設計書 2-Success

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるSuccess（成功）通知の設計について記述する。Success通知は、操作の正常完了をユーザーに通知するためのUI通知であり、NotificationType.Success として定義されている。

### 本通知の処理概要

Success通知は、アプリケーションにおいてユーザーが行った操作やシステムが実行した処理が正常に完了したことを視覚的に伝えるための仕組みである。

**業務上の目的・背景**：アプリケーションにおいて、ユーザーが実行した操作（ファイル保存、データ送信、設定変更など）が成功したことを明確にフィードバックすることは、ユーザーエクスペリエンスにおいて非常に重要である。成功通知により、ユーザーは自分の操作が正しく処理されたことを確認でき、次のアクションに安心して進むことができる。緑色を基調としたビジュアルにより、ポジティブな結果であることを直感的に伝える。

**通知の送信タイミング**：データの保存完了、送信完了、インポート/エクスポート完了、設定適用完了、認証成功など、ユーザーが開始した操作が成功裏に完了したとき。バックグラウンドタスクの正常終了時にも使用される。

**通知の受信者**：アプリケーションのUI上で通知が表示されるウィンドウを視認しているエンドユーザー。特に、成功を確認したい操作を実行したユーザーが主な対象となる。

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

**期待されるアクション**：ユーザーは成功の確認として通知内容を認識する。特別なアクションは必要ないが、通知をクリックして関連画面に遷移するなどの追加機能を設定することも可能。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
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.Success | 標準的な成功通知表示 |
| API呼び出し | WindowNotificationManager.Show(object, NotificationType) | type == NotificationType.Success | 直接タイプ指定 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[操作完了イベント発生] --> B[Show メソッド呼び出し]
    B --> C[UIスレッド検証]
    C -->|OK| D[NotificationCard 作成]
    C -->|NG| E[例外スロー]
    D --> F[NotificationType.Success 設定]
    F --> G[:success 疑似クラス適用]
    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日あたり上限 | なし |

### 配信時間帯

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

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

- 通知内容にユーザー入力が含まれる場合はエスケープ処理を行うこと
- 成功通知に機密情報（保存されたパスワード等）を含めないこと

## 備考

- Success通知は緑色系統のスタイルで表示され、成功を視覚的に伝える
- FluentテーマとSimpleテーマで異なるビジュアルスタイルが適用される
- 短い操作の連続成功時は通知の頻度に注意（ユーザーを煩わせない設計が必要）

---

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

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

### 推奨読解順序

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

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

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

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

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

通知表示の呼び出し方法を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WindowNotificationManager.cs | `src/Avalonia.Controls/Notifications/WindowNotificationManager.cs` | Show メソッドの NotificationType 引数 |

**主要処理フロー**:
1. **97-100行目**: INotification から Type を取得
2. **124-137行目**: NotificationCard 作成時に NotificationType を設定

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

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

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

**主要処理フロー**:
- **12行目**: PseudoClasses属性で `:success` を定義
- **183-184行目**: `case NotificationType.Success` で `:success` を追加

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

```
アプリケーションコード（操作成功時）
    │
    ├─ new Notification("保存完了", "正常に保存されました", NotificationType.Success)
    │
    └─ INotificationManager.Show(notification)
           │
           └─ WindowNotificationManager.Show()
                  │
                  ├─ new NotificationCard { NotificationType = Success }
                  │      └─ UpdateNotificationType() → :success 疑似クラス設定
                  │
                  └─ 緑色ベースのスタイルで表示
```

### データフロー図

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

Notification             WindowNotificationManager          NotificationCard
├─ Title         ───▶   ├─ UIスレッド検証          ───▶    ├─ Content = Notification
├─ Message              ├─ NotificationCard 作成            ├─ NotificationType = Success
├─ Type=Success         └─ 疑似クラス適用                   ├─ :success 疑似クラス
└─ Expiration                                               └─ 緑色スタイル適用
```

### 関連ファイル一覧

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