# 機能設計書 69-スプラッシュスクリーン

## 概要

本ドキュメントは、スプラッシュスクリーン機能の設計仕様を定義する。アプリ起動時に表示される初期画面で、アプリの初期化処理とホーム画面への遷移を担当する。

### 本機能の処理概要

**業務上の目的・背景**：アプリ起動時に必要な初期化処理（データプリフェッチ、ストレージパス取得等）を行う間、ユーザーにブランドロゴやローディングアニメーションを表示する。これにより、ユーザー体験を向上させるとともに、バックグラウンドで必要なデータを準備できる。

**機能の利用シーン**：
- アプリの初回起動時
- アプリの再起動時（言語・通貨変更後など）
- バックグラウンドから復帰時（状態によっては）

**主要な処理内容**：
1. アプリケーションドキュメントディレクトリのパスを取得
2. CMSデータと言語データをプリフェッチ（バックグラウンド処理）
3. 一定時間（defaultSplashDelay秒）後にホーム画面へ遷移
4. Lottieアニメーションでブランディング表示

**関連システム・外部連携**：
- path_provider（アプリケーションドキュメントディレクトリ取得）
- Lottie（アニメーション表示）
- PrefetchingHelper（データプリフェッチ）

**権限による制御**：認証状態に関わらず、アプリ起動時に必ず表示。

## 関連画面

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

## 機能種別

初期化処理・画面遷移処理

## 入力仕様

### 入力パラメータ

なし（アプリ起動時に自動的に呼び出される）

### 入力データソース

- システムからのアプリ起動イベント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| appDocPath | String | アプリケーションドキュメントディレクトリパス（グローバル変数） |

### 出力先

- グローバル変数（appDocPath）
- 画面遷移（ホーム画面）

## 処理フロー

### 処理シーケンス

```
1. 画面初期化（initState）
   └─ _navigateHomepageを呼び出し
   └─ preCacheCMSDataを呼び出し（非同期）
   └─ preCacheLanguageDataを呼び出し（非同期）
2. _navigateHomepage処理
   └─ getApplicationDocumentsDirectoryでパス取得
   └─ appDocPathグローバル変数に保存
   └─ Timer設定（defaultSplashDelay秒後）
3. タイマー完了
   └─ Navigator.pushReplacementNamedでホーム画面へ遷移
4. UI表示
   └─ 黒背景にLottieアニメーション表示
```

### フローチャート

