# 画面設計書 3-ルーティング一覧画面

## 概要

本ドキュメントは、Ruby on Rails フレームワークにおけるルーティング一覧画面の画面設計を定義するものである。

### 本画面の処理概要

本画面は、Railsアプリケーションに定義されたすべてのルーティング情報を一覧表示する開発者向けデバッグ画面である。各ルートのHTTPメソッド（Verb）、URLパターン、コントローラー#アクション、ルート名（Prefix）を視覚的に確認できるHTMLテーブルを提供する。

**業務上の目的・背景**：開発者がアプリケーションのルーティング構成を俯瞰的に把握するために使用される。新規ルート追加後の確認、既存ルートの調査、ルーティングエラー発生時のデバッグ、APIエンドポイントの一覧確認などに活用される。`rails routes` コマンドのGUI版として機能し、ブラウザ上でインタラクティブにルーティング情報を確認できる。

**画面へのアクセス方法**：開発環境において、ブラウザで `/rails/info/routes` にアクセスする。また、`/rails/info` にアクセスすると本画面にリダイレクトされる。ローカルリクエストのみ許可されている。

**主要な操作・処理内容**：
1. RoutesInspectorを使用してアプリケーションのルーティング情報を収集
2. HtmlTableFormatterを使用してHTMLテーブル形式で描画
3. ルートの優先順位（上から下の順でマッチング）を視覚的に表示
4. マウントされたエンジンのルートも含めて表示
5. JSON形式でのルート検索API（クエリパラメータ対応）

**画面遷移**：
- 遷移元：Railsウェルカム画面、アプリケーションプロパティ画面
- 遷移先：特になし（表示専用画面）

**権限による表示制御**：`before_action :require_local!` によりローカルリクエストのみ許可される。リモートからのアクセスは403 Forbiddenとなる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | Journey | 主機能 | ルーティングエンジンによるルート情報の解析・抽出 |
| 8 | Action Dispatch | 主機能 | RoutesInspectorによるルーティング一覧の生成 |
| 2 | Railties | 補助機能 | InfoControllerによるルート情報の表示制御 |
| 5 | Action View | 補助機能 | HtmlTableFormatterによるルート情報のテーブル描画 |

## 画面種別

一覧画面（ルーティング情報一覧）

## URL/ルーティング

| HTTP メソッド | URL パターン | コントローラー#アクション | 備考 |
|--------------|--------------|--------------------------|------|
| GET | /rails/info | rails/info#index | routesにリダイレクト |
| GET | /rails/info/routes | rails/info#routes | HTML形式 |
| GET | /rails/info/routes.json | rails/info#routes | JSON形式（検索API） |

## 入出力項目

### 入力項目（JSON API用）

| 項目名 | パラメータ名 | データ型 | 必須 | 説明 |
|--------|-------------|----------|------|------|
| 検索クエリ | query | String | No | ルートパス、名前、コントローラー#アクションで検索 |

### 出力項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ルートテーブル | HTMLテーブル | Prefix、Verb、URI Pattern、Controller#Actionで構成 |

## 表示項目

| No | 項目ID | 項目名 | データ型 | 取得元 | 備考 |
|----|--------|--------|----------|--------|------|
| 1 | prefix | Prefix | String | RouteWrapper.name | ルート名（_pathや_urlヘルパーの接頭辞） |
| 2 | verb | Verb | String | RouteWrapper.verb | HTTPメソッド（GET/POST/PUT/PATCH/DELETE） |
| 3 | path | URI Pattern | String | RouteWrapper.path | URLパターン（:idなどの動的セグメント含む） |
| 4 | reqs | Controller#Action | String | RouteWrapper.reqs | コントローラー名#アクション名、制約条件 |

## イベント仕様

本画面は主に表示専用であるが、JSON APIでのルート検索機能を提供する。

### 1-ルート検索（JSON API）

**トリガー**: GET /rails/info/routes.json?query=検索語

**処理内容**:
1. queryパラメータを取得し、URIエンコードを適用
2. 完全一致ルート（exact）と部分一致ルート（fuzzy）を検索
3. JSON形式で結果を返却

**レスポンス形式**:
```json
{
  "exact": ["/users/:id"],
  "fuzzy": ["/users", "/users/new"]
}
```

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

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

本画面はデータベースアクセスを行わない。メモリ上のルーティング定義を読み取るのみ。

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

## メッセージ仕様

