# 画面設計書 41-トレースコンポーネント

## 概要

本ドキュメントは、Laravelフレームワークの例外レンダラーにおけるトレースコンポーネント（trace.blade.php）の画面設計書である。例外発生時にスタックトレース全体を表示し、アプリケーションコードとベンダーコードを視覚的に区別して表示するBladeコンポーネントについて定義する。

### 本画面の処理概要

**業務上の目的・背景**：開発時に例外が発生した際、エラーの原因を特定するためにはスタックトレースの解析が不可欠である。このコンポーネントは、例外の呼び出し履歴（スタックトレース）を開発者が効率的に把握できるよう、アプリケーションコードとベンダーコードを分離して表示する。これにより、開発者は自身のアプリケーションコードに起因するエラーを素早く特定でき、デバッグ作業の効率化に貢献する。特に大規模なフレームワークやライブラリを使用している場合、ベンダーフレームは折りたたまれて表示されるため、視認性が向上する。

**画面へのアクセス方法**：開発環境（APP_DEBUG=true）においてアプリケーションで例外が発生した際、例外表示画面（show.blade.php）から自動的にこのコンポーネントが読み込まれて表示される。直接URLでアクセスするものではなく、例外発生時に自動的にレンダリングされる。

**主要な操作・処理内容**：
1. 例外オブジェクトからフレームグループを取得し、ベンダー/非ベンダーで分類
2. 非ベンダーフレーム（アプリケーションコード）は個別のフレームコンポーネントとして展開表示
3. ベンダーフレームは折りたたみ可能なグループとして表示
4. 各フレームは展開/折りたたみが可能で、ソースコードの確認ができる

**画面遷移**：例外表示画面（show.blade.php）の一部として表示される。個々のフレームを展開すると、frame-code コンポーネントによりソースコードが表示される。

**権限による表示制御**：APP_DEBUG が true の場合のみ表示される。本番環境では例外詳細画面自体が表示されないため、このコンポーネントも表示されない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | ビューファクトリ | 主機能 | スタックトレース情報の描画処理 |

## 画面種別

詳細 / コンポーネント

## URL/ルーティング

直接のURLはなし（例外発生時に自動的にレンダリングされるコンポーネント）

## 入出力項目

| 項目名 | 属性名 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| exception | $exception | Exception | 必須 | 例外情報を保持するExceptionラッパーオブジェクト |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| セクションタイトル | "Exception trace" の固定文字列 | テキスト（h3要素） |
| アラートアイコン | トレースセクションを示すアイコン | SVGアイコン |
| フレーム一覧 | スタックトレースの各フレーム | リスト形式 |
| ベンダーフレームグループ | ベンダーディレクトリのフレームをまとめた折りたたみグループ | 折りたたみパネル |

## イベント仕様

### 1-フレーム展開/折りたたみ

非ベンダーフレームをクリックすると、Alpine.jsのx-dataで管理された`expanded`状態が切り替わり、対応するソースコードが表示/非表示となる。

### 2-ベンダーフレームグループ展開

ベンダーフレームグループのヘッダーをクリックすると、グループ内の全フレームが展開表示される。

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

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

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

本コンポーネントは表示専用であり、データベースへの更新処理は行わない。

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 見出し | Exception trace | 常時表示 |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| フレームデータが存在しない | 空のフレーム一覧が表示される |
| ソースファイルが読み取り不可 | 該当フレームのコードスニペットが表示されない |

## 備考

- Alpine.jsを使用したインタラクティブなUI
- ダークモード対応のスタイリング
- Tailwind CSSによるレスポンシブデザイン
- 主要な非ベンダーフレームは自動的に展開状態で表示される

---

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

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

### 推奨読解順序

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

まず、スタックトレースのデータ構造とフレームオブジェクトの構成を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Frame.php | `src/Illuminate/Foundation/Exceptions/Renderer/Frame.php` | フレームの構造、isFromVendor()メソッド、snippet()メソッドの実装を理解 |
| 1-2 | Exception.php | `src/Illuminate/Foundation/Exceptions/Renderer/Exception.php` | frames()とframeGroups()メソッドによるフレームのグループ化ロジックを理解 |

**読解のコツ**: Frameクラスはスタックトレースの1行（1フレーム）を表現し、ファイルパス、行番号、クラス名、メソッド名などの情報を保持する。ExceptionクラスのframeGroups()メソッドがベンダー/非ベンダーでフレームを分類する。

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

トレースコンポーネントが呼び出される流れを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | show.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/show.blade.php` | 15行目でtraceコンポーネントが呼び出されている |
| 2-2 | trace.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/trace.blade.php` | @propsでexceptionを受け取り、frameGroups()でループ処理 |

**主要処理フロー**:
1. **1行目**: @props(['exception'])で例外オブジェクトを受け取る
2. **12行目**: $exception->frameGroups()でベンダー/非ベンダーで分類されたフレームグループを取得
3. **13-19行目**: 各グループについて、ベンダーフレームならvendor-framesコンポーネント、それ以外ならframeコンポーネントを使用

#### Step 3: 子コンポーネントを理解する

トレースコンポーネントから呼び出される各子コンポーネントの役割を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | frame.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/frame.blade.php` | 個別フレームの表示、展開/折りたたみの実装 |
| 3-2 | vendor-frames.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/vendor-frames.blade.php` | ベンダーフレームのグループ表示、折りたたみの実装 |
| 3-3 | vendor-frame.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/vendor-frame.blade.php` | 個別のベンダーフレームの簡易表示 |

**主要処理フロー**:
- **frame.blade.php 5行目**: `expanded: {{ $frame->isMain() ? 'true' : 'false' }}`でメインフレーム（最初の非ベンダーフレーム）を自動展開
- **vendor-frames.blade.php 21行目**: フレーム数をカウントして「X vendor frames」と表示

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

```
show.blade.php
    │
    └─ trace.blade.php
           │
           ├─ vendor-frames.blade.php (ベンダーフレームグループ)
           │      └─ vendor-frame.blade.php (個別ベンダーフレーム)
           │             └─ formatted-source.blade.php
           │             └─ file-with-line.blade.php
           │
           └─ frame.blade.php (アプリケーションフレーム)
                  └─ formatted-source.blade.php
                  └─ file-with-line.blade.php
                  └─ frame-code.blade.php
```

### データフロー図

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

Exception                 Exception::frameGroups()       フレームグループ配列
(例外オブジェクト)    ───▶ (ベンダー/非ベンダー分類)  ───▶ [{is_vendor, frames}]
                                   │
                                   ▼
                          trace.blade.php             ───▶ HTML出力
                          (フレーム一覧描画)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| trace.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/trace.blade.php` | テンプレート | トレースセクションのメインコンポーネント |
| frame.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/frame.blade.php` | テンプレート | 個別フレームの表示コンポーネント |
| vendor-frames.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/vendor-frames.blade.php` | テンプレート | ベンダーフレームグループの表示 |
| vendor-frame.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/vendor-frame.blade.php` | テンプレート | 個別ベンダーフレームの簡易表示 |
| Frame.php | `src/Illuminate/Foundation/Exceptions/Renderer/Frame.php` | ソース | フレームデータのラッパークラス |
| Exception.php | `src/Illuminate/Foundation/Exceptions/Renderer/Exception.php` | ソース | 例外データのラッパー、フレームグループ化ロジック |
| alert.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/alert.blade.php` | テンプレート | アラートアイコンSVG |
