# 機能設計書 6-ホームページ表示

## 概要

本ドキュメントは、ECモバイルアプリケーションにおけるホームページ表示機能の設計仕様を定義する。アプリのメイン画面として、スライダー、カテゴリ、商品一覧、バナー等のコンテンツを動的に取得・表示する。

### 本機能の処理概要

**業務上の目的・背景**：ECアプリのメインエントランスとして、ユーザーにおすすめ商品、キャンペーン情報、カテゴリへのナビゲーションを提供する。CMSで設定されたテーマカスタマイズデータに基づき、動的にレイアウトを構成する。

**機能の利用シーン**：アプリ起動時、またはログイン成功後の遷移先として表示される。また、ボトムナビゲーションの「ホーム」タブをタップした際にも表示される。

**主要な処理内容**：
1. テーマカスタマイズデータの取得（スライダー、バナー、商品カルーセル等の設定）
2. ホームカテゴリ一覧の取得
3. 商品一覧の取得（カルーセル用）
4. CMSページ一覧の取得
5. ログインユーザーの場合、顧客詳細情報の取得
6. カート数量の取得
7. 各コンテンツのUI描画

**関連システム・外部連携**：Bagisto（Laravel製ECプラットフォーム）のGraphQL APIと連携し、複数のqueryを順次または並列で呼び出す。

**権限による制御**：本機能はログイン/未ログイン問わず利用可能。ログイン状態によって表示コンテンツの一部（お気に入り状態等）が変化する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | ホーム画面 | 主画面 | 各種コンテンツの表示、商品タップ、カテゴリタップ |
| 3 | ドロワー | 参照画面 | ドロワーメニューの表示 |
| 7 | カテゴリ一覧画面 | 遷移先画面 | カテゴリタップ時の遷移先 |
| 9 | 商品詳細画面 | 遷移先画面 | 商品タップ時の遷移先 |

## 機能種別

データ取得 / UI描画 / API連携 / キャッシュ管理

## 入力仕様

### 入力パラメータ

本機能の初期表示時には明示的な入力パラメータなし。テーマカスタマイズデータに基づくフィルタ条件が内部的に使用される。

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| filters | List<Map<String, dynamic>> | No | カテゴリ/商品取得用フィルタ | テーマ設定から自動生成 |
| locale | String | No | 言語コード | GlobalData.localeから取得 |

### 入力データソース

- テーマカスタマイズAPI：商品カルーセル、カテゴリカルーセルのフィルタ条件
- SharedPreferences：言語設定、通貨設定、ログイン状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ThemeCustomDataModel | Object | テーマカスタマイズ設定（スライダー、バナー、サービス等） |
| GetDrawerCategoriesData | Object | カテゴリ一覧 |
| NewProductsModel | Object | 商品一覧（カルーセル用） |
| CmsData | Object | CMSページ一覧 |
| AccountInfoModel | Object | ログインユーザーの詳細情報 |
| CartModel | Object | カート情報 |

### 出力先

- 画面UI：ホーム画面の各セクションに描画
- GlobalData：商品データ、カテゴリデータをグローバル状態に保存
- SharedPreferences：ドロワーカテゴリデータをキャッシュ

## 処理フロー

### 処理シーケンス

```
1. ホーム画面の初期化
   └─ initState()でBlocと各種リスナーを設定

2. ホームページデータの取得開始
   └─ FetchHomeCustomDataイベント発行

3. テーマカスタマイズデータ取得
   └─ themeCustomization queryを実行
   └─ 取得したデータからカルーセル設定を解析

4. 商品カルーセルデータ取得（複数並列）
   └─ product_carouselタイプごとにFetchAllProductsEvent発行

5. カテゴリカルーセルデータ取得
   └─ category_carouselタイプでFetchHomePageCategoriesEvent発行

6. ドロワー用カテゴリ取得
   └─ FetchDrawerPageEvent発行

7. CMSページ取得
   └─ FetchCMSDataEvent発行

8. ログインユーザーの場合、顧客詳細取得
   └─ CustomerDetailsEvent発行

9. カート数量取得
   └─ CartCountEvent発行

10. 各データを受信してUIを更新
    └─ BlocConsumerで状態変化を監視してrebuild
```