| メッセージID | メッセージ種別 | 表示条件 | メッセージ内容 |
|-------------|---------------|---------|--------------|
| MSG-001 | 情報 | ルートが定義されていない場合 | "You don't have any routes defined!" |
| MSG-002 | 説明 | 常時表示 | "Routes match in priority from top to bottom" |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| リモートからのアクセス | 403 Forbiddenエラーを返却 |
| ルートが未定義 | 空のテーブルとガイダンスメッセージを表示 |

## 備考

- 本画面は開発環境でのみ使用される
- internalフラグが立っているルート（フレームワーク内部ルート）は表示されない
- マウントされたエンジンのルートは、エンジン名をセクションタイトルとして表示される
- ルートの優先順位は定義順（config/routes.rbの記述順）に対応する
- source_location情報が利用可能な場合、ルート定義のファイル位置も取得可能

---

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

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

### 推奨読解順序

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

ルーティング情報の構造とラッパークラスを理解する。

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

**読解のコツ**:
- `RouteWrapper` (行10-103): 各ルートの情報をラップし、表示用メソッドを提供
- `RoutesInspector` (行109-184): ルート一覧の収集とフォーマット処理
- `HtmlTableFormatter` (行333-372): HTMLテーブル形式での描画

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

コントローラーアクションの処理フローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | info_controller.rb | `railties/lib/rails/info_controller.rb` | routesアクションの実装を理解する |

**主要処理フロー**:
1. **21-37行目**: `routes` アクションの定義
2. **22-26行目**: HTML形式の処理 - RoutesInspectorを生成
3. **28-35行目**: JSON形式の処理 - クエリ検索を実行
4. **47-73行目**: `matching_routes` プライベートメソッドでルート検索ロジック

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | routes.html.erb | `railties/lib/rails/templates/rails/info/routes.html.erb` | テンプレートの構造を理解する |

**主要処理フロー**:
- **1-3行目**: 見出し「Routes」の表示
- **5-7行目**: 優先順位の説明テキスト
- **9行目**: HtmlTableFormatterを使用してルートテーブルを描画

#### Step 4: テーブルフォーマッターを理解する

HTMLテーブル生成の詳細を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | inspector.rb | `actionpack/lib/action_dispatch/routing/inspector.rb` | HtmlTableFormatterクラスの実装を理解する |

**主要処理フロー**:
- **334-337行目**: コンストラクタでビューインスタンスを保持
- **343-345行目**: `section` メソッドでルートパーシャルをレンダリング
- **367-371行目**: `result` メソッドでテーブルレイアウトを適用

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

```
ブラウザリクエスト (GET /rails/info/routes)
    │
    ├─ before_action :require_local!
    │      └─ ローカルIPアドレスチェック
    │
    └─ Rails::InfoController#routes
           │
           ├─ [HTML形式]
           │      │
           │      ├─ RoutesInspector.new(routes) 生成
           │      │      └─ RouteWrapper でラップ
           │      │
           │      └─ routes.html.erb テンプレート描画
           │             │
           │             └─ HtmlTableFormatter.format()
           │                    │
           │                    ├─ _route パーシャル
           │                    └─ _table レイアウト
           │
           └─ [JSON形式]
                  │
                  └─ matching_routes(query:, exact_match:)
                         │
                         ├─ 完全一致検索
                         └─ 部分一致検索
```

### データフロー図

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

HTTPリクエスト ──▶ InfoController#routes
(GET /rails/info/routes)
        │
        │ respond_to によるフォーマット分岐
        │
        ├─[HTML] RoutesInspector
        │            │
        │            ├─ Rails.application.routes.routes 取得
        │            │
        │            └─ HtmlTableFormatter でフォーマット
        │                                                      ↓
        │                                              HTML テーブル
        │
        └─[JSON] matching_routes
                     │
                     ├─ パス完全一致検索
                     ├─ 名前完全一致検索
                     ├─ パス部分一致検索
                     └─ 名前部分一致検索
                                                              ↓
                                                    JSON レスポンス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| info_controller.rb | `railties/lib/rails/info_controller.rb` | コントローラー | ルート一覧画面のアクション定義 |
| routes.html.erb | `railties/lib/rails/templates/rails/info/routes.html.erb` | テンプレート | メインテンプレート |
| inspector.rb | `actionpack/lib/action_dispatch/routing/inspector.rb` | ソース | RoutesInspector、HtmlTableFormatter定義 |
| _route.html.erb | `actionpack/lib/action_dispatch/middleware/templates/routes/_route.html.erb` | パーシャル | 各ルート行の描画 |
| _table.html.erb | `actionpack/lib/action_dispatch/middleware/templates/routes/_table.html.erb` | レイアウト | テーブル全体のレイアウト |
