# 画面設計書 3-ダッシュボード画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリのダッシュボード画面に関する設計書です。ログイン済みユーザーのアカウント情報を集約的に表示し、注文履歴、住所、レビューなどの主要機能へのアクセスを提供するハブ画面です。

### 本画面の処理概要

**業務上の目的・背景**：ダッシュボード画面は、ログイン済みユーザーが自身のアカウント情報や各種履歴にすばやくアクセスできるようにするための統合ビューです。ボトムナビゲーションの「アカウント」タブから遷移可能で、ユーザーの購買履歴、登録住所、投稿レビューを一元的に確認・管理できます。これにより、ユーザーは複数の画面を行き来することなく、主要な情報を把握できます。

**画面へのアクセス方法**：
- ボトムナビゲーションの「アカウント」タブをタップ
- ドロワーメニューの「ダッシュボード」をタップ
- 各種操作完了後のリダイレクト

**主要な操作・処理内容**：
1. ダッシュボードヘッダービューの表示（ユーザー情報サマリー）
2. タブバーによる3つのセクション切り替え（注文、住所、レビュー）
3. 最近の注文一覧の表示と詳細画面への遷移
4. 登録住所の一覧表示と住所管理画面への遷移
5. 投稿レビュー一覧の表示
6. 「買い物を続ける」ボタンによるホーム画面への遷移
7. 「住所追加」または「住所管理」ボタンによる住所画面への遷移

**画面遷移**：
- 遷移元：ホーム画面、ドロワーメニュー
- 遷移先：ホーム画面、住所一覧画面、住所追加画面、注文詳細画面

**権限による表示制御**：
- 本画面はログイン済みユーザーのみがアクセス可能
- 住所データの有無により「住所追加」または「住所管理」ボタンの表示が切り替わる

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 51 | ダッシュボード表示 | 主機能 | アカウントダッシュボードのメイン画面表示、ボトムナビゲーションによる各機能へのアクセス |

## 画面種別

ダッシュボード画面（タブ型統合ビュー）

## URL/ルーティング

- ルート名: `dashboardScreen`
- パス: `/dashboard`

## 入出力項目

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

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| なし | - | - | ユーザー操作はボタンタップのみ |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ダッシュボードタイトル | String | AppBarに表示される「Dashboard」 |
| ヘッダービュー | Widget | DashboardHeaderView - ユーザー情報サマリー |
| 注文タブ | Tab | 最近の注文を表示するタブ |
| 住所タブ | Tab | 登録住所を表示するタブ |
| レビュータブ | Tab | 投稿レビューを表示するタブ |
| 注文一覧 | List<Order> | 最近の注文リスト（OrdersListウィジェット） |
| 住所一覧 | List<Address> | 登録住所リスト（AddressScreenウィジェット） |
| レビュー一覧 | List<Review> | 投稿レビューリスト（ReviewsScreenウィジェット） |
| 買い物を続けるボタン | Button | ホーム画面へ遷移するボタン |
| 住所追加/管理ボタン | Button | 住所関連画面へ遷移するボタン |

## イベント仕様

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

**トリガー**: 画面がビルドされたタイミング

**処理フロー**:
1. `appStoragePref.getAddressData()`で住所データ有無を確認
2. `DefaultTabController`で3つのタブを初期化
3. 各タブに対応するBlocProviderを設定
   - OrderListBloc: 注文リスト用
   - ReviewsBloc: レビューリスト用
   - AddressBloc: 住所リスト用
4. TabBarViewで各タブのコンテンツを表示

### 2-買い物を続けるボタン押下イベント

**トリガー**: 「Continue Shopping」ボタンタップ

**処理フロー**:
1. `Navigator.pushReplacementNamed(context, home)`を実行
2. ホーム画面に遷移（現在の画面はスタックから削除）

### 3-住所追加ボタン押下イベント

**トリガー**: 住所がない状態で「Add New Address」ボタンタップ

**処理フロー**:
1. `Navigator.pushNamed(context, addAddressScreen, arguments: AddressNavigationData(...))`を実行
2. 住所追加画面に遷移
3. `isEdit: false`, `addressModel: null`, `isCheckout: false`を引数として渡す

### 4-住所管理ボタン押下イベント

**トリガー**: 住所がある状態で「Manage Address」ボタンタップ

**処理フロー**:
1. `Navigator.of(context).pushNamed(addressList)`を実行
2. 住所一覧画面に遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | なし | SELECT | 注文、住所、レビューデータを取得（各Blocで処理） |

本画面自体ではデータベースの更新処理は行いません。データの取得・更新は埋め込まれた各サブ画面（OrdersList, AddressScreen, ReviewsScreen）のBlocで処理されます。

## メッセージ仕様

| メッセージID | メッセージ種別 | 表示条件 | メッセージ内容 |
|-------------|--------------|----------|--------------|
| なし | - | - | 本画面自体ではメッセージ表示なし（サブ画面で表示） |

## 例外処理

| 例外ケース | 処理内容 | ユーザーへの影響 |
|-----------|---------|----------------|
| 注文データ取得失敗 | OrdersListウィジェット内でエラー処理 | 注文タブにエラーまたは空状態を表示 |
| 住所データ取得失敗 | AddressScreenウィジェット内でエラー処理 | 住所タブにエラーまたは空状態を表示 |
| レビューデータ取得失敗 | ReviewsScreenウィジェット内でエラー処理 | レビュータブにエラーまたは空状態を表示 |

## 備考

