# 画面設計書 1-スプラッシュ画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリのスプラッシュ画面に関する設計書です。アプリ起動時に最初に表示される画面であり、初期化処理を行いながらユーザーにアプリのブランドイメージを印象付ける重要な役割を持ちます。

### 本画面の処理概要

**業務上の目的・背景**：スプラッシュ画面は、アプリケーション起動時にユーザーに視覚的なフィードバックを提供し、バックグラウンドで必要な初期化処理（CMSデータのプリキャッシュ、言語データの取得、アプリケーションドキュメントパスの取得など）を行うために必要です。ユーザーがアプリ起動後に即座に機能を使用できるよう、事前にデータをロードしておくことでユーザー体験を向上させます。

**画面へのアクセス方法**：アプリケーションを起動した際に自動的に表示されます。ユーザーが意図的にアクセスする画面ではなく、アプリの起動フローにおいて最初に表示されるエントリーポイントです。

**主要な操作・処理内容**：
1. アプリケーションドキュメントディレクトリのパスを取得し、グローバル変数に保存
2. CMSデータ（利用規約、プライバシーポリシー等）をプリキャッシュ
3. 言語・通貨データをプリキャッシュ
4. Lottieアニメーションを表示してブランディング
5. 設定されたディレイ時間（defaultSplashDelay秒）後にホーム画面へ自動遷移

**画面遷移**：
- 遷移元：なし（アプリ起動時に最初に表示）
- 遷移先：ホーム画面（初期化完了後に自動遷移）

**権限による表示制御**：なし。全ユーザーに同一の画面が表示されます。ログイン状態に関わらず同じ処理が実行されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 69 | スプラッシュスクリーン | 主機能 | アプリ起動時の初期化処理を行い、ホーム画面へ遷移する |

## 画面種別

起動画面（スプラッシュ）

## URL/ルーティング

- ルート名: `splash` (splashScreen)
- パス: `/` (アプリ起動時の初期ルート)

## 入出力項目

本画面はユーザー入力を受け付けません。

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| なし | - | - | ユーザー操作なし |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| Lottieアニメーション | Widget | スプラッシュ画面用のブランドアニメーション（AssetConstants.splashLottie） |

## イベント仕様

### 1-画面初期化イベント（initState）

**トリガー**: 画面がマウントされたタイミング

**処理フロー**:
1. `_navigateHomepage()`メソッドを呼び出し
   - `getApplicationDocumentsDirectory()`でアプリドキュメントディレクトリを取得
   - 取得したパスを`appDocPath`グローバル変数に保存
   - `Timer`を使用して`defaultSplashDelay`秒後にホーム画面へ遷移
2. `preCacheCMSData()`を呼び出してCMSデータをプリキャッシュ
3. `preCacheLanguageData()`を呼び出して言語・通貨データをプリキャッシュ

**遷移先**: ホーム画面（`Navigator.pushReplacementNamed(context, home)`）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期化 | なし | なし | データベースへの直接アクセスなし |

本画面ではデータベースへの直接的な更新処理は行いません。プリキャッシュ処理はAPIからデータを取得し、ローカルキャッシュに保存する処理です。

## メッセージ仕様

| メッセージID | メッセージ種別 | 表示条件 | メッセージ内容 |
|-------------|--------------|----------|--------------|
| なし | - | - | 本画面ではユーザーへのメッセージ表示は行わない |

## 例外処理

| 例外ケース | 処理内容 | ユーザーへの影響 |
|-----------|---------|----------------|
| ドキュメントディレクトリ取得失敗 | 例外がスローされる可能性 | アプリが正常に起動しない可能性 |
| CMSデータ取得失敗 | debugPrintでエラーログ出力、処理継続 | CMSページ表示時にデータがない可能性 |
| 言語データ取得失敗 | debugPrintでエラーログ出力、処理継続 | 言語切替機能に影響の可能性 |

## 備考