```mermaid
flowchart TD
    A[アプリ起動] --> B[SplashScreen表示]
    B --> C[initState]
    C --> D[_navigateHomepage]
    C --> E[preCacheCMSData]
    C --> F[preCacheLanguageData]
    D --> G[getApplicationDocumentsDirectory]
    G --> H[appDocPath保存]
    H --> I[Timer設定]
    I --> J{defaultSplashDelay経過}
    J -->|Yes| K[ホーム画面へ遷移]
    E --> L[CMSデータキャッシュ]
    F --> M[言語データキャッシュ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-69-01 | 遅延時間 | defaultSplashDelay秒後にホーム画面へ遷移 | 常時 |
| BR-69-02 | データプリフェッチ | CMSと言語データを非同期でプリフェッチ | 常時 |
| BR-69-03 | パス取得 | アプリドキュメントディレクトリパスを取得して保存 | 常時 |
| BR-69-04 | 遷移方式 | pushReplacementNamedでスタックを置換して遷移 | 常時 |

### 計算ロジック

該当なし

## データベース操作仕様

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

本機能はローカルストレージへのパス取得のみ行い、データベース操作は行わない。

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| パス取得 | ファイルシステム | READ | アプリケーションドキュメントディレクトリパスを取得 |

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ディレクトリ取得エラー | ストレージアクセス権限不足 | 例外発生、アプリ起動失敗 |
| - | プリフェッチエラー | ネットワーク接続失敗 | 非同期処理のため画面遷移には影響なし |

### リトライ仕様

プリフェッチ処理は失敗しても画面遷移には影響しない。失敗した場合は後続の画面でオンデマンドでデータを取得する。

## トランザクション仕様

該当なし

## パフォーマンス要件

- スプラッシュ画面表示: defaultSplashDelay秒（設定値）
- Lottieアニメーション: スムーズに60FPSで再生

## セキュリティ考慮事項

- 認証状態に関わらず表示される公開画面
- センシティブな情報は表示しない
- ストレージアクセスはアプリ固有ディレクトリのみ

## 備考

- defaultSplashDelayはserver_configuration.dartで定義されている
- Lottieアニメーションファイルはassets/に配置
- プリフェッチ処理の完了を待たずにタイマーで遷移するため、ネットワーク遅延の影響を受けない

---

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

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

### 推奨読解順序

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

処理の起点となる画面ファイルを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | splash_screen.dart | `lib/screens/splash_screen/view/splash_screen.dart` | SplashScreenウィジェット、initState処理 |

**主要処理フロー**:
1. **25-29行目**: initStateで3つの処理を呼び出し
2. **26行目**: _navigateHomepageでタイマー設定とホーム遷移
3. **27行目**: preCacheCMSDataでCMSデータをプリフェッチ
4. **28行目**: preCacheLanguageDataで言語データをプリフェッチ
5. **33-57行目**: buildメソッドでLottieアニメーション表示

#### Step 2: ホーム画面遷移処理を理解する

タイマーを使った画面遷移処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | splash_screen.dart | `lib/screens/splash_screen/view/splash_screen.dart` | _navigateHomepageメソッド |

**主要処理フロー**:
- **60行目**: async関数として定義
- **61行目**: getApplicationDocumentsDirectory()でディレクトリ取得
- **62行目**: appDocPathグローバル変数に保存
- **63-65行目**: Timer設定、defaultSplashDelay秒後にホーム画面へ遷移
- **64行目**: pushReplacementNamedでスタックを置換して遷移

#### Step 3: プリフェッチ処理を理解する

バックグラウンドでのデータプリフェッチを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | prefetching_helper.dart | `lib/utils/prefetching_helper.dart` | preCacheCMSData、preCacheLanguageData関数 |

**読解のコツ**:
- プリフェッチ関数は非同期で実行される
- 結果を待たずに画面遷移するため、ユーザー体験に影響しない
- キャッシュされたデータは後続の画面で高速アクセス可能

#### Step 4: 設定値を理解する

遅延時間などの設定値を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | server_configuration.dart | `lib/utils/server_configuration.dart` | defaultSplashDelay定数 |

**読解のコツ**:
- defaultSplashDelayはDuration(seconds: X)のXに相当する秒数
- アプリのブランディング表示時間として設定

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

```
SplashScreen (splash_screen.dart)
    │
    ├─ initState
    │      ├─ _navigateHomepage()
    │      │      ├─ getApplicationDocumentsDirectory()
    │      │      ├─ appDocPath = appDocDir.path
    │      │      └─ Timer(Duration(seconds: defaultSplashDelay))
    │      │             └─ Navigator.pushReplacementNamed(context, home)
    │      │
    │      ├─ preCacheCMSData()
    │      │      └─ [非同期] CMSデータをキャッシュ
    │      │
    │      └─ preCacheLanguageData()
    │             └─ [非同期] 言語データをキャッシュ
    │
    └─ build
           └─ Scaffold
                  └─ LottieBuilder.asset(splashLottie)
```

### データフロー図

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

アプリ起動 ───────────▶ SplashScreen.initState
                              │
                              ├─────────────────────────▶ _navigateHomepage
                              │                                 │
                              │                                 ├─ getApplicationDocumentsDirectory
                              │                                 │         │
                              │                                 │         ▼
                              │                                 │    appDocPath保存
                              │                                 │
                              │                                 └─ Timer(defaultSplashDelay)
                              │                                           │
                              │                                           ▼
                              │                                 ホーム画面へ遷移
                              │
                              ├─────────────────────────▶ preCacheCMSData
                              │                                 │
                              │                                 ▼
                              │                          CMSデータキャッシュ
                              │
                              └─────────────────────────▶ preCacheLanguageData
                                                                │
                                                                ▼
                                                         言語データキャッシュ

Lottieアニメーション ────────────────────────────────▶ 画面表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ソース | データプリフェッチユーティリティ |
| server_configuration.dart | `lib/utils/server_configuration.dart` | 設定 | サーバー設定・定数 |
| asset_constants.dart | `lib/utils/assets_constants.dart` | 設定 | アセットパス定数 |
| route_constants.dart | `lib/utils/route_constants.dart` | 設定 | ルート名定数（home等） |
