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

## 概要

本ドキュメントは、Shopware 6 管理画面（Administration）のダッシュボード画面の設計仕様を定義します。ダッシュボードは管理者がログイン後に最初にアクセスするメイン画面であり、売上統計や最近の注文情報など、ショップ運営に必要な重要指標を一覧表示します。

### 本画面の処理概要

**業務上の目的・背景**：ダッシュボード画面は、ショップ管理者が日々の業務開始時にショップの状態を素早く把握するためのエントリーポイントとして機能します。売上の推移、注文状況、商品の在庫警告など、経営判断に必要な情報を集約表示することで、管理者の意思決定を支援し、運用効率の向上を図ります。

**画面へのアクセス方法**：管理画面へログイン後、自動的にこの画面に遷移します。また、左側メインナビゲーションの「ダッシュボード」メニューアイコンをクリックすることでいつでもアクセス可能です。URLパスは `/admin#/sw/dashboard/index` です。

**主要な操作・処理内容**：
1. 売上統計の表示：日次・週次・月次の売上グラフを表示
2. 最近の注文一覧：直近の注文を表示し、詳細へのクイックアクセスを提供
3. 時刻に応じた挨拶メッセージ：ログインユーザーの名前と時間帯に応じたウェルカムメッセージを表示
4. 統計ウィジェット：主要KPIをカード形式で表示
5. 使用データ同意バナー：Shopware利用データ収集への同意確認（初回表示時）

**画面遷移**：この画面から各管理機能（商品管理、注文管理、顧客管理、設定など）へ遷移できます。すべての管理画面からこの画面へ戻ることが可能です。ログイン画面からログイン成功後にこの画面へ遷移します（初回ログイン時は初期設定ウィザードが優先される場合があります）。

**権限による表示制御**：ダッシュボードへのアクセスには特別な権限は不要ですが、表示される統計情報は各エンティティ（注文、商品など）の閲覧権限に依存します。例えば `order.viewer` 権限がない場合、注文関連の統計は非表示となります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | アカウント概要 | 主機能 | 管理者用ダッシュボード、売上統計表示 |

## 画面種別

ダッシュボード（概要表示）

## URL/ルーティング

- **URLパス**: `/admin#/sw/dashboard/index`
- **ルート名**: `sw.dashboard.index`
- **モジュール名**: `sw-dashboard`

## 入出力項目

本画面は主に表示専用のダッシュボードであり、ユーザーからの入力項目はありません。

## 表示項目

| 項目名 | 表示形式 | データソース | 説明 |
|--------|----------|--------------|------|
| ウェルカムメッセージ | テキスト | currentUser.firstName | 時刻に応じた挨拶とユーザー名を表示 |
| サブタイトル | テキスト | i18n | 時刻に応じたサブメッセージ |
| 売上統計グラフ | グラフ | order API | 売上の推移をチャート表示 |
| 本日の注文数 | 数値 | order API | 当日の注文件数 |
| 本日の売上 | 通貨 | order API | 当日の売上金額 |
| 最近の注文 | テーブル | order API | 直近の注文一覧 |
| 使用データ同意バナー | バナー | システム設定 | Shopwareへのデータ送信同意確認 |

## イベント仕様

### 1-画面初期化

コンポーネント作成時（`createdComponent`）に以下の処理を実行：
- 現在時刻に基づく挨拶メッセージキーの取得とキャッシュ
- セッションストアから現在のユーザー情報を取得
- 統計データの非同期読み込み開始

### 2-時刻別挨拶表示

`getGreetingTimeKey` メソッドにより、現在時刻に応じた挨拶メッセージを取得：
- 5時〜11時：朝の挨拶
- 11時〜16時：昼の挨拶
- 16時〜22時：夕方の挨拶
- 22時〜5時：夜の挨拶

各時間帯に複数の挨拶パターンがあり、ランダムに選択されます。

### 3-統計ウィジェット更新

`sw-dashboard-statistics` コンポーネントにより売上統計を表示：
- 日次/週次/月次の切り替え
- グラフの描画更新
- データの自動リフレッシュ

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | order | SELECT | 売上統計データの取得 |
| 画面表示 | user_config | SELECT | ユーザー設定の取得 |

### テーブル別更新項目詳細