- スプラッシュ画面のディレイ時間は`defaultSplashDelay`定数で制御されており、`server_configuration.dart`で設定可能
- Lottieアニメーションファイルは`AssetConstants.splashLottie`で指定されたアセットを使用
- 画面の背景色は黒（`Colors.black`）に設定
- コメントアウトされたコードには静止画像とローダーを使用した代替実装が存在

---

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

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

### 推奨読解順序

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

スプラッシュ画面では直接的なデータモデルは使用しないが、プリキャッシュ処理で取得されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | currency_language_model.dart | `lib/data_model/currency_language_model.dart` | 言語・通貨データのモデル構造を確認 |

**読解のコツ**: FlutterのデータモデルはfromJsonファクトリメソッドを持つことが多い。JSON構造との対応関係を確認する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | splash_screen.dart | `lib/screens/splash_screen/view/splash_screen.dart` | 画面のメインウィジェットとライフサイクル |

**主要処理フロー**:
1. **25-29行目**: `initState()`で初期化処理を開始
2. **26行目**: `_navigateHomepage()`でホーム画面への遷移をスケジュール
3. **27行目**: `preCacheCMSData()`でCMSデータをプリキャッシュ
4. **28行目**: `preCacheLanguageData()`で言語データをプリキャッシュ
5. **33-57行目**: `build()`でLottieアニメーションを表示
6. **60-66行目**: `_navigateHomepage()`でディレイ後にホーム画面へ遷移

#### Step 3: プリキャッシュ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | prefetching_helper.dart | `lib/utils/prefetching_helper.dart` | プリキャッシュ処理の実装詳細 |

**主要処理フロー**:
- **19-27行目**: `preCacheLanguageData()`で言語・通貨データをAPIから取得
- **29-36行目**: `preCacheCMSData()`でCMSページデータをAPIから取得

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | route_constants.dart | `lib/utils/route_constants.dart` | ルート名定数の定義 |

**主要処理フロー**:
- **11行目**: `splash`ルート名の定義
- **12行目**: `home`ルート名の定義（遷移先）

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

```
SplashScreen (StatefulWidget)
    │
    ├─ initState()
    │      ├─ _navigateHomepage()
    │      │      ├─ getApplicationDocumentsDirectory() [path_provider]
    │      │      └─ Timer → Navigator.pushReplacementNamed(context, home)
    │      │
    │      ├─ preCacheCMSData() [prefetching_helper.dart]
    │      │      └─ ApiClient().getCmsPagesData()
    │      │
    │      └─ preCacheLanguageData() [prefetching_helper.dart]
    │             └─ ApiClient().getLanguageCurrency()
    │
    └─ build()
           └─ Scaffold
                  └─ LottieBuilder.asset(AssetConstants.splashLottie)
```

### データフロー図

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

なし ─────────────▶ getApplicationDocumentsDirectory() ───▶ appDocPath (グローバル変数)

なし ─────────────▶ ApiClient().getCmsPagesData() ───────▶ GlobalData.cmsData (キャッシュ)

なし ─────────────▶ ApiClient().getLanguageCurrency() ───▶ GlobalData.languageData (キャッシュ)

Timer完了 ─────────▶ Navigator.pushReplacementNamed ──────▶ ホーム画面へ遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| splash_screen.dart | `lib/screens/splash_screen/view/splash_screen.dart` | ソース | スプラッシュ画面のメインウィジェット |
| index.dart | `lib/screens/splash_screen/utils/index.dart` | ソース | スプラッシュ画面用のエクスポート集約 |
| prefetching_helper.dart | `lib/utils/prefetching_helper.dart` | ソース | プリキャッシュ処理のヘルパー関数 |
| route_constants.dart | `lib/utils/route_constants.dart` | ソース | ルーティング定数定義 |
| server_configuration.dart | `lib/utils/server_configuration.dart` | 設定 | サーバー設定・定数（defaultSplashDelay等） |
| api_client.dart | `lib/services/api_client.dart` | ソース | API通信クライアント |
| currency_language_model.dart | `lib/data_model/currency_language_model.dart` | ソース | 言語・通貨データモデル |
| app_global_data.dart | `lib/utils/app_global_data.dart` | ソース | グローバルデータ管理 |
