# 画面設計書 8-503 Service Unavailable

## 概要

本ドキュメントは、Laravel フレームワークにおける HTTP 503 Service Unavailable 画面の設計書です。アプリケーションがメンテナンスモード中の場合や、サービスが一時的に利用できない場合に表示されるエラー画面について記載しています。

### 本画面の処理概要

HTTP 503 Service Unavailable 画面は、アプリケーションが一時的にリクエストを処理できない状態にあることをユーザーに通知する画面です。主にメンテナンスモード時に表示され、計画的なダウンタイムや緊急メンテナンス中であることをユーザーに伝える役割を果たします。

**業務上の目的・背景**：Web アプリケーションの運用において、データベースマイグレーション、サーバーアップデート、依存関係の更新などの作業中にアプリケーションを一時的に停止する必要があります。本画面は、このような計画的なメンテナンス時にユーザーに対して適切な情報を提供し、いつサービスが復旧するかの見通しを伝えることができます。Laravel の `php artisan down` コマンドによりメンテナンスモードを有効化すると、この画面が表示されます。また、予期しないサーバー過負荷やリソース不足の場合にも表示されることがあります。

**画面へのアクセス方法**：この画面は直接アクセスするものではなく、以下のような状況で自動的に表示されます。
1. `php artisan down` コマンドでメンテナンスモードが有効化された場合
2. サーバーが過負荷状態でリクエストを処理できない場合
3. バックエンドサービスが一時的に利用できない場合
4. HttpException(503) がスローされた場合

**主要な操作・処理内容**：
1. エラーコード「503」とメッセージ「Service Unavailable」を画面中央に表示
2. ダークモード対応のスタイリングにより、ユーザーの表示設定に応じた適切な配色で表示
3. レスポンシブデザインにより、デスクトップ・モバイル両方のデバイスで適切に表示

**画面遷移**：
- 遷移元：メンテナンスモード中の任意のページへのアクセス
- 遷移先：なし（エラー表示のみ。メンテナンス終了後にサービスは自動的に復旧）

**権限による表示制御**：
- デフォルトでは全てのユーザーにこの画面が表示されます
- `php artisan down --secret="your-secret"` オプションを使用すると、特定のシークレットを知っているユーザーはメンテナンス画面をバイパスできます
- 特定の IP アドレスからのアクセスを許可する `--allow` オプションも利用可能です

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | ルーター | 主機能 | メンテナンスモード時のサービス停止画面表示 |
| 36 | ビューファクトリ | 補助機能 | Blade テンプレートのレンダリング処理 |

## 画面種別

エラー表示画面（メンテナンス画面）

## URL/ルーティング

この画面は特定の URL を持ちません。メンテナンスモード中は全ての URL へのアクセスでこの画面が表示されます。`PreventRequestsDuringMaintenance` ミドルウェアによって処理されます。

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|------|------|------|
| なし | - | - | この画面は入力項目を持ちません |

### 出力項目（テンプレート変数）

| 項目名 | 型 | 説明 |
|--------|------|------|
| $exception | HttpExceptionInterface | 発生した例外オブジェクト |
| $errors | ViewErrorBag | バリデーションエラーバッグ（空） |

### HTTPレスポンスヘッダー

| ヘッダー名 | 説明 |
|-----------|------|
| Retry-After | サービス復旧予定時刻（設定されている場合） |

## 表示項目

| 項目 | 表示内容 | スタイル |
|------|----------|----------|
| エラーコード | 503 | 大きなフォント、右ボーダー付き |
| エラーメッセージ | Service Unavailable | 大文字、トラッキング広め |

## イベント仕様

### 1-画面表示

本画面は静的なエラー表示のみを行い、ユーザーインタラクションのイベントは定義されていません。メンテナンス終了後にページを再読み込みすることでサービスに復帰できます。

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

本画面はデータベースへの読み書きを行いません。メンテナンスモードの状態は `storage/framework/down` ファイルで管理されます。

## メッセージ仕様

| メッセージ種別 | メッセージコード | メッセージ内容 | 表示条件 |
|--------------|----------------|--------------|----------|
| エラー | - | Service Unavailable | 常時表示 |

**多言語対応**：メッセージは `__('Service Unavailable')` ヘルパー関数を使用しており、言語ファイルにより翻訳可能です。

## 例外処理

本画面自体が例外処理の結果として表示されるため、画面内での例外処理は定義されていません。テンプレートのレンダリングに失敗した場合は、Symfony の HtmlErrorRenderer によるフォールバック表示が行われます。

## 備考

- この画面は `minimal.blade.php` レイアウトを継承しています
- `php artisan down` コマンドでメンテナンスモードを有効化します
- `php artisan up` コマンドでメンテナンスモードを終了します
- カスタマイズする場合は、`resources/views/errors/503.blade.php` にファイルを配置することで上書き可能です
- `php artisan down --render="errors::maintenance"` で別のビューを指定することも可能です
- ダークモード対応のスタイリングが含まれています（`prefers-color-scheme: dark` メディアクエリ使用）
- メンテナンスモードでは静的ファイル（CSS、JS、画像など）も提供されないため、インラインスタイルが使用されています

