# 通知設計書 4-Error

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるError（エラー）通知の設計について記述する。Error通知は、エラーや問題発生をユーザーに通知するためのUI通知であり、NotificationType.Error として定義されている。

### 本通知の処理概要

Error通知は、アプリケーションにおいてエラーや問題が発生したことをユーザーに視覚的に伝えるための仕組みである。

**業務上の目的・背景**：アプリケーション運用において、ユーザーの操作が失敗した場合やシステムエラーが発生した場合、その情報をユーザーに明確に伝える必要がある。エラー通知により、ユーザーは問題の発生を認識し、適切な対処（再試行、サポートへの連絡、設定の確認など）を行うことができる。赤色を基調としたビジュアルにより、深刻な問題であることを直感的に伝え、ユーザーの注意を引く。

**通知の送信タイミング**：API呼び出しの失敗、ファイル操作エラー、ネットワーク接続エラー、認証失敗、バリデーションエラー、予期しない例外発生時など、操作が正常に完了できなかった場合。

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

**通知内容の概要**：タイトル（Title）とメッセージ（Message）の2つのテキスト要素で構成される。NotificationType.Error として識別され、UIテーマに応じたエラーアイコン（X印や円に感嘆符など）や赤系の配色で表示されることが一般的。デフォルトでは5秒間表示された後に自動的に閉じるが、重要なエラーの場合は手動クローズのみにすることも推奨される。

**期待されるアクション**：ユーザーはエラー内容を確認し、必要に応じて再試行、設定の確認、サポートへの連絡などの対処を行う。通知をクリックして詳細画面やヘルプページに遷移するなどの追加機能を設定することが推奨される。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（UIスレッド上で実行） |
| 優先度 | 高（視覚的に最も目立つスタイル） |
| リトライ | なし（通知自体のリトライは行わない） |

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
NotificationCard
├── Title: {タイトルテキスト}（例：「保存エラー」）
├── Message: {メッセージテキスト}（例：「ファイルの保存に失敗しました。権限を確認してください。」）
└── CloseButton（オプション）
```

### 添付ファイル

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

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | INotificationManager.Show(INotification) | Notification.Type == NotificationType.Error | 標準的なエラー通知表示 |
| API呼び出し | WindowNotificationManager.Show(object, NotificationType) | type == NotificationType.Error | 直接タイプ指定 |
| 例外ハンドラ | try-catch ブロック内 | 例外発生時 | エラーメッセージを表示 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[エラー発生] --> B[Show メソッド呼び出し]
    B --> C[UIスレッド検証]
    C -->|OK| D[NotificationCard 作成]
    C -->|NG| E[例外スロー]
    D --> F[NotificationType.Error 設定]
    F --> G[:error 疑似クラス適用]
    G --> H[赤ベースのスタイル適用]
    H --> I[_items に追加]
    I --> J{MaxItems 超過?}
    J -->|Yes| K[最古の通知をクローズ]
    J -->|No| L{Expiration == 0?}
    K --> L
    L -->|Yes| M[手動クローズまで表示]
    L -->|No| N[タイマー設定]
    M --> O[表示完了]
    N --> O
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- エラーメッセージにスタックトレースやシステム内部情報を含めないこと
- ユーザー入力が含まれる場合はエスケープ処理を行うこと
- 認証エラーの詳細（「パスワードが間違っています」など）を過度に開示しないこと
- エラーログは適切に記録すること（通知とは別に）

## 備考

- Error通知は赤色系統のスタイルで表示され、最も目立つデザインとなる
- 重要なエラーは Expiration = TimeSpan.Zero を設定し、ユーザーが明示的に閉じるまで表示を継続することを推奨
- エラー通知には OnClick コールバックで詳細画面への遷移を設定することが有効

---

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

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

### 推奨読解順序

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

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

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

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

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

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

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

**主要処理フロー**:
- **12行目**: PseudoClasses属性で `:error` を定義（最初に記載されている）
- **175-176行目**: `case NotificationType.Error` で `:error` を追加

#### Step 3: 表示制御を理解する

自動クローズの制御方法を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WindowNotificationManager.cs | `src/Avalonia.Controls/Notifications/WindowNotificationManager.cs` | Expiration == 0 の場合の処理 |

**主要処理フロー**:
- **168-171行目**: `if (expiration == TimeSpan.Zero) return;` で自動クローズをスキップ

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

```
アプリケーションコード（エラー発生時）
    │
    ├─ new Notification("エラー", "処理に失敗しました", NotificationType.Error, TimeSpan.Zero)
    │
    └─ INotificationManager.Show(notification)
           │
           └─ WindowNotificationManager.Show()
                  │
                  ├─ new NotificationCard { NotificationType = Error }
                  │      └─ UpdateNotificationType() → :error 疑似クラス設定
                  │
                  ├─ Expiration == 0 → タイマー設定スキップ
                  │
                  └─ 赤ベースのスタイルで表示（手動クローズまで）
```

### データフロー図

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

Notification             WindowNotificationManager          NotificationCard
├─ Title         ───▶   ├─ UIスレッド検証          ───▶    ├─ Content = Notification
├─ Message              ├─ NotificationCard 作成            ├─ NotificationType = Error
├─ Type=Error           ├─ 疑似クラス適用                   ├─ :error 疑似クラス
└─ Expiration=0         └─ タイマー設定判定                 └─ 赤スタイル適用（永続表示）
```

### 関連ファイル一覧

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