# 機能設計書 51-ダッシュボード表示

## 概要

本ドキュメントは、アカウントダッシュボードのメイン画面表示機能の設計を記述する。

### 本機能の処理概要

本機能は、ログイン済みユーザーのアカウント情報を集約して表示するダッシュボード画面を提供する。ユーザーは最近の注文履歴、登録済み住所、投稿したレビューを一つの画面で確認でき、各機能への迅速なアクセスが可能となる。

**業務上の目的・背景**：ECアプリにおいて、ユーザーが自身のアカウント情報を効率的に確認・管理できる統合的なインターフェースが必要である。ダッシュボード画面により、ユーザーは複数の画面を行き来することなく、主要な情報にアクセスできる。これにより、ユーザーエクスペリエンスの向上と、アプリ内での回遊性を高めることができる。

**機能の利用シーン**：ログイン後のアカウント管理時、注文状況の確認時、住所情報の確認時、過去のレビュー確認時などにユーザーが利用する。ボトムナビゲーションからアカウントメニューを選択してアクセスする。

**主要な処理内容**：
1. ユーザープロフィール情報（名前、メール、プロフィール画像）の表示
2. 最近の注文一覧の表示（最大5件）
3. 登録済み住所一覧の表示（最大5件）
4. 投稿済みレビュー一覧の表示（最大5件）
5. 各セクションから詳細画面への遷移ボタン表示

**関連システム・外部連携**：ローカルストレージ（SharedPreferences）からユーザー情報を取得。注文、住所、レビューのデータはそれぞれのBLocを介してバックエンドAPIから取得する。

**権限による制御**：ログイン済みユーザーのみがアクセス可能。未ログイン状態では表示されない。

## 関連画面

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

## 機能種別

データ表示（CRUD - Read）/ 画面統合表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | 本機能は入力パラメータを受け取らない | - |

### 入力データソース

- SharedPreferences: ユーザープロフィール情報（名前、メール、プロフィール画像URL）
- OrderListBloc: 注文一覧データ
- AddressBloc: 住所一覧データ
- ReviewsBloc: レビュー一覧データ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | String | ユーザー名 |
| customerEmail | String | ユーザーメールアドレス |
| image | String | プロフィール画像URL |
| orderList | List<Order> | 最近の注文一覧（最大5件） |
| addressList | List<AddressData> | 登録済み住所一覧（最大5件） |
| reviewList | List<ReviewData> | 投稿済みレビュー一覧（最大5件） |

### 出力先

画面表示（ダッシュボード画面）

## 処理フロー

### 処理シーケンス

```
1. 画面初期化
   └─ DashboardScreenの構築、TabControllerの初期化
2. ユーザー情報取得
   └─ SharedPreferencesから名前、メール、画像URLを取得
3. タブコンテンツの構築
   └─ 注文、住所、レビューの各BLocProviderを設定
4. ヘッダービュー表示
   └─ ユーザープロフィール情報を表示
5. タブバー表示
   └─ Recent Orders、Address、Reviewsの3タブを表示
6. タブコンテンツ表示
   └─ 選択されたタブに応じて対応するコンテンツを表示
7. アクションボタン表示
   └─ 各タブに応じた「続けて買い物」「住所管理」等のボタンを表示
```

### フローチャート

