# 画面設計書 4-ソースコードノート一覧画面

## 概要

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

### 本画面の処理概要

本画面は、Railsアプリケーションのソースコード内に記述された注釈（TODO、FIXME、OPTIMIZEなど）を一覧表示する開発者向けデバッグ画面である。SourceAnnotationExtractorを使用してソースファイルを走査し、特定のタグを持つコメントを抽出してテーブル形式で表示する。

**業務上の目的・背景**：開発者がソースコード内の課題や改善点を一元的に把握するために使用される。TODOコメント（未実装機能のメモ）、FIXMEコメント（修正が必要な箇所）、OPTIMIZEコメント（最適化が必要な箇所）などを開発チーム内で共有し、技術的負債の可視化やタスク管理に活用できる。`rails notes` コマンドのGUI版として機能する。

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

**主要な操作・処理内容**：
1. SourceAnnotationExtractorを使用して指定ディレクトリ（app, config, db, lib, test）を走査
2. 登録されたタグ（TODO, FIXME, OPTIMIZE等）に一致するコメントを抽出
3. ファイル名、行番号、タグ、説明文をテーブル形式で表示
4. タグによるフィルタリング機能を提供

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Railties | 主機能 | SourceAnnotationExtractorによるTODO・FIXME・OPTIMIZE等の注釈抽出 |
| 5 | Action View | 補助機能 | 注釈一覧のHTML描画処理 |

## 画面種別

一覧画面（ソースコードノート一覧）

## URL/ルーティング

| HTTP メソッド | URL パターン | コントローラー#アクション | 備考 |
|--------------|--------------|--------------------------|------|
| GET | /rails/info/notes | rails/info#notes | HTML形式 |
| GET | /rails/info/notes?tag=TODO | rails/info#notes | タグフィルタリング |

## 入出力項目

### 入力項目

| 項目名 | パラメータ名 | データ型 | 必須 | 説明 |
|--------|-------------|----------|------|------|
| タグフィルター | tag | String | No | 表示するタグを指定（TODO/FIXME/OPTIMIZE等） |

### 出力項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ノートテーブル | HTMLテーブル | File Name、Line No.、Tag、Descriptionで構成 |
| フィルタードロップダウン | select要素 | タグによるフィルタリング用UI |

## 表示項目

| No | 項目ID | 項目名 | データ型 | 取得元 | 備考 |
|----|--------|--------|----------|--------|------|
| 1 | file_name | File Name | String | annotations.keys | ファイルパス（アプリルートからの相対パス） |
| 2 | line_no | Line No. | Integer | Annotation.line | 注釈が記述されている行番号 |
| 3 | tag | Tag | String | Annotation.tag | 注釈のタグ（TODO/FIXME/OPTIMIZE等） |
| 4 | description | Description | String | Annotation.text | 注釈の説明テキスト |

## イベント仕様

### 1-タグフィルター変更

**トリガー**: フィルタードロップダウンで値を変更

**処理内容**:
1. 選択されたタグ値でフォームを自動サブミット
2. GETリクエストで `/rails/info/notes?tag=選択値` に遷移
3. 指定タグの注釈のみをフィルタリングして表示

**遷移先**: 同一画面（フィルタリング結果で更新）

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

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

本画面はデータベースアクセスを行わない。ファイルシステムからソースコードを読み取るのみ。

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

## メッセージ仕様

本画面ではシステムメッセージの表示は行わない。注釈が見つからない場合は空のテーブルが表示される。

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| リモートからのアクセス | 403 Forbiddenエラーを返却 |
| 注釈が見つからない | 空のテーブルを表示 |
| ファイル読み込みエラー | 該当ファイルをスキップして続行 |

## 備考

- 本画面は開発環境でのみ使用される
- デフォルトで検索されるディレクトリ: app, config, db, lib, test
- デフォルトで検索されるタグ: TODO, FIXME, OPTIMIZE
- カスタムタグは `Rails::SourceAnnotationExtractor::Annotation.register_tags` で追加可能
- カスタムディレクトリは `Rails::SourceAnnotationExtractor::Annotation.register_directories` で追加可能
- 対応ファイル拡張子: .rb, .rake, .ruby, .builder, .yml, .yaml, .js, .css, .erb
- ダークモード対応のCSSスタイルが適用される