### フローチャート

```mermaid
flowchart TD
    A[ホーム画面表示] --> B[テーマカスタマイズ取得]
    B --> C{カルーセル設定解析}
    C --> D[商品カルーセル取得]
    C --> E[カテゴリカルーセル取得]
    D --> F[GlobalData.allProductsに保存]
    E --> G[カテゴリデータ保存]
    F --> H[CMSページ取得]
    G --> H
    H --> I{ログイン済み?}
    I -->|Yes| J[顧客詳細取得]
    I -->|No| K[カート数量取得]
    J --> K
    K --> L[UI描画完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | テーマ設定優先 | CMS設定に基づいてホーム画面のレイアウトを構成 | 常時 |
| BR-002 | 言語別コンテンツ | GlobalData.localeに応じた翻訳コンテンツを表示 | 常時 |
| BR-003 | キャッシュ利用 | ドロワーカテゴリはSharedPreferencesにキャッシュ | 初回取得後 |
| BR-004 | お気に入り状態表示 | ログインユーザーには商品のお気に入り状態を表示 | ログイン時 |
| BR-005 | カート数表示 | AppBarにカート内商品数をバッジ表示 | 常時 |

### 計算ロジック

本機能に計算ロジックは存在しない。

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

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

モバイルアプリ側ではデータベース操作なし（APIからのデータ取得のみ）。

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

#### SharedPreferences（ローカルストレージ）

| 操作 | 項目（キー名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| READ | customerLoggedIn | ログイン状態確認 | 顧客詳細取得の判定用 |
| READ/WRITE | drawerCategories | カテゴリデータ | Hive経由でキャッシュ |
| READ/WRITE | cartCount | カート数量 | グローバル状態と同期 |
| WRITE | customerDetails | 顧客情報 | ログインユーザーのみ |
| WRITE | customerImage | プロフィール画像URL | ログインユーザーのみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ネットワークエラー | API通信失敗 | ローディング表示を継続、またはエラー画面表示 |
| - | データ取得エラー | 各APIでエラーレスポンス | FetchXxxState.fail発行、エラーメッセージ表示 |
| - | パースエラー | JSONパース失敗 | エラーログ出力、デフォルト値使用 |

### リトライ仕様

本機能にリトライ処理は実装されていない。ユーザーはアプリを再起動するか、Pull-to-refreshで再取得する必要がある。

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

モバイルアプリ側ではトランザクション管理は行わない。

## パフォーマンス要件

- 初期表示：3秒以内（ローディング画面表示）
- 各APIの並列実行による高速化
- 画像のプリキャッシュによる表示高速化

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

- 商品価格等の重要データはAPIから毎回取得
- ログイン状態に応じた情報表示制御

## 備考

- 複数のAPIを順次/並列で呼び出す複雑なデータ取得フロー
- GlobalData.allProductsにカルーセル別の商品データを保存
- HomePageLoaderでスケルトンローディングを表示

---

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

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

### 推奨読解順序

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

複数のデータモデルを使用。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | theme_customization.dart | `lib/screens/home_page/data_model/theme_customization.dart` | ThemeCustomDataModel、ThemeCustomization、Translations、Options等 |
| 1-2 | get_categories_drawer_data_model.dart | `lib/screens/home_page/data_model/get_categories_drawer_data_model.dart` | GetDrawerCategoriesData、HomeCategories |
| 1-3 | new_product_data.dart | `lib/data_model/categories_data_model/filter_product_model.dart` | NewProductsModel（商品一覧） |

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | home_page.dart | `lib/screens/home_page/home_page.dart` | メイン画面のStatefulWidget |

**主要処理フロー**:
1. **35-48行目**: initStateで初期化処理、fetchHomepageData呼び出し
2. **54-57行目**: fetchHomepageDataでFetchHomeCustomData発行
3. **120-175行目**: BlocConsumerでHomePageBloc状態を監視
4. **178-285行目**: buildContainerで各状態に応じたUI切り替え
5. **325-358行目**: getHomePageDataでテーマ設定を解析してイベント発行

#### Step 3: ビジネスロジックを理解する

Blocでのイベント処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | home_page_bloc.dart | `lib/screens/home_page/bloc/home_page_bloc.dart` | 複数イベントの処理 |
| 3-2 | home_page_event.dart | `lib/screens/home_page/bloc/home_page_event.dart` | イベント定義 |
| 3-3 | home_page_state.dart | `lib/screens/home_page/bloc/home_page_state.dart` | 状態定義 |

**主要イベント**:
- **115-126行目**: FetchHomeCustomData - テーマ取得
- **127-141行目**: FetchAllProductsEvent - 商品取得
- **163-172行目**: FetchHomePageCategoriesEvent - カテゴリ取得

#### Step 4: リポジトリ層を理解する

API呼び出しの抽象化を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | home_page_repository.dart | `lib/screens/home_page/bloc/home_page_repository.dart` | 複数API呼び出しメソッド |

**主要メソッド**:
- **98-107行目**: getThemeCustomizationData()
- **148-159行目**: getAllProducts()
- **36-48行目**: getHomeCategoriesList()

#### Step 5: API通信層を理解する

GraphQL通信の実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | api_client.dart | `lib/services/api_client.dart` | 各API呼び出しメソッド |
| 5-2 | mutation_query.dart | `lib/services/mutation_query.dart` | themeCustomizationData、homeCategoriesFilters、allProductsList |

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

```
HomeScreen (View)
    │
    ├─ DrawerBloc (ドロワー用)
    │      └─ FetchDrawerPageEvent → カテゴリ取得
    │
    ├─ HomePageBloc (メインコンテンツ用)
    │      │
    │      ├─ FetchHomeCustomData → ThemeCustomDataModel
    │      │
    │      ├─ FetchAllProductsEvent → NewProductsModel
    │      │
    │      ├─ FetchHomePageCategoriesEvent → GetDrawerCategoriesData
    │      │
    │      ├─ FetchCMSDataEvent → CmsData
    │      │
    │      ├─ CustomerDetailsEvent → AccountInfoModel
    │      │
    │      └─ CartCountEvent → CartModel
    │
    └─ HomePageRepository
           │
           └─ ApiClient
                  │
                  └─ GraphQlApiCalling
