# 通知設計書 14-ControlNoticeDialog

## 概要

ターミナルコントロール（ControlCore）から発生した通知（RaiseNotice）を表示するためのモーダルダイアログ（ContentDialog）の設計書である。読み取り専用モードの有効化警告やレンダラー警告など、さまざまなレベルの通知を統一的に表示する汎用的な通知ダイアログである。

### 本通知の処理概要

ControlNoticeDialogは、TerminalControlのRaiseNoticeイベントを受けて表示される汎用通知ダイアログである。NoticeLevel（Debug/Info/Warning/Error）に応じたタイトルと、動的なメッセージ内容を表示する。

**業務上の目的・背景**：ターミナルコントロール内部で発生するさまざまな通知（読み取り専用モードの有効化通知、シェーダーコンパイルエラー、レンダラー警告など）をユーザーに伝える必要がある。これらの通知は発生源や内容が多様であるため、NoticeLevel列挙型による統一的な分類と、汎用的なダイアログUIを使用して表示する設計となっている。

**通知の送信タイミング**：ControlCoreまたはTermControlがRaiseNoticeイベントを発火した時点でトリガーされる。具体的には、読み取り専用モードでユーザーが入力しようとした場合（`_raiseReadOnlyWarning`）、レンダラーがシェーダーファイルの読み込みやコンパイルに失敗した場合（`_RendererWarning`）などに発火される。

**通知の受信者**：アプリケーションを操作中のユーザー本人。モーダルダイアログとして表示される。

**通知内容の概要**：NoticeLevelに応じたタイトル（Debug/Information/Warning/Error）と、イベントから渡されたメッセージ文字列が表示される。メッセージテキストは選択可能（IsTextSelectionEnabled="True"）であり、コンテキストメニューからコピーが可能。

**期待されるアクション**：ユーザーは通知内容を確認し、「OK」ボタンを押してダイアログを閉じる。通知内容に応じて、設定変更やトラブルシューティングなどの対応を行うことが想定される。

## 通知種別

アプリ内通知（モーダルダイアログ / ContentDialog）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（UIスレッドへのディスパッチ後にモーダル表示） |
| 優先度 | 中（NoticeLevelに依存） |
| リトライ | 無し |

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

RaiseNoticeイベントの発火元TermControlが属するTerminalPageに対して表示される。送信先の明示的な決定ロジックは存在しない。

## 通知テンプレート

### ダイアログ構成

| 項目 | 内容 |
|-----|------|
| タイトル | NoticeLevel依存（Debug / Information / Warning / Error） |
| 内容 | 動的メッセージ（TextBlock内のRun要素） |
| プライマリボタン | OK |
| デフォルトボタン | Primary（OK） |

### NoticeLevel別タイトル

| NoticeLevel | 値 | タイトル文字列 |
|------------|-----|---------------|
| Debug | 10 | Debug |
| Info | 20 | Information |
| Warning | 30 | Warning |
| Error | 40 | Error |

### 本文テンプレート

```
Title: {NoticeLevel別タイトル}
Content: {動的メッセージ}
[OK]
```

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| title | NoticeLevelに応じたタイトル | NoticeEventArgs.Level()からResources.reswで変換 | Yes |
| message | 通知メッセージ本文 | NoticeEventArgs.Message() | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| システムイベント | RaiseNotice | 常に表示（ダイアログプレゼンターが存在する場合） | 読み取り専用モード入力時 |
| システムイベント | RendererWarning | レンダラー警告発生時 | シェーダーファイルエラー等 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ダイアログプレゼンターが未設定 | `_dialogPresenter.get()`がnullptrの場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ControlCore/TermControlでRaiseNoticeイベント発火] --> B[TermControl._coreRaisedNotice]
    B --> C[TermControl.RaiseNotice.raiseでイベント中継]
    C --> D[TerminalPage._ControlNoticeRaisedHandler]
    D --> E[UIスレッドへディスパッチ]
    E --> F[NoticeLevelに応じたタイトル決定]
    F --> G[_ShowControlNoticeDialog呼び出し]
    G --> H[FindName - XAMLオブジェクトロード]
    H --> I[タイトルとメッセージ設定]
    I --> J[presenter.ShowDialog表示]
    J --> K[ユーザーがOKをクリック]
    K --> L[終了]