---

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

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

### 推奨読解順序

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

注釈情報の構造と抽出ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | source_annotation_extractor.rb | `railties/lib/rails/source_annotation_extractor.rb` | SourceAnnotationExtractorクラスとAnnotation構造体を理解する |

**読解のコツ**:
- `Annotation` (行43-105): line, tag, textの3つの属性を持つ構造体
- `directories` (行44-46): デフォルト検索ディレクトリ（app, config, db, lib, test）
- `tags` (行54-56): デフォルトタグ（OPTIMIZE, FIXME, TODO）
- `extensions` (行64-92): ファイル拡張子ごとの抽出パターン

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

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

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

**主要処理フロー**:
1. **39-44行目**: `notes` アクションの定義
2. **40行目**: タグパラメータの取得（デフォルトは全タグ）
3. **41-43行目**: SourceAnnotationExtractorでの注釈検索実行

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

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

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

**主要処理フロー**:
- **1-52行目**: CSSスタイル定義（テーブル、フィルター、ダークモード対応）
- **54-56行目**: 見出し「Notes」の表示
- **58-63行目**: タグフィルタードロップダウン
- **65-88行目**: 注釈テーブルの描画（ファイル、行番号、タグ、説明）

#### Step 4: 抽出ロジックを理解する

注釈抽出の詳細ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | source_annotation_extractor.rb | `railties/lib/rails/source_annotation_extractor.rb` | find_inメソッドとパターンマッチングを理解する |

**主要処理フロー**:
- **136-138行目**: `find` メソッドでディレクトリを走査
- **144-175行目**: `find_in` メソッドでファイルを再帰的に検索
- **18-27行目**: `ParserExtractor` - Prismパーサーを使用したRubyコメント抽出
- **31-40行目**: `PatternExtractor` - 正規表現による行単位抽出

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

```
ブラウザリクエスト (GET /rails/info/notes)
    │
    ├─ before_action :require_local!
    │      └─ ローカルIPアドレスチェック
    │
    └─ Rails::InfoController#notes
           │
           ├─ params[:tag] 取得
           │      └─ 未指定時は全タグ（OPTIMIZE|FIXME|TODO）
           │
           └─ SourceAnnotationExtractor.new(tags).find(directories)
                  │
                  ├─ find_in("app")
                  ├─ find_in("config")
                  ├─ find_in("db")
                  ├─ find_in("lib")
                  └─ find_in("test")
                         │
                         ├─ ファイル拡張子をチェック
                         ├─ 対応する Extractor を取得
                         │      ├─ ParserExtractor (.rb, .rake, .ruby, .builder)
                         │      └─ PatternExtractor (.yml, .yaml, .js, .css, .erb)
                         │
                         └─ annotations を抽出
                                │
                                └─ Annotation(line, tag, text) を生成
```

### データフロー図

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

HTTPリクエスト ──▶ InfoController#notes
(GET /rails/info/notes)
        │
        │ params[:tag] による
        │ フィルター条件取得
        │
        └──▶ SourceAnnotationExtractor
                    │
                    ├─ 指定ディレクトリを再帰走査
                    │
                    ├─ 各ファイルをパターンマッチング
                    │      │
                    │      ├─ Rubyファイル: Prismパーサー使用
                    │      └─ その他: 正規表現パターン
                    │
                    └─ @annotations ハッシュに格納
                           キー: ファイルパス
                           値: Annotation配列
                                                              ↓
                                                    HTML テーブル
                                                    (notes.html.erb)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| info_controller.rb | `railties/lib/rails/info_controller.rb` | コントローラー | ノート一覧画面のアクション定義 |
| notes.html.erb | `railties/lib/rails/templates/rails/info/notes.html.erb` | テンプレート | HTML描画テンプレート |
| source_annotation_extractor.rb | `railties/lib/rails/source_annotation_extractor.rb` | ソース | 注釈抽出ロジック |
