# 画面設計書 76-ヘルスチェック画面

## 概要

本ドキュメントは、Laravel フレームワークの「ヘルスチェック画面」の設計書である。この画面は、アプリケーションの稼働状況を確認するためのエンドポイントに対応するビューであり、HTTPリクエストに対する応答性とアプリケーションの健全性を視覚的に表示する。

### 本画面の処理概要

ヘルスチェック画面は、アプリケーションの稼働状態をリアルタイムで表示するシンプルなステータス画面である。

**業務上の目的・背景**：マイクロサービスアーキテクチャやコンテナ化された環境において、アプリケーションのヘルスチェック（死活監視）は重要な運用要件である。この画面は、ロードバランサー、Kubernetes、Docker Compose、AWS ELB などの外部監視システムがアプリケーションの状態を確認するためのエンドポイントとして機能する。正常時はHTTP 200を、異常時はHTTP 500を返却し、視覚的なステータス表示も提供する。

**画面へのアクセス方法**：`bootstrap/app.php`にて`withRouting`メソッドの`health`パラメータで指定されたURL（デフォルトは`/up`）にHTTPリクエストを送信することでアクセスする。例：`GET /up`

**主要な操作・処理内容**：
1. HTTPリクエストを受け付ける
2. `DiagnosingHealth`イベントを発火し、カスタムヘルスチェック処理を実行可能にする
3. 例外が発生しなければ正常（緑色インジケータ、HTTP 200）を表示
4. 例外が発生した場合は異常（赤色インジケータ、HTTP 500）を表示
5. レスポンス時間を計測して表示（LARAVEL_STARTが定義されている場合）

**画面遷移**：この画面からの画面遷移は存在しない。単独のステータス表示画面として機能する。外部システム（監視ツール等）からのHTTPリクエストに応答することが主目的である。

**権限による表示制御**：特に権限による表示制御は行われない。ヘルスチェックエンドポイントは通常、認証なしでアクセス可能である（ミドルウェアによる保護がない場合）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | ルーター | 補助機能 | ヘルスチェックエンドポイントへのルーティング |
| 36 | ビューファクトリ | 主機能 | ヘルスチェック結果の描画処理 |

## 画面種別

ステータス表示画面

## URL/ルーティング

| メソッド | URL | 説明 |
|---------|-----|------|
| GET | /up（設定可能） | ヘルスチェックエンドポイント |

ルーティングは`ApplicationBuilder::withRouting()`メソッドの`health`パラメータで設定される。

```php
// bootstrap/app.php
return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        health: '/up', // ヘルスチェックURL
    )
```

## 入出力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| $exception | string\|null | 任意 | 例外発生時のエラーメッセージ（正常時はnull） |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| アプリケーション名 | config('app.name')の値（デフォルト: Laravel） |
| ステータスインジケータ | アニメーション付きの円形インジケータ（緑: 正常、赤: 異常） |
| ステータスメッセージ | "Application up"（正常時）または"Application experiencing problems"（異常時） |
| レスポンス情報 | "HTTP request received." + レスポンス時間（ms） |

## イベント仕様

### 1-DiagnosingHealthイベント発火

ヘルスチェック処理の一環として`DiagnosingHealth`イベントが発火される。

**処理フロー**:
1. HTTPリクエスト受信
2. `Event::dispatch(new DiagnosingHealth)`でイベント発火
3. リスナーで例外が発生した場合、`$exception`にメッセージがセットされる
4. 例外発生時はデバッグモードなら例外を再スローし、そうでなければログに記録
5. ビューをレンダリングしてHTTPレスポンスを返却

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

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

このコンポーネントは直接データベース操作を行わない。ただし、`DiagnosingHealth`イベントのリスナーでデータベース接続確認等を実装することは可能。

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG-001 | 正常 | Application up |
| MSG-002 | 異常 | Application experiencing problems |
| MSG-003 | 情報 | HTTP request received. Response rendered in {time}ms. |