- 各タブのコンテンツは`isFromDashboard: true`パラメータを受け取り、ダッシュボード専用のレイアウトで表示される
- タブの高さは`MediaQuery.of(context).size.height / 2.15`で計算され、画面の約半分を占める
- 各タブの下部に固定のアクションボタン（買い物を続ける、住所追加等）が配置される
- SingleTickerProviderStateMixinを使用してTabControllerのアニメーションを制御

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | address_navigation_data.dart | `lib/screens/add_edit_address/data_model/` | 住所画面への遷移パラメータ |

**読解のコツ**: AddressNavigationDataは住所追加/編集画面への遷移時に使用される。isEdit, addressModel, isCheckoutの3つのフラグで挙動が変わる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dashboard.dart | `lib/screens/dashboard/view/dashboard.dart` | ダッシュボード画面のメインウィジェット |

**主要処理フロー**:
1. **22-40行目**: State内で3つのサブ画面ウィジェットを定義（orderScreen, reviewsScreen, addressScreen）
2. **43-55行目**: `build()`でDefaultTabControllerとScaffoldを構築
3. **57-273行目**: `dashboardView()`でTabBarとTabBarViewを構築
4. **72-82行目**: TabBarで3つのタブを定義
5. **88-266行目**: TabBarViewで各タブのコンテンツを表示

#### Step 3: サブ画面を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_list.dart | `lib/screens/orders/screen/order_list.dart` | 注文一覧のサブ画面 |
| 3-2 | address_screen.dart | `lib/screens/address_list/view/address_screen.dart` | 住所一覧のサブ画面 |
| 3-3 | reviews.dart | `lib/screens/review/screen/reviews.dart` | レビュー一覧のサブ画面 |

**主要処理フロー**:
- 各サブ画面は`isFromDashboard: true`を受け取り、ダッシュボード用のコンパクトレイアウトで表示

#### Step 4: ヘッダービューを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | dashboard_header_view.dart | `lib/screens/dashboard/widget/dashboard_header_view.dart` | ヘッダー部分のウィジェット |

**主要処理フロー**:
- ユーザー情報（名前、メール、プロフィール画像等）をサマリー表示

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

```
DashboardScreen (StatefulWidget)
    │
    ├─ build()
    │      └─ DefaultTabController(length: 3)
    │             └─ Scaffold
    │                    ├─ AppBar(title: "Dashboard")
    │                    └─ dashboardView()
    │                           ├─ DashboardHeaderView
    │                           ├─ TabBar
    │                           │      ├─ Tab("Recent Orders")
    │                           │      ├─ Tab("Address")
    │                           │      └─ Tab("Reviews")
    │                           │
    │                           └─ TabBarView
    │                                  ├─ Column
    │                                  │      ├─ orderScreen (OrdersList)
    │                                  │      │      └─ BlocProvider<OrderListBloc>
    │                                  │      └─ ElevatedButton("Continue Shopping")
    │                                  │             └─ Navigator.pushReplacementNamed(home)
    │                                  │
    │                                  ├─ Column
    │                                  │      ├─ addressScreen (AddressScreen)
    │                                  │      │      └─ BlocProvider<AddressBloc>
    │                                  │      └─ ElevatedButton("Add/Manage Address")
    │                                  │             ├─ Navigator.pushNamed(addAddressScreen)
    │                                  │             └─ Navigator.pushNamed(addressList)
    │                                  │
    │                                  └─ Column
    │                                         ├─ reviewsScreen (ReviewsScreen)
    │                                         │      └─ BlocProvider<ReviewsBloc>
    │                                         └─ ElevatedButton("Continue Shopping")
    │                                                └─ Navigator.pushReplacementNamed(home)
```

### データフロー図

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

SharedPreferences ──────▶ getAddressData() ────────────▶ addressIsEmpty (bool)
                                                              │
                                                              ▼
                                                    ボタン表示切替
                                                    ├─ 住所あり: "Manage Address"
                                                    └─ 住所なし: "Add New Address"

OrderListBloc ──────────▶ 注文データ取得 ─────────────▶ OrdersList表示

AddressBloc ────────────▶ 住所データ取得 ─────────────▶ AddressScreen表示

ReviewsBloc ────────────▶ レビューデータ取得 ─────────▶ ReviewsScreen表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dashboard.dart | `lib/screens/dashboard/view/dashboard.dart` | ソース | ダッシュボード画面のメインウィジェット |
| dashboard_header_view.dart | `lib/screens/dashboard/widget/dashboard_header_view.dart` | ソース | ヘッダー部分のウィジェット |
| index.dart | `lib/screens/dashboard/utils/index.dart` | ソース | エクスポート集約 |
| order_list.dart | `lib/screens/orders/screen/order_list.dart` | ソース | 注文一覧サブ画面 |
| address_screen.dart | `lib/screens/address_list/view/address_screen.dart` | ソース | 住所一覧サブ画面 |
| reviews.dart | `lib/screens/review/screen/reviews.dart` | ソース | レビュー一覧サブ画面 |
| order_list_bloc.dart | `lib/screens/orders/bloc/order_list_bloc.dart` | ソース | 注文リストのBloc |
| address_bloc.dart | `lib/screens/address_list/bloc/address_bloc.dart` | ソース | 住所リストのBloc |
| reviews_bloc.dart | `lib/screens/review/bloc/reviews_bloc.dart` | ソース | レビューリストのBloc |
| route_constants.dart | `lib/utils/route_constants.dart` | ソース | ルーティング定数 |
