# 画面設計書 7-ウェルカム画面

## 概要

本ドキュメントは、Actual Budget アプリケーションのウェルカム画面の設計仕様を記述したものである。

### 本画面の処理概要

ウェルカム画面は、初めてActual Budgetを利用するユーザー、または予算ファイルが存在しない状態でアクセスした際に表示される案内画面である。アプリケーションの紹介と、予算ファイルの作成・インポート方法を案内する。

**業務上の目的・背景**：新規ユーザーがアプリケーションを初めて使用する際に、Actual Budgetの特徴や使い方を理解し、スムーズに予算管理を開始できるようにするための導入画面である。封筒予算システムの概念へのリンクや、ガイドツアーへの誘導を提供し、ユーザーオンボーディングを支援する。

**画面へのアクセス方法**：以下の条件でこの画面に遷移する：
- 認証済みで、予算ファイルが0件の状態でルート画面（`/`）にアクセス
- ManagementApp内で files.length が 0 の場合に自動表示

**主要な操作・処理内容**：
1. 「Import my budget」でインポートモーダルを開く（YNAB4/YNAB5/Actual形式対応）
2. 「View demo」でデモ予算ファイルを作成
3. 「Start fresh」で新規空予算ファイルを作成

**画面遷移**：
- 遷移元：ログイン完了後（予算ファイルが存在しない場合）
- 遷移先：予算画面（`/budget`）（予算ファイル作成後）、インポートモーダル

**権限による表示制御**：この画面は認証済みかつ予算ファイルが存在しない場合のみ表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 30 | YNAB4インポート | 遷移先機能 | YNAB4形式のデータインポート画面への遷移 |
| 31 | YNAB5（nYNAB）インポート | 遷移先機能 | YNAB5形式のデータインポート画面への遷移 |
| 32 | Actualフォーマットインポート | 遷移先機能 | Actualバックアップからのインポート画面への遷移 |

## 画面種別

案内画面（初期設定）

## URL/ルーティング

`/`（予算ファイルが0件の場合に表示）

## 入出力項目

| 項目名 | 項目ID | 入出力 | 必須 | データ型 | 最大長 | 備考 |
|--------|--------|--------|------|----------|--------|------|
| - | - | - | - | - | - | 入力項目なし |

## 表示項目

| 項目名 | 表示内容 | 備考 |
|--------|----------|------|
| タイトル | "Let's get started!" | 固定テキスト |
| 説明文1 | Actual Budgetの紹介文 | 編集の高速さを強調 |
| 説明文2 | 封筒予算システムの説明とガイドツアーへのリンク | 外部リンクあり |
| 説明文3 | 開始方法の案内 | インポート/デモ/新規作成の選択肢 |

## イベント仕様

### 1-予算インポート（Import my budgetボタン押下）

1. `pushModal` アクションをdispatchしてインポートモーダルを表示
2. モーダル内でYNAB4/YNAB5/Actual形式のインポートを選択可能
3. インポート完了後、予算画面に遷移

### 2-デモ表示（View demoボタン押下）

1. `createBudget` アクションを `testMode: true` で実行
2. サンプルデータを含むデモ予算ファイルが作成される
3. 予算画面に遷移

### 3-新規作成（Start freshボタン押下）

1. `createBudget` アクションを空オプションで実行
2. 空の予算ファイルが作成される
3. 予算画面に遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| デモ表示 | budgets, categories, transactions等 | INSERT | デモデータを含む予算ファイルを作成 |
| 新規作成 | budgets, categories | INSERT | 空の予算ファイルを作成 |
| インポート | budgets, categories, transactions等 | INSERT | インポートしたデータで予算ファイルを作成 |

### テーブル別更新項目詳細

#### budgets

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成UUID | 予算ファイルID |
| INSERT | name | "My Budget" または インポート元名 | 予算ファイル名 |
| INSERT | created_at | 現在時刻 | 作成日時 |