```mermaid
flowchart TD
    A[画面初期化] --> B[ユーザー情報取得]
    B --> C[タブコンテンツ構築]
    C --> D[ヘッダービュー表示]
    D --> E[タブバー表示]
    E --> F{選択タブ}
    F -->|注文| G[注文一覧表示]
    F -->|住所| H[住所一覧表示]
    F -->|レビュー| I[レビュー一覧表示]
    G --> J[続けて買い物ボタン]
    H --> K{住所あり?}
    K -->|Yes| L[住所管理ボタン]
    K -->|No| M[住所追加ボタン]
    I --> N[続けて買い物ボタン]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-51-01 | 表示件数制限 | 各セクションの一覧は最大5件まで表示 | ダッシュボード画面からの表示時 |
| BR-51-02 | 住所ボタン切替 | 住所が未登録の場合は「住所追加」、登録済みの場合は「住所管理」ボタンを表示 | 住所タブ選択時 |
| BR-51-03 | プロフィール編集遷移 | ヘッダーの「編集」ボタンでアカウント情報画面へ遷移 | ヘッダービュー表示時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロフィール表示 | - | SELECT(ローカル) | SharedPreferencesからユーザー情報を取得 |
| 注文一覧取得 | orders | SELECT | 注文履歴をAPI経由で取得 |
| 住所一覧取得 | customer_addresses | SELECT | 登録住所をAPI経由で取得 |
| レビュー一覧取得 | reviews | SELECT | 投稿レビューをAPI経由で取得 |

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

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

| 操作 | 項目（キー名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | customerName | - | ユーザー名 |
| SELECT | customerEmail | - | メールアドレス |
| SELECT | customerImage | - | プロフィール画像URL |
| SELECT | addressData | - | 住所有無フラグ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | データ取得失敗 | API通信エラー | EmptyDataViewを表示 |
| - | 画像読み込み失敗 | 画像URLが無効 | プレースホルダー画像を表示 |

### リトライ仕様

各タブのコンテンツは個別にBLocで管理されており、RefreshIndicatorによるプルダウン更新が可能。

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

本機能はデータ参照のみのため、トランザクション管理は不要。

## パフォーマンス要件

- 画面初期表示: 2秒以内
- 各タブ切替: 即座に表示（キャッシュ済みデータ使用）
- 各一覧の表示件数を5件に制限し、表示パフォーマンスを確保

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

- ログイン済みユーザーのみがアクセス可能
- ユーザー情報はSharedPreferencesに暗号化なしで保存（要改善検討）
- APIリクエストは認証トークン付きで送信

## 備考

- TabBarViewを使用した3タブ構成
- 各タブのコンテンツは独立したBLocで状態管理
- ヘッダービューはStatefulWidgetで、アカウント編集後の情報更新に対応

---

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

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

### 推奨読解順序

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

ダッシュボード画面で使用されるデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.dart | `lib/screens/dashboard/utils/index.dart` | ダッシュボード関連のインポートファイル |

**読解のコツ**: ダッシュボード自体は独自のデータモデルを持たず、注文、住所、レビューの各機能のモデルを参照している。

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

ダッシュボード画面のメインウィジェットを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dashboard.dart | `lib/screens/dashboard/view/dashboard.dart` | メイン画面の構築ロジック |

**主要処理フロー**:
1. **23-40行目**: 各BLocProvider（注文、レビュー、住所）の初期化
2. **43-54行目**: buildメソッドでScaffoldとDefaultTabControllerを構築
3. **57-273行目**: dashboardViewメソッドでタブバーとコンテンツを構築
4. **64-82行目**: TabBarの3つのタブ（注文、住所、レビュー）を定義
5. **88-266行目**: TabBarViewで各タブのコンテンツを表示

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

ユーザープロフィール表示部分を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dashboard_header_view.dart | `lib/screens/dashboard/view/dashboard_header_view.dart` | プロフィール表示ロジック |

**主要処理フロー**:
- **26-30行目**: initStateでSharedPreferencesからユーザー情報を取得
- **34-154行目**: buildメソッドでヘッダーUIを構築
- **71-80行目**: CachedNetworkImageでプロフィール画像を表示
- **112-144行目**: 編集ボタンタップでアカウント情報画面へ遷移

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

```
DashboardScreen (dashboard.dart)
    │
    ├─ DashboardHeaderView (dashboard_header_view.dart)
    │      └─ appStoragePref.getCustomerName()
    │      └─ appStoragePref.getCustomerEmail()
    │      └─ appStoragePref.getCustomerImage()
    │
    ├─ OrdersList (orders.dart) ※BlocProvider経由
    │      └─ OrderListBloc
    │
    ├─ AddressScreen (address_screen.dart) ※BlocProvider経由
    │      └─ AddressBloc
    │
    └─ ReviewsScreen (reviews.dart) ※BlocProvider経由
           └─ ReviewsBloc
```

### データフロー図

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

SharedPreferences ───▶ DashboardHeaderView ───▶ ヘッダー表示
                              │
OrderListBloc API ───▶ OrdersList Widget ───▶ 注文タブ表示
                              │
AddressBloc API ───▶ AddressScreen Widget ───▶ 住所タブ表示
                              │
ReviewsBloc API ───▶ ReviewsScreen Widget ───▶ レビュータブ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dashboard.dart | `lib/screens/dashboard/view/dashboard.dart` | ソース | ダッシュボードメイン画面 |
| dashboard_header_view.dart | `lib/screens/dashboard/view/dashboard_header_view.dart` | ソース | ヘッダービュー（プロフィール表示） |
| index.dart | `lib/screens/dashboard/utils/index.dart` | ソース | インポート集約ファイル |
