# 画面設計書 4-エラー画面

## 概要

本ドキュメントは、Actual Budget アプリケーションの認証エラー画面の設計仕様を記述したものである。

### 本画面の処理概要

エラー画面は、認証処理やサーバー接続でエラーが発生した際に表示されるエラー通知画面である。ユーザーにエラーの内容を伝え、再試行のオプションを提供する。

**業務上の目的・背景**：アプリケーションの初期化や認証プロセスで何らかの問題が発生した場合、ユーザーに適切なフィードバックを提供し、問題解決への導線を示すことが重要である。この画面は、ネットワーク障害、サーバー設定ミス、認証エラーなど様々な問題発生時にユーザーに状況を伝え、次のアクションを促す役割を持つ。

**画面へのアクセス方法**：以下の条件でこの画面に遷移する：
- サーバー接続チェック時にエラーが発生した場合（`useBootstrapped` hookからのリダイレクト）
- `/error` URLへの直接アクセス（React Routerのstate経由でエラー情報を受け取る）

**主要な操作・処理内容**：
1. エラーメッセージの表示（エラー種別に応じたメッセージ）
2. 「Try again」ボタンでルート画面（`/`）に再遷移

**画面遷移**：
- 遷移元：ブートストラップ画面、ログイン画面、サーバー接続チェック処理
- 遷移先：ルート画面（`/`）→ 状態に応じて適切な画面にリダイレクト

**権限による表示制御**：この画面は未認証時のみ表示される（ManagementApp内のルート）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 47 | パスワード認証 | 遷移先機能 | 認証エラー時の表示処理 |
| 48 | OpenID認証 | 遷移先機能 | OpenID認証エラー時の表示処理 |

## 画面種別

エラー通知画面

## URL/ルーティング

`/error`

## 入出力項目

| 項目名 | 項目ID | 入出力 | 必須 | データ型 | 最大長 | 備考 |
|--------|--------|--------|------|----------|--------|------|
| エラーコード | error | 入力（Router state） | 任意 | string | - | エラー種別を示すコード |

## 表示項目

| 項目名 | 表示内容 | 備考 |
|--------|----------|------|
| エラーメッセージ | エラー種別に応じたメッセージ | 動的に決定 |
| 再試行ボタン | "Try again" | 固定テキスト |

## イベント仕様

### 1-再試行（Try againボタン押下）

1. `navigate('/')` を実行してルート画面に遷移
2. ルート画面では、現在の状態に応じて適切な画面（ブートストラップ、ログイン、予算ファイル選択等）にリダイレクト

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | この画面ではデータベース更新なし |

## メッセージ仕様

| メッセージID | メッセージ内容 | 種別 | 表示条件 |
|-------------|---------------|------|----------|
| network-failure | "Unable to access server. Make sure the configured URL for the server is accessible." | エラー | ネットワーク接続失敗時 |
| default | "Server returned an error while checking its status." | エラー | 上記以外のエラー |

## 例外処理

| 例外ケース | 処理内容 |
|------------|----------|
| エラーコードが未指定 | デフォルトメッセージを表示 |
| Router stateが存在しない | デフォルトメッセージを表示 |

## 備考

- エラー情報はReact Routerの `location.state` 経由で受け渡される
- 「Try again」は現在の状態をリセットせず、単にルート画面に戻るだけ
- サーバー設定が間違っている場合、再試行しても同じエラーになる可能性がある

---

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

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

### 推奨読解順序

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

エラー情報の受け渡し方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | react-router | 外部ライブラリ | useLocation hookとstate引き渡し |

**読解のコツ**: React Routerの `navigate(path, { state })` と `useLocation().state` のパターンを理解する

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

メインコンポーネントの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Error.tsx | `packages/desktop-client/src/components/manager/subscribe/Error.tsx` | メインコンポーネントの実装 |

**主要処理フロー**:
1. **13-20行目**: getErrorMessage関数でエラーコードをメッセージに変換
2. **22-26行目**: Error関数コンポーネントの初期化、hooks使用
3. **25行目**: location.stateからerrorを取得
4. **27-29行目**: onTryAgain関数でルート画面に遷移
5. **31-46行目**: JSXレンダリング（エラーメッセージ、ボタン）

#### Step 3: エラー発生元を理解する

どこからこの画面に遷移してくるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | common.tsx | `packages/desktop-client/src/components/manager/subscribe/common.tsx` | useBootstrapped hookでのエラーハンドリング |

**主要処理フロー**:
- **79行目**: エラー発生時に `/error` にstate付きでナビゲート

#### Step 4: ルーティングを理解する

画面遷移の流れを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ManagementApp.tsx | `packages/desktop-client/src/components/manager/ManagementApp.tsx` | ルーティング定義 |

**主要処理フロー**:
- **194行目**: `/error` ルートの定義

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

```
[エラー発生源]
       │
       ├─ useBootstrapped (common.tsx)
       │      └─ subscribe-needs-bootstrap APIエラー
       │             └─ navigate('/error', { state: { error } })
       │
       └─ 他の認証処理
              └─ navigate('/error', { state: { error } })

       │
       ▼
Error (Error.tsx)
    │
    ├─ useLocation (react-router)
    │      └─ location.state.error 取得
    │
    ├─ getErrorMessage(error)
    │      └─ エラーコード → メッセージ変換
    │
    └─ onTryAgain
           └─ navigate('/')
                  └─ ルート画面へ遷移
```

### データフロー図

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

navigate('/error',
  { state: { error } }) ─▶ React Router state ───────────▶ location.state
                              │
                              ▼
                         useLocation()
                              │
                              ▼
                         error 取得
                              │
                              ▼
                    getErrorMessage(error) ──────────────▶ エラーメッセージ表示
                              │
                              ▼
                    [ユーザー: Try again クリック]
                              │
                              ▼
                        navigate('/') ───────────────────▶ ルート画面
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Error.tsx | `packages/desktop-client/src/components/manager/subscribe/Error.tsx` | ソース | メインコンポーネント |
| common.tsx | `packages/desktop-client/src/components/manager/subscribe/common.tsx` | ソース | エラー発生・遷移元 |
| ManagementApp.tsx | `packages/desktop-client/src/components/manager/ManagementApp.tsx` | ソース | ルーティング定義 |
| useNavigate.ts | `packages/desktop-client/src/hooks/useNavigate.ts` | ソース | ナビゲーションhook |