## メッセージ仕様

| メッセージID | メッセージ内容 | 種別 | 表示条件 |
|-------------|---------------|------|----------|
| - | - | - | この画面にはエラーメッセージなし |

## 例外処理

| 例外ケース | 処理内容 |
|------------|----------|
| 予算ファイル作成失敗 | エラー通知を表示（Notificationsコンポーネント経由） |
| インポート失敗 | インポートモーダル内でエラーメッセージを表示 |

## 備考

- この画面は予算ファイルが存在しない場合のみ表示される
- 予算ファイルが1件以上存在する場合は、BudgetFileSelection画面が表示される
- 外部リンク（封筒予算システム、ガイドツアー）はactualbudget.orgドキュメントサイトを参照

---

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

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

### 推奨読解順序

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

予算ファイル作成のパラメータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | budgetfilesSlice.ts | `packages/desktop-client/src/budgetfiles/budgetfilesSlice.ts` | createBudget アクションの型定義 |

**読解のコツ**: `testMode` と `demoMode` の違い、インポート時のオプションを確認する

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

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

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

**主要処理フロー**:
1. **16-18行目**: WelcomeScreen関数の初期化、hooks使用
2. **30行目**: タイトル表示 "Let's get started!"
3. **31-75行目**: 説明文とリンクの表示
4. **84-88行目**: "Import my budget" ボタンでインポートモーダル表示
5. **96行目**: "View demo" ボタンでデモ予算作成
6. **99-105行目**: "Start fresh" ボタンで新規予算作成

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

画面表示条件を理解する。

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

**主要処理フロー**:
- **142-145行目**: files.length > 0 で BudgetFileSelection、そうでなければ WelcomeScreen を表示

#### Step 4: 予算作成処理を理解する

createBudget アクションの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | budgetfilesSlice.ts | `packages/desktop-client/src/budgetfiles/budgetfilesSlice.ts` | createBudget の実装 |

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

```
WelcomeScreen (WelcomeScreen.tsx)
    │
    ├─ "Import my budget" ボタン
    │      └─ dispatch(pushModal({ modal: { name: 'import' } }))
    │             └─ インポートモーダル表示
    │                    ├─ YNAB4インポート
    │                    ├─ YNAB5インポート
    │                    └─ Actualインポート
    │
    ├─ "View demo" ボタン
    │      └─ dispatch(createBudget({ testMode: true }))
    │             └─ デモ予算ファイル作成
    │                    └─ 予算画面へ遷移
    │
    └─ "Start fresh" ボタン
           └─ dispatch(createBudget({}))
                  └─ 空の予算ファイル作成
                         └─ 予算画面へ遷移
```

### データフロー図

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

                    WelcomeScreen表示
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   Import         View demo         Start fresh
        │                │                │
        ▼                ▼                ▼
   pushModal      createBudget     createBudget
   (import)       (testMode)       (empty)
        │                │                │
        ▼                │                │
   インポート            │                │
   モーダル              │                │
        │                │                │
        └────────────────┼────────────────┘
                         ▼
                    budgets テーブル更新
                         │
                         ▼
                    Redux state 更新
                         │
                         ▼
                    予算画面 (/budget) へ遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WelcomeScreen.tsx | `packages/desktop-client/src/components/manager/WelcomeScreen.tsx` | ソース | メインコンポーネント |
| ManagementApp.tsx | `packages/desktop-client/src/components/manager/ManagementApp.tsx` | ソース | ルーティング定義・表示条件 |
| budgetfilesSlice.ts | `packages/desktop-client/src/budgetfiles/budgetfilesSlice.ts` | ソース | createBudget アクション |
| modalsSlice.ts | `packages/desktop-client/src/modals/modalsSlice.ts` | ソース | pushModal アクション |
| Link.tsx | `packages/desktop-client/src/components/common/Link.tsx` | ソース | 外部リンクコンポーネント |