```

### データフロー図

```
[初期化]                     [API呼び出し]                    [状態管理]

initState() ───▶ fetchHomepageData()
                     │
                     ▼
              FetchHomeCustomData ───▶ themeCustomization query
                     │                         │
                     │                         ▼
                     │              ThemeCustomDataModel
                     │                         │
                     ▼                         ▼
              getHomePageData() ───▶ テーマ設定解析
                     │
        ┌────────────┼────────────┐
        │            │            │
        ▼            ▼            ▼
FetchAllProducts  FetchCategories  FetchCMSData
        │            │            │
        ▼            ▼            ▼
NewProductsModel Categories    CmsData
        │            │            │
        └────────────┼────────────┘
                     │
                     ▼
              GlobalData.allProducts
                     │
                     ▼
              HomePageView (UI描画)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| home_page.dart | `lib/screens/home_page/home_page.dart` | ソース | ホーム画面メインウィジェット |
| home_page_view.dart | `lib/screens/home_page/view/home_page_view.dart` | ソース | ホーム画面UIビュー |
| home_page_bloc.dart | `lib/screens/home_page/bloc/home_page_bloc.dart` | ソース | 状態管理Bloc |
| home_page_event.dart | `lib/screens/home_page/bloc/home_page_event.dart` | ソース | イベント定義 |
| home_page_state.dart | `lib/screens/home_page/bloc/home_page_state.dart` | ソース | 状態定義 |
| home_page_repository.dart | `lib/screens/home_page/bloc/home_page_repository.dart` | ソース | リポジトリ層 |
| theme_customization.dart | `lib/screens/home_page/data_model/theme_customization.dart` | ソース | テーマカスタマイズモデル |
| get_categories_drawer_data_model.dart | `lib/screens/home_page/data_model/get_categories_drawer_data_model.dart` | ソース | カテゴリモデル |
| home_page_loader.dart | `lib/screens/home_page/view/home_page_loader.dart` | ソース | ローディングUI |
| api_client.dart | `lib/services/api_client.dart` | ソース | API通信クライアント |
| mutation_query.dart | `lib/services/mutation_query.dart` | ソース | GraphQLクエリ定義 |