```

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

### 参照テーブル一覧

該当なし。

### 更新テーブル一覧

該当なし。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ダイアログプレゼンター未設定 | ウィンドウ初期化前にRaiseNoticeが発火された場合 | `_dialogPresenter.get()`がnullptrで処理をスキップ |
| UIスレッドディスパッチ失敗 | ウィンドウが既に破棄されている場合 | `weak_ref`のget()がnullptrで処理を中止 |

### リトライ仕様

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

## 配信設定

### レート制限

特に制限なし。ただし、ダイアログはモーダルであるため、ユーザーが閉じるまで次のダイアログは表示されない。

### 配信時間帯

制限なし。

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

- メッセージテキストは`IsTextSelectionEnabled="True"`で選択可能であり、コンテキストメニュー（TextMenuFlyout）からコピーできる。
- メッセージ内容はターミナルコントロール内部から生成されるため、外部からの注入リスクは低い。

## 備考

- `x:Load="False"`により遅延読み込みが適用されている。
- RaiseNoticeイベントはControlCore -> TermControl -> TerminalPageの3層を経由して伝播する。
- ControlCoreの`_raiseReadOnlyWarning`（行2228-2231）は`NoticeLevel::Info`で通知を発行する。
- TermControlの`_RendererWarning`は`NoticeLevel::Warning`で通知を発行する（行1354）。
- `TextBlock`の`TextWrapping`は`WrapWholeWords`に設定されており、単語単位で折り返される。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | EventArgs.idl | `src/cascadia/TerminalControl/EventArgs.idl` | 行77-89: NoticeLevel列挙型（Debug=10, Info=20, Warning=30, Error=40）とNoticeEventArgsランタイムクラスの定義 |
| 1-2 | EventArgs.h | `src/cascadia/TerminalControl/EventArgs.h` | 行116-129: NoticeEventArgsの実装。Level()とMessage()プロパティ |
| 1-3 | TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | 行133-145: ControlNoticeDialogのUI定義。TextBlock内のRun要素（NoticeMessage） |

**読解のコツ**: NoticeEventArgsはNoticeLevel列挙型とhstring型のメッセージを保持するシンプルなデータクラスである。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | 行2228-2231: `_raiseReadOnlyWarning`メソッド。NoticeLevel::Infoで通知を発行 |
| 2-2 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | 行1354-1355: レンダラー警告のRaiseNotice発火 |

#### Step 3: イベント伝播チェーンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | 行312: ControlCoreのRaiseNoticeイベント購読 |
| 3-2 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | 行3645-3652: `_coreRaisedNotice`ハンドラ。TermControlのRaiseNoticeイベントを中継 |
| 3-3 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | 行1955: TermControlのRaiseNoticeイベント購読 |
| 3-4 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | 行3143-3189: `_ControlNoticeRaisedHandler`と`_ShowControlNoticeDialog`の実装 |

**主要処理フロー**:
1. **行3147**: UIスレッドへのディスパッチ（`co_await wil::resume_foreground`）
2. **行3154-3168**: NoticeLevelに応じたタイトル文字列の決定
3. **行3170**: `_ShowControlNoticeDialog(title, message)`呼び出し
4. **行3179**: `FindName(L"ControlNoticeDialog")`でXAMLオブジェクトをロード
5. **行3181**: タイトル設定
6. **行3184**: メッセージテキスト設定
7. **行3187**: `presenter.ShowDialog()`でモーダル表示

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

```
ControlCore::_raiseReadOnlyWarning (ControlCore.cpp:2228)
    |
    +-- RaiseNotice.raise() (NoticeLevel::Info)
            |
            +-- TermControl::_coreRaisedNotice (TermControl.cpp:3645)
                    |
                    +-- RaiseNotice.raise() (中継)
                            |
                            +-- TerminalPage::_ControlNoticeRaisedHandler (TerminalPage.cpp:3143)
                                    |
                                    +-- co_await resume_foreground
                                    +-- NoticeLevel判定 -> タイトル決定
                                    +-- _ShowControlNoticeDialog(title, message)
                                            |
                                            +-- FindName(L"ControlNoticeDialog")
                                            +-- ControlNoticeDialog().Title(title)
                                            +-- NoticeMessage().Text(message)
                                            +-- presenter.ShowDialog()
```

### データフロー図

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

ControlCore内部イベント    ControlCore.cpp
(読み取り専用入力等)       RaiseNotice.raise()
        |                       |
        v                  TermControl.cpp                    ControlNoticeDialog
NoticeEventArgs            _coreRaisedNotice()  ------>      モーダル表示
(Level, Message)           RaiseNotice.raise()               (タイトル + メッセージ)
        |                       |
        v                  TerminalPage.cpp
                           _ControlNoticeRaisedHandler()
                           NoticeLevel -> タイトル変換
                           _ShowControlNoticeDialog()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| EventArgs.idl | `src/cascadia/TerminalControl/EventArgs.idl` | IDL定義 | NoticeLevel列挙型・NoticeEventArgsの定義 |
| EventArgs.h | `src/cascadia/TerminalControl/EventArgs.h` | ヘッダー | NoticeEventArgsの実装 |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | RaiseNoticeイベントの発火元 |
| ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | IDL定義 | RaiseNoticeイベントの宣言（行210） |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | RaiseNoticeイベントの中継 |
| TermControl.idl | `src/cascadia/TerminalControl/TermControl.idl` | IDL定義 | RaiseNoticeイベントの宣言（行69） |
| TerminalPage.xaml | `src/cascadia/TerminalApp/TerminalPage.xaml` | XAML定義 | ControlNoticeDialogのUI定義（行133-145） |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | ダイアログ表示処理（行3143-3189） |
| Resources.resw | `src/cascadia/TerminalApp/Resources/en-US/Resources.resw` | リソース | ボタンテキスト・NoticeLevelタイトル文字列 |