---

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

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

### 推奨読解順序

#### Step 1: メンテナンスモードの仕組みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DownCommand.php | `src/Illuminate/Foundation/Console/DownCommand.php` | メンテナンスモード開始コマンド |
| 1-2 | UpCommand.php | `src/Illuminate/Foundation/Console/UpCommand.php` | メンテナンスモード終了コマンド |
| 1-3 | MaintenanceModeManager.php | `src/Illuminate/Foundation/MaintenanceModeManager.php` | メンテナンスモードの状態管理 |

**読解のコツ**: メンテナンスモードは `storage/framework/down` ファイルの存在で判定されます。このファイルには JSON 形式でメンテナンス情報が保存されます。

#### Step 2: リクエスト処理の流れを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | PreventRequestsDuringMaintenance.php | `src/Illuminate/Foundation/Http/Middleware/PreventRequestsDuringMaintenance.php` | メンテナンスモードチェックミドルウェア |

**主要処理フロー**:
- アプリケーションがメンテナンスモードかチェック
- 許可された IP やシークレットをチェック
- 条件を満たさない場合に 503 例外をスロー

#### Step 3: 例外ハンドリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Handler.php | `src/Illuminate/Foundation/Exceptions/Handler.php` | 例外ハンドラのメインクラス |

**主要処理フロー**:
1. **行 920-938**: `renderHttpException()` メソッドで HTTP 例外のレンダリングを実行
2. **行 922**: `registerErrorViewPaths()` でエラービューのパスを登録
3. **行 958-968**: `getHttpExceptionView()` でステータスコードに基づくビュー名を決定

#### Step 4: テンプレート継承を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | 503.blade.php | `src/Illuminate/Foundation/Exceptions/views/503.blade.php` | 503 エラー専用テンプレート |
| 4-2 | minimal.blade.php | `src/Illuminate/Foundation/Exceptions/views/minimal.blade.php` | 共通レイアウトテンプレート |

**主要処理フロー**:
- **503.blade.php 行 1**: `@extends('errors::minimal')` で共通レイアウトを継承
- **503.blade.php 行 3-5**: `@section` でタイトル、コード、メッセージを定義

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

```
php artisan down
    │
    ├─ DownCommand::handle()
    │      └─ MaintenanceModeManager::activate()
    │             └─ storage/framework/down ファイル作成
    │
HTTP リクエスト
    │
    ├─ PreventRequestsDuringMaintenance ミドルウェア
    │      │
    │      ├─ MaintenanceModeManager::active()
    │      │      └─ メンテナンスモード判定
    │      │
    │      ├─ 許可チェック（IP、シークレット）
    │      │
    │      └─ HttpException(503) スロー
    │
    ├─ Handler::render()
    │      │
    │      └─ Handler::prepareResponse()
    │             │
    │             └─ Handler::renderHttpException()
    │                    │
    │                    ├─ Handler::registerErrorViewPaths()
    │                    │
    │                    └─ Handler::getHttpExceptionView()
    │                           └─ view()->exists('errors::503')
    │
    └─ response()->view('errors::503', [...])
           └─ 503.blade.php
                  └─ minimal.blade.php（継承）
```

### データフロー図

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

php artisan down    ───▶ DownCommand               ───▶ down ファイル作成
                          │
                          └─ storage/framework/down

HTTP リクエスト      ───▶ PreventRequestsDuringMaintenance
                          │
                          ├─ down ファイル存在チェック
                          │
                          ├─ 許可チェック
                          │      ├─ IP アドレス
                          │      └─ シークレット
                          │
                          └─ HttpException(503) スロー
                                 │
                                 ▼
                           Handler::render()
                                 │
                                 └─ response()->view()   ───▶ HTTP Response
                                        │                      (status: 503)
                                        └─ 503.blade.php
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 503.blade.php | `src/Illuminate/Foundation/Exceptions/views/503.blade.php` | テンプレート | 503 エラー専用のコンテンツ定義 |
| minimal.blade.php | `src/Illuminate/Foundation/Exceptions/views/minimal.blade.php` | テンプレート | エラー画面の共通レイアウト |
| Handler.php | `src/Illuminate/Foundation/Exceptions/Handler.php` | ソース | 例外ハンドリングとビュー選択のロジック |
| RegisterErrorViewPaths.php | `src/Illuminate/Foundation/Exceptions/RegisterErrorViewPaths.php` | ソース | エラービューパスの登録処理 |
| PreventRequestsDuringMaintenance.php | `src/Illuminate/Foundation/Http/Middleware/PreventRequestsDuringMaintenance.php` | ソース | メンテナンスモードチェックミドルウェア |
| DownCommand.php | `src/Illuminate/Foundation/Console/DownCommand.php` | ソース | メンテナンスモード開始コマンド |
| UpCommand.php | `src/Illuminate/Foundation/Console/UpCommand.php` | ソース | メンテナンスモード終了コマンド |
| MaintenanceModeManager.php | `src/Illuminate/Foundation/MaintenanceModeManager.php` | ソース | メンテナンスモードの状態管理 |