#### order（参照のみ）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | amount_total | 統計期間内の注文を集計 | 売上グラフ用 |
| SELECT | created_at | 日付でグループ化 | 日次統計用 |

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|--------------|
| daytimeHeadline.5h | 情報 | 5時〜11時 | Good morning, {name}! など |
| daytimeHeadline.11h | 情報 | 11時〜16時 | Good afternoon, {name}! など |
| daytimeHeadline.16h | 情報 | 16時〜22時 | Good evening, {name}! など |
| daytimeHeadline.22h | 情報 | 22時〜5時 | Still awake, {name}? など |
| daytimeWelcomeText | 情報 | 常時 | 時刻に応じたサブタイトル |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 統計データ取得失敗 | API通信エラー | ウィジェットにエラー状態を表示、再試行ボタンを表示 |
| ユーザー名未設定 | firstName が空 | 挨拶メッセージから名前部分を省略（カンマとスペースを除去） |
| 翻訳キー未定義 | ロケール設定不備 | フォールバックロケール（英語）を使用 |

## 備考

- ダッシュボードのウィジェットは将来的に拡張可能な設計になっています
- 統計データはキャッシュされ、パフォーマンスを最適化しています
- 使用データ同意バナーは一度同意/拒否すると再表示されません

---

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

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

### 推奨読解順序

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

ダッシュボード画面で使用される主要なデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | session store | `src/Administration/Resources/app/administration/src/app/store/session.store.ts` | currentUserデータ構造、認証状態の管理方法 |

**読解のコツ**: Shopware AdminはVue.js + Vuex/Piniaベースで構築されており、グローバルストアでセッション情報を管理しています。`Shopware.Store.get('session')` でアクセスします。

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

モジュール登録とルーティング設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `src/Administration/Resources/app/administration/src/module/sw-dashboard/index.ts` | モジュール登録、ルート定義、ナビゲーション設定 |

**主要処理フロー**:
1. **18行目**: `Shopware.Module.register('sw-dashboard', {...})` でモジュールを登録
2. **29-35行目**: `routes.index` でダッシュボードページのルーティングを定義
3. **38-47行目**: ナビゲーションメニューを定義（position: 10で最上位に表示）

#### Step 3: ページコンポーネントを理解する

メインのダッシュボードページコンポーネントの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/index.js` | コンポーネントのdata、computed、methodsの実装 |

**主要処理フロー**:
- **14-18行目**: `data()` でキャッシュ用の状態変数を定義
- **26-45行目**: `welcomeMessage` computed プロパティで挨拶メッセージを生成
- **52-60行目**: `greetingName` でセッションストアからユーザー名を取得
- **68-70行目**: `createdComponent` でコンポーネント初期化処理
- **80-100行目**: `getGreetingTimeKey` で時刻に応じた挨拶キーを決定

#### Step 4: 統計コンポーネントを理解する

売上統計を表示するサブコンポーネントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sw-dashboard-statistics | `src/Administration/Resources/app/administration/src/module/sw-dashboard/component/sw-dashboard-statistics/` | 統計グラフの描画、データ取得ロジック |

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

```
sw-dashboard (モジュール)
    |
    +-- sw-dashboard-index (ページコンポーネント)
           |
           +-- createdComponent()
           |      +-- getGreetingTimeKey()
           |             +-- getGreetings()
           |
           +-- welcomeMessage (computed)
           |      +-- greetingName (computed)
           |             +-- Shopware.Store.get('session').currentUser
           |
           +-- sw-dashboard-statistics (子コンポーネント)
           |      +-- 売上統計API呼び出し
           |      +-- グラフ描画
           |
           +-- sw-usage-data-consent-banner (子コンポーネント)
                  +-- 使用データ同意確認
```

### データフロー図

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

Shopware.Store           sw-dashboard-index             画面表示
  (session)     ───▶     ・welcomeMessage計算    ───▶   ウェルカムメッセージ
  currentUser            ・getGreetingTimeKey

Order API        ───▶    sw-dashboard-statistics  ───▶   売上統計グラフ
                         ・データ集計
                         ・チャート描画

System Config    ───▶    sw-usage-data-consent    ───▶   同意バナー
                         ・同意状態確認
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `src/Administration/Resources/app/administration/src/module/sw-dashboard/index.ts` | ソース | モジュール登録・ルーティング定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/index.js` | ソース | ダッシュボードページのメインロジック |
| sw-dashboard-index.html.twig | `src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/sw-dashboard-index.html.twig` | テンプレート | ページのHTMLテンプレート |
| sw-dashboard-index.scss | `src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/sw-dashboard-index.scss` | スタイル | ページのスタイル定義 |
| sw-dashboard-statistics | `src/Administration/Resources/app/administration/src/module/sw-dashboard/component/sw-dashboard-statistics/` | ソース | 統計表示コンポーネント |
| sw-usage-data-consent-banner | `src/module/sw-settings-usage-data/component/sw-usage-data-consent-banner/` | ソース | 使用データ同意バナー |
