# 画面設計書 8-例外診断画面

## 概要

本ドキュメントは、Ruby on Rails フレームワークにおける例外診断画面の画面設計を定義するものである。

### 本画面の処理概要

本画面は、Railsアプリケーションで例外が発生した際に、詳細な診断情報を表示するエラーデバッグ画面である。例外クラス名、エラーメッセージ、スタックトレース、ソースコード抽出、リクエスト/レスポンス情報を一画面で確認できる。

**業務上の目的・背景**：開発中に発生した例外の原因を迅速に特定するために使用される。スタックトレースの各フレームからソースコードを抽出し、エラー発生箇所を視覚的に表示する。Application Trace（アプリケーションコード）とFramework Trace（フレームワークコード）を分離して表示し、デバッグ効率を向上させる。例外に対する修正候補（corrections）がある場合は提案も表示する。

**画面へのアクセス方法**：開発環境において、例外が発生した際に自動的に表示される。`action_dispatch.show_detailed_exceptions` がtrueの場合のみ詳細情報が表示される。

**主要な操作・処理内容**：
1. DebugExceptionsミドルウェアが例外をキャッチ
2. ExceptionWrapperで例外情報をラップ
3. 例外クラス名に対応するrescueテンプレートを選択
4. スタックトレースの各フレームからソースコードを抽出
5. リクエスト/レスポンス情報を収集
6. diagnostics.html.erbテンプレートで描画

**画面遷移**：
- 遷移元：例外発生時に自動表示
- 遷移先：特になし（エラー画面）

**権限による表示制御**：`action_dispatch.show_detailed_exceptions` 設定に依存。通常、開発環境でのみ詳細表示が有効。本番環境では簡易なエラーページに置き換えられる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | Debug Exceptions | 主機能 | 例外発生時の詳細診断情報表示処理 |
| 8 | Action Dispatch | 主機能 | DebugExceptionsミドルウェアによる例外キャプチャ・処理 |
| 5 | Action View | 補助機能 | スタックトレース・ソースコードのHTML描画 |

## 画面種別

エラー画面（例外診断）

## URL/ルーティング

本画面は特定のURLに紐づかない。例外発生時に自動的に表示される。

| HTTP メソッド | URL パターン | コントローラー#アクション | 備考 |
|--------------|--------------|--------------------------|------|
| * | * | - | 例外発生時に自動表示 |

## 入出力項目

本画面は表示専用であり、ユーザーからの入力項目は存在しない。

### 出力項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 例外クラス名 | h1要素 | 発生した例外のクラス名 |
| コントローラー#アクション | h1要素 | エラー発生箇所のコントローラーとアクション |
| エラーメッセージ | div要素 | 例外のメッセージ |
| 修正候補 | ul要素 | DidYouMean等による修正提案 |
| ソースコード抽出 | pre要素 | エラー発生箇所のソースコード |
| スタックトレース | div要素 | Application/Framework/Full Traceの切り替え表示 |
| リクエスト情報 | table要素 | リクエストパラメータ、ヘッダー等 |
| レスポンス情報 | div要素 | レスポンスヘッダー等 |
| 例外原因 | 折りたたみ要素 | has_cause?がtrueの場合、原因例外を表示 |

## 表示項目

| No | 項目ID | 項目名 | データ型 | 取得元 | 備考 |
|----|--------|--------|----------|--------|------|
| 1 | exception_class | 例外クラス名 | String | @exception_wrapper.exception_class_name | 例外のクラス名 |
| 2 | controller | コントローラー名 | String | @request.parameters['controller'] | リクエスト先コントローラー |
| 3 | action | アクション名 | String | @request.parameters['action'] | リクエスト先アクション |
| 4 | message | エラーメッセージ | String | @exception_wrapper.message | 例外のメッセージ |
| 5 | source_extracts | ソースコード | Array | @source_extracts | スタックトレース各フレームのソースコード |
| 6 | traces | スタックトレース | Hash | @traces | Application/Framework/Full Trace |
| 7 | corrections | 修正候補 | Array | @exception_wrapper.corrections | DidYouMean等の提案 |
| 8 | wrapped_causes | 例外原因チェーン | Array | @exception_wrapper.wrapped_causes | 原因例外のラップ |

## イベント仕様

### 1-トレース切り替え

**トリガー**: Application Trace/Framework Trace/Full Trace のリンクをクリック

**処理内容**:
1. JavaScript toggle関数を実行
2. 選択されたトレースタイプを表示、他を非表示

**遷移先**: 同一画面（表示切り替え）

### 2-例外原因の展開

**トリガー**: 例外原因のリンクをクリック（has_cause?がtrue時）

**処理内容**:
1. JavaScript toggle関数を実行
2. 原因例外の詳細（ソースコード、トレース）を展開

**遷移先**: 同一画面（詳細展開）

### 3-クリップボードコピー

**トリガー**: コピーボタンをクリック

**処理内容**:
1. 例外情報をクリップボードにコピー

**遷移先**: なし

## データベース更新仕様

### 操作別データベース影響一覧

本画面はデータベースアクセスを行わない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベースアクセスなし |

## メッセージ仕様

本画面では例外メッセージが主要な表示内容となる。

## 例外処理

本画面は例外発生時に表示される画面であるため、本画面自体の例外処理は最小限。