## 例外処理

| 例外タイプ | 発生条件 | 対応処理 |
|-----------|---------|---------|
| \Throwable | DiagnosingHealthイベントリスナーで例外発生 | デバッグモード時は再スロー、そうでなければログ記録してエラー表示 |

## 備考

- Tailwind CSSを使用したレスポンシブデザイン
- ステータスインジケータにはCSSアニメーション（ping）を使用
- フォントはFigtree（Google Fonts/Bunny Fonts経由）を使用
- LARAVEL_START定数が定義されている場合、レスポンス時間をミリ秒単位で計算・表示
- 外部CDN（cdn.jsdelivr.net）からTailwind CSSブラウザビルドを読み込み
- ダークモード対応のスタイリング

---

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

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

### 推奨読解順序

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

ヘルスチェック画面に渡されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DiagnosingHealth.php | `src/Illuminate/Foundation/Events/DiagnosingHealth.php` | ヘルスチェック時に発火されるイベントクラス |

**読解のコツ**: `DiagnosingHealth`イベントは空のイベントクラスで、リスナー内でカスタムヘルスチェック処理を実装する際のフックポイントとして機能する。

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

ルーティング定義とコントローラ処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ApplicationBuilder.php | `src/Illuminate/Foundation/Configuration/ApplicationBuilder.php` | ヘルスチェックルートの定義箇所（218-237行目） |

**主要処理フロー**:
1. **218行目**: `if (is_string($health))` でヘルスチェックURLが設定されているか確認
2. **219行目**: `Route::get($health, function () {...})` でルートを登録
3. **223行目**: `Event::dispatch(new DiagnosingHealth)` でイベント発火
4. **224-231行目**: 例外ハンドリング（デバッグモード判定、ログ記録）
5. **234-236行目**: ビューファイルをレンダリングしてレスポンス返却

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

HTMLテンプレートの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | health-up.blade.php | `src/Illuminate/Foundation/resources/health-up.blade.php` | ヘルスチェック画面のHTMLテンプレート |

**主要処理フロー**:
- **7行目**: `{{ config('app.name', 'Laravel') }}` でアプリケーション名を取得
- **26行目**: `{{ $exception ? 'status-down' : null }}` で状態に応じたクラス追加
- **27-28行目**: アニメーション付きステータスインジケータ（緑/赤）
- **32行目**: `{{ $exception ? 'experiencing problems' : 'up' }}` でステータスメッセージ切替
- **37-39行目**: `LARAVEL_START`が定義されていればレスポンス時間を計算・表示

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

```
HTTPリクエスト（GET /up）
    │
    └─ ApplicationBuilder::buildRoutingCallback()（ルーティング定義）
           │
           ├─ Event::dispatch(new DiagnosingHealth)
           │      └─ [カスタムリスナー]（オプション）
           │
           └─ View::file('health-up.blade.php', ['exception' => ...])
                  │
                  └─ health-up.blade.php（HTMLレンダリング）
                         │
                         └─ HTTPレスポンス（200 or 500）
```

### データフロー図

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

HTTPリクエスト ───▶ ApplicationBuilder ───▶ health-up.blade.php ───▶ HTTPレスポンス
(GET /up)           (イベント発火・例外捕捉)    (HTMLレンダリング)       (200/500)
                           │
                           ▼
                    DiagnosingHealth
                    イベントリスナー
                    （カスタム処理）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| health-up.blade.php | `src/Illuminate/Foundation/resources/health-up.blade.php` | テンプレート | ヘルスチェック画面のHTMLテンプレート |
| ApplicationBuilder.php | `src/Illuminate/Foundation/Configuration/ApplicationBuilder.php` | ソース | ルーティング定義とヘルスチェック処理 |
| DiagnosingHealth.php | `src/Illuminate/Foundation/Events/DiagnosingHealth.php` | ソース | ヘルスチェックイベントクラス |
