# 画面設計書 48-クエリコンポーネント

## 概要

本ドキュメントは、Laravelフレームワークの例外レンダラーにおけるクエリコンポーネント（query.blade.php）の画面設計書である。例外発生時に実行されたデータベースクエリの一覧をページネーション付きで表示し、各クエリのSQL文、接続名、実行時間を確認できるBladeコンポーネントについて定義する。

### 本画面の処理概要

**業務上の目的・背景**：アプリケーションのデバッグにおいて、どのようなデータベースクエリが実行されたかを把握することは重要である。N+1問題の検出、遅いクエリの特定、意図しないクエリの発見など、データベースに関連する問題の特定に役立つ。このコンポーネントは、例外発生までに実行されたすべてのクエリ（最大100件）を表示し、ページネーションで効率的に確認できる。

**画面へのアクセス方法**：例外表示画面（show.blade.php）から直接呼び出される。例外発生時に自動的にレンダリングされ、クエリ情報がある場合は一覧として表示される。

**主要な操作・処理内容**：
1. クエリ配列を受け取り、最大100件まで表示
2. 10件ずつページネーション表示
3. 各クエリの接続名、SQL文（シンタックスハイライト付き）、実行時間を表示
4. 100件を超える場合はツールチップで通知
5. クエリがない場合は空状態コンポーネントを表示

**画面遷移**：例外表示画面（show.blade.php）の一部として表示。ページネーション操作で表示ページが切り替わる。

**権限による表示制御**：APP_DEBUGがtrueの場合のみ表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | ビューファクトリ | 主機能 | DBクエリ情報の描画処理 |
| 5 | クエリビルダ | 補助機能 | 実行されたSQLクエリの表示連携 |

## 画面種別

一覧 / コンポーネント

## URL/ルーティング

直接のURLはなし（例外表示画面から呼び出されるコンポーネント）

## 入出力項目

| 項目名 | 属性名 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| queries | $queries | array | 必須 | クエリ情報の配列（connectionName, sql, time） |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| セクションタイトル | "Queries" の固定文字列 | テキスト（h3要素） |
| データベースアイコン | クエリセクションを示すアイコン | SVGアイコン |
| 表示件数表示 | "X-Y of Z" 形式の件数表示 | テキスト |
| 接続名 | データベース接続名 | モノスペーステキスト |
| SQL文 | 実行されたSQL（シンタックスハイライト付き） | コード形式 |
| 実行時間 | クエリの実行時間 | "Xms" 形式 |
| ページネーション | ページ切り替えボタン | ボタン群 |

## イベント仕様

### 1-ページネーション操作

Alpine.jsで実装されたページネーション機能。以下のボタンが利用可能:

- **最初へ（first）**: 1ページ目に移動
- **前へ（previous）**: 前のページに移動
- **ページ番号クリック（goToPage）**: 指定ページに移動
- **次へ（next）**: 次のページに移動
- **最後へ（last）**: 最終ページに移動

### 2-ツールチップ表示

SQL文にホバーすると、全文がツールチップで表示される。

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

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

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

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

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 見出し | Queries | 常時表示 |
| 空状態 | No queries executed | クエリがない場合 |
| ツールチップ | Only the first 100 queries are shown | 100件を超える場合 |

## 例外処理

| 例外状況 | 処理内容 |
|----------|----------|
| クエリがない | empty-stateコンポーネントで「No queries executed」を表示 |
| 100件を超えるクエリ | 最初の100件のみ表示、infoアイコンでツールチップ通知 |

## 備考

- Listenerクラスでクエリを収集（最大101件まで、表示は100件）
- Alpine.jsで完全にクライアントサイドのページネーションを実装
- 10件/ページで表示
- 省略記号（...）を含む賢いページ番号表示
- ダークモード対応のスタイリング

---

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

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

### 推奨読解順序

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

クエリデータの収集と構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Listener.php | `src/Illuminate/Foundation/Exceptions/Renderer/Listener.php` | クエリ収集ロジック、onQueryExecuted()メソッド |
| 1-2 | Exception.php | `src/Illuminate/Foundation/Exceptions/Renderer/Exception.php` | applicationQueries()メソッド（258-281行目） |

**読解のコツ**:
- Listenerクラスはクエリイベントをリッスンし、最大101件まで保存
- ExceptionクラスのapplicationQueries()がバインディングをSQLに埋め込む

#### Step 2: テンプレートを理解する

クエリコンポーネントのテンプレート構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | query.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/query.blade.php` | x-dataのページネーション状態、visiblePagesの計算ロジック |

**主要処理フロー**:
1. **1行目**: @props(['queries'])でクエリ配列を受け取る
2. **5-77行目**: Alpine.jsのx-dataでページネーション状態を定義
3. **6行目**: `totalQueries: min(count($queries), 100)` で最大100件に制限
4. **7-8行目**: currentPage, perPage(10)の初期化
5. **39-76行目**: visiblePages計算（省略記号を含む賢い表示）
6. **98-120行目**: クエリ一覧のループ表示
7. **101行目**: x-showでページネーションに応じて表示制御

#### Step 3: ページネーションUIを理解する

ページネーションコントロールの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | query.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/query.blade.php` | 124-181行目のページネーションUI |

**主要処理フロー**:
- **126-133行目**: 最初へボタン（chevrons-left）
- **135-143行目**: 前へボタン（chevron-left）
- **145-160行目**: ページ番号表示（省略記号含む）
- **162-170行目**: 次へボタン（chevron-right）
- **172-180行目**: 最後へボタン（chevrons-right）

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

```
show.blade.php
    │
    └─ query.blade.php
           │
           ├─ icons/database.blade.php
           ├─ icons/info.blade.php
           │
           ├─ syntax-highlight.blade.php (各クエリのSQL表示)
           │
           ├─ empty-state.blade.php (クエリがない場合)
           │
           └─ icons/chevron-*.blade.php (ページネーション)
```

### データフロー図

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

Listener                        Exception::applicationQueries()
    │                                  │
    └─ queries[] ──────────▶   バインディング埋め込み   ───▶   queries[]
                                       │
                                       ▼
                               query.blade.php
                               (ページネーション付き一覧表示)
                                       │
                                       ├─ 接続名表示
                                       ├─ SQL表示（syntax-highlight）
                                       └─ 実行時間表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| query.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/query.blade.php` | テンプレート | クエリ一覧の表示 |
| Listener.php | `src/Illuminate/Foundation/Exceptions/Renderer/Listener.php` | ソース | クエリイベントのリスナー |
| Exception.php | `src/Illuminate/Foundation/Exceptions/Renderer/Exception.php` | ソース | クエリデータの整形 |
| show.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/show.blade.php` | テンプレート | 親コンポーネント |
| syntax-highlight.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/syntax-highlight.blade.php` | テンプレート | SQLのシンタックスハイライト |
| empty-state.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/empty-state.blade.php` | テンプレート | 空状態の表示 |
| database.blade.php | `src/Illuminate/Foundation/resources/exceptions/renderer/components/icons/database.blade.php` | テンプレート | データベースアイコン |