| 例外条件 | 動作 |
|---------|------|
| テンプレート描画中のエラー | プレーンテキストでエラー表示 |

## 備考

- 本画面は開発環境でのみ詳細表示される
- 本番環境では `public/500.html` 等の静的ファイルに置き換えられる
- ExceptionWrapperがrescue_templatesマッピングでテンプレートを選択
- ActionableError対応の場合、アクションボタンが表示される
- XHRリクエストの場合はプレーンテキスト形式で返却
- API形式（JSON等）の場合はJSON形式でエラー情報を返却
- コピーボタンで例外情報をクリップボードにコピー可能

---

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

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

### 推奨読解順序

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

例外ラッパーの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | exception_wrapper.rb | `actionpack/lib/action_dispatch/middleware/exception_wrapper.rb` | ExceptionWrapperクラスの構造を理解する |

**読解のコツ**:
- `rescue_responses` (行12-29): 例外クラス名からHTTPステータスへのマッピング
- `rescue_templates` (行31-38): 例外クラス名からテンプレート名へのマッピング
- `source_extracts` (行204-208): スタックトレースからソースコード抽出
- `traces` (行148-179): Application/Framework/Full Traceの生成

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

ミドルウェアの処理フローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | debug_exceptions.rb | `actionpack/lib/action_dispatch/middleware/debug_exceptions.rb` | DebugExceptionsミドルウェアを理解する |

**主要処理フロー**:
1. **30-47行目**: `call` メソッド - 例外をキャッチし、ExceptionWrapperでラップ
2. **58-78行目**: `render_exception` - show_detailed_exceptionsに応じて描画
3. **80-95行目**: `render_for_browser_request` - ブラウザ向けHTML生成
4. **121-135行目**: `create_template` - DebugViewインスタンス生成

#### Step 3: ビューテンプレートを理解する

HTML描画の仕組みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | diagnostics.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/diagnostics.html.erb` | メインテンプレートの構造を理解する |

**主要処理フロー**:
- **1-9行目**: ヘッダー部（例外クラス名、コントローラー#アクション）
- **11-16行目**: メッセージ、サジェスション、アクションボタン
- **15行目**: ソースコード抽出の表示
- **16行目**: スタックトレースの表示
- **18-33行目**: 例外原因チェーンの表示
- **35行目**: リクエスト/レスポンス情報の表示

#### Step 4: パーシャルテンプレートを理解する

各パーツの描画を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | _source.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_source.html.erb` | ソースコード表示パーシャル |
| 4-2 | _trace.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_trace.html.erb` | スタックトレース表示パーシャル |
| 4-3 | _request_and_response.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_request_and_response.html.erb` | リクエスト/レスポンス情報パーシャル |

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

```
リクエスト処理中に例外発生
    │
    └─ DebugExceptions#call
           │
           ├─ @app.call(env) で例外がraiseされる
           │
           ├─ rescue Exception => exception
           │      │
           │      └─ ExceptionWrapper.new(backtrace_cleaner, exception)
           │             │
           │             ├─ rescue_template 決定
           │             ├─ source_extracts 生成
           │             └─ traces 生成
           │
           └─ render_exception(request, exception, wrapper)
                  │
                  ├─ show_detailed_exceptions? チェック
                  │
                  └─ render_for_browser_request
                         │
                         ├─ create_template(request, wrapper)
                         │      │
                         │      └─ DebugView インスタンス生成
                         │
                         └─ template.render(template: "rescues/diagnostics")
                                │
                                ├─ _copy_button.html.erb
                                ├─ _message_and_suggestions.html.erb
                                ├─ _actions.html.erb
                                ├─ _source.html.erb
                                ├─ _trace.html.erb
                                └─ _request_and_response.html.erb
```

### データフロー図

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

例外発生 ──▶ DebugExceptions ミドルウェア
                    │
                    └─ ExceptionWrapper
                           │
                           ├─ exception.backtrace_locations
                           │       │
                           │       └─ 各フレームからソース抽出
                           │
                           ├─ exception.message
                           │
                           ├─ exception.cause （原因チェーン）
                           │
                           └─ corrections （修正候補）
                                                              ↓
                                                    HTML エラーページ
                                                    (diagnostics.html.erb)
                                                         +
                                                    各種パーシャル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| debug_exceptions.rb | `actionpack/lib/action_dispatch/middleware/debug_exceptions.rb` | ミドルウェア | 例外キャッチと描画制御 |
| exception_wrapper.rb | `actionpack/lib/action_dispatch/middleware/exception_wrapper.rb` | ソース | 例外情報のラッピング |
| diagnostics.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/diagnostics.html.erb` | テンプレート | メイン診断テンプレート |
| _source.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_source.html.erb` | パーシャル | ソースコード表示 |
| _trace.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_trace.html.erb` | パーシャル | スタックトレース表示 |
| _message_and_suggestions.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_message_and_suggestions.html.erb` | パーシャル | メッセージと修正候補 |
| _actions.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_actions.html.erb` | パーシャル | ActionableErrorのアクション |
| _request_and_response.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_request_and_response.html.erb` | パーシャル | リクエスト/レスポンス情報 |
| _copy_button.html.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/_copy_button.html.erb` | パーシャル | クリップボードコピーボタン |
| layout.erb | `actionpack/lib/action_dispatch/middleware/templates/rescues/layout.erb` | レイアウト | エラー画面共通レイアウト |
