# 画面設計書 10-ホーム（ダッシュボード）

## 概要

本ドキュメントはInvenTreeシステムのホーム（ダッシュボード）画面の設計仕様を記載する。ログイン後に最初に表示される、システムのメインダッシュボード画面である。

### 本画面の処理概要

ホーム（ダッシュボード）画面は、InvenTreeシステムにログイン後に表示されるメイン画面である。ウィジェットベースのカスタマイズ可能なレイアウトを提供し、ユーザーが必要な情報を一目で確認できるダッシュボードを構築できる。ウィジェットの追加、削除、配置変更、サイズ変更が可能で、設定はユーザープロファイルに保存される。

**業務上の目的・背景**：在庫管理システムの中心となるダッシュボードとして、ユーザーが業務に必要な情報を効率的に確認できる画面を提供する。ウィジェットのカスタマイズにより、各ユーザーの役割や業務内容に応じた最適な情報表示を実現する。プラグインによるウィジェット拡張もサポートし、システムの柔軟性を高める。

**画面へのアクセス方法**：ログイン成功後に自動的に表示されるか、ナビゲーションの「Home」からアクセスする。URLは `/` または `/home/`。

**主要な操作・処理内容**：
1. ウィジェットの表示と情報確認
2. ウィジェットの追加（ドロワーから選択）
3. ウィジェットの削除
4. ウィジェットの配置変更（ドラッグ＆ドロップ）
5. ウィジェットのサイズ変更
6. 編集モードの切り替え（Ctrl+E）
7. レイアウト設定の保存

**画面遷移**：
- 遷移元：ログイン画面（認証成功時）、MFA認証画面（認証成功時）、各種画面からのナビゲーション
- 遷移先：部品管理、在庫管理、製造管理、購買管理、販売管理、設定等の各画面

**権限による表示制御**：
- ログイン済みユーザーのみアクセス可能
- ウィジェットの表示内容はユーザー権限に応じて制御される場合がある

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 46 | ダッシュボード表示 | 主機能 | システム概要情報、在庫状況、注文状況のウィジェット表示 |
| 45 | 通知表示 | 補助機能 | 未読通知の表示、通知アラートの確認 |

## 画面種別

ダッシュボード画面

## URL/ルーティング

| パス | 説明 |
|------|------|
| `/` | ホーム画面（ルート） |
| `/home/` | ホーム画面 |

## 入出力項目

### 入力項目

なし（ウィジェット内での操作は各ウィジェットによる）

### 出力項目

| No | 項目名 | 説明 |
|----|--------|------|
| 1 | ウィジェット群 | 設定されたウィジェットの表示 |
| 2 | ウィジェット未選択メッセージ | ウィジェット未設定時のガイダンス |

## 表示項目

| No | 項目名 | 表示条件 | 説明 |
|----|--------|----------|------|
| 1 | ページタイトル | 常時 | "Dashboard" |
| 2 | ダッシュボードメニュー | 常時 | ウィジェット追加、編集、削除操作用メニュー |
| 3 | ウィジェットグリッド | ウィジェット設定時 | レスポンシブグリッドレイアウト |
| 4 | ウィジェット未選択アラート | ウィジェット未設定時 | "No Widgets Selected" |
| 5 | サンプルダッシュボード | 初回表示時 | デフォルトウィジェット（news, gstart） |
| 6 | ウィジェットドロワー | 追加時 | 利用可能なウィジェット一覧 |
| 7 | ローディングインジケーター | 読込中 | 中央にLoaderを表示 |
| 8 | エラーアラート | ウィジェット読込エラー時 | "Failed to load dashboard widgets." |

## イベント仕様

### 1-画面マウント時

ダッシュボードレイアウトとウィジェットを読み込む。

**処理フロー**：
1. ローカル状態（`useLocalState`）からウィジェット設定とレイアウトを取得
2. 利用可能なウィジェット一覧を取得（`useDashboardItems`フック）
3. プラグイン有効時はプラグインウィジェットもAPI経由で取得
4. 保存されたウィジェット設定に基づいてウィジェットをフィルタリング
5. レイアウトを適用してグリッド表示

### 2-ウィジェット追加ボタン押下

ウィジェット選択ドロワーを開く。

**処理フロー**：
1. `DashboardWidgetDrawer`コンポーネントを開く
2. 利用可能なウィジェット一覧から選択
3. 選択時に`addWidget`関数を呼び出し
4. ウィジェット配列に追加、レイアウトを更新
5. サンプルダッシュボード表示中の場合は非表示に切り替え

### 3-編集モード切り替え（Ctrl+E）

ウィジェットの配置・サイズ変更モードを切り替える。

**処理フロー**：
1. `setEditing.toggle()`で編集モードを切り替え
2. 編集モード時：ウィジェットのドラッグ＆リサイズが有効化
3. 通常モード時：ウィジェットの操作がロック

### 4-ウィジェット削除

特定のウィジェットを削除する。

**処理フロー**：
1. 削除モードを有効化（`setRemoving.open`）
2. ウィジェットの削除ボタンを押下
3. `removeWidget`関数を呼び出し
4. ウィジェット配列から削除、レイアウトから該当エントリを削除
5. ローカル/リモートストレージに保存

### 5-レイアウト変更

ウィジェットの配置やサイズを変更する。

**処理フロー**：
1. react-grid-layoutの`onLayoutChange`イベント発火
2. 新しいレイアウトをウィジェット要件に基づいて調整
3. ローカル状態を更新
4. ユーザープロファイルにPATCHリクエストで保存

### 6-レイアウトクリア

すべてのウィジェットを削除する。

**処理フロー**：
1. `clearWidgets`関数を呼び出し
2. サンプルダッシュボード表示を無効化
3. ウィジェット配列とレイアウトを空に設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ウィジェット設定変更 | user_profile | UPDATE | ウィジェット/レイアウト設定の保存 |

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

#### user_profile

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | widgets | { widgets: [...], layouts: {...} } | JSONオブジェクトとして保存 |

## メッセージ仕様

| No | メッセージID | メッセージ種別 | メッセージ内容 | 表示条件 |
|----|-------------|---------------|---------------|----------|
| 1 | no-widgets | 情報 | No Widgets Selected / Use the menu to add widgets to the dashboard | ウィジェット未設定時 |
| 2 | widget-error | エラー | Error / Failed to load dashboard widgets. | ウィジェット読込エラー時 |

## 例外処理

| No | 例外条件 | 処理内容 |
|----|----------|----------|
| 1 | ウィジェット読込エラー | エラーアラートを表示 |
| 2 | プラグインウィジェット取得失敗 | 内蔵ウィジェットのみで続行 |
| 3 | レイアウト保存失敗 | ローカルストレージには保存、サーバー同期は次回ログイン時 |

## 備考

- レスポンシブグリッドレイアウト（react-grid-layout）を使用
- ブレークポイント：lg(1200), md(996), sm(768), xs(480), xxs(0)
- 列数：lg(12), md(10), sm(6), xs(4), xxs(2)
- 行高さ：64px
- ウィジェットには最小幅・最小高さの制約がある
- Ctrl+Eで編集モード切り替え（ショートカット）
- プラグインウィジェットは`ENABLE_PLUGINS_INTERFACE`設定が有効な場合のみ読み込み
- デフォルトウィジェット：news, gstart（初回表示時のサンプル）

---

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

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

### 推奨読解順序

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

ダッシュボードに関連するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | LocalState.tsx | `src/frontend/src/states/LocalState.tsx` | `widgets`, `layouts`, `setWidgets`, `setLayouts`の状態管理 |
| 1-2 | DashboardWidget.tsx | `src/frontend/src/components/dashboard/DashboardWidget.tsx` | `DashboardWidgetProps`インターフェース |

**読解のコツ**: ウィジェットとレイアウトがローカルストレージとユーザープロファイルの両方に保存されることを理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Home.tsx | `src/frontend/src/pages/Index/Home.tsx` | 非常にシンプルな構造、DashboardLayoutを使用 |

**主要処理フロー**:
1. **行5-11**: PageTitleとDashboardLayoutの表示

#### Step 3: ダッシュボードレイアウトを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DashboardLayout.tsx | `src/frontend/src/components/dashboard/DashboardLayout.tsx` | メインのダッシュボードロジック |

**主要処理フロー**:
- **行25-58**: 状態初期化（layouts, widgets, editing, removing等）
- **行61-68**: キーボードショートカット（Ctrl+E）
- **行70-72**: 利用可能ウィジェット取得
- **行87-110**: ウィジェット追加処理
- **行115-132**: ウィジェット削除処理
- **行135-164**: レイアウト更新処理
- **行171-199**: レイアウト変更ハンドラ
- **行259-330**: JSX描画（メニュー、グリッド、ドロワー）

#### Step 4: ウィジェット読み込みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | UseDashboardItems.tsx | `src/frontend/src/hooks/UseDashboardItems.tsx` | ビルトイン+プラグインウィジェットの読み込み |

**主要処理フロー**:
- **行31-57**: プラグインウィジェットのAPI取得
- **行62-88**: プラグインウィジェットのマッピング
- **行90-94**: ビルトイン+プラグインウィジェットの統合

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

```
Home.tsx (エントリーポイント)
    │
    ├─ PageTitle (title="Dashboard")
    │
    └─ DashboardLayout
           │
           ├─ useLocalState (widgets, layouts, setWidgets, setLayouts)
           │
           ├─ useDashboardItems()
           │      ├─ DashboardWidgetLibrary() [ビルトイン]
           │      └─ useQuery [プラグイン]
           │             └─ GET plugin/ui/features/dashboard
           │
           ├─ useHotkeys (Ctrl+E → 編集モード切替)
           │
           ├─ DashboardWidgetDrawer (ウィジェット追加UI)
           │      └─ onAddWidget → addWidget()
           │
           ├─ DashboardMenu (編集/削除/クリア操作)
           │
           └─ ReactGridLayout (Responsive)
                  └─ DashboardWidget[] (各ウィジェット)
                         └─ item.render()
```

### データフロー図

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

ローカルストレージ ─────▶ useLocalState()
                            │
                            ├─ remoteWidgets, remoteLayouts
                            │
                            ▼
プラグイン設定 ─────────▶ useDashboardItems()
                            │
                            ├─ DashboardWidgetLibrary() [ビルトイン]
                            │
                            ├─ GET plugin/ui/features [プラグイン]
                            │
                            ▼
                     ウィジェット統合
                            │
                            ▼
                     ReactGridLayout ──────────────────────▶ 画面表示
                            │
                            │
レイアウト変更 ─────────▶ onLayoutChange()
                            │
                            ├─ setLayouts()
                            │
                            └─ patchUser('widgets', {...})
                                   │
                                   └─ PATCH user/profile ──────▶ サーバー保存
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Home.tsx | `src/frontend/src/pages/Index/Home.tsx` | ソース | ホーム画面エントリーポイント |
| DashboardLayout.tsx | `src/frontend/src/components/dashboard/DashboardLayout.tsx` | ソース | ダッシュボードメインレイアウト |
| DashboardWidget.tsx | `src/frontend/src/components/dashboard/DashboardWidget.tsx` | ソース | 個別ウィジェットコンポーネント |
| DashboardWidgetDrawer.tsx | `src/frontend/src/components/dashboard/DashboardWidgetDrawer.tsx` | ソース | ウィジェット追加ドロワー |
| DashboardMenu.tsx | `src/frontend/src/components/dashboard/DashboardMenu.tsx` | ソース | ダッシュボード操作メニュー |
| DashboardWidgetLibrary.tsx | `src/frontend/src/components/dashboard/DashboardWidgetLibrary.tsx` | ソース | ビルトインウィジェット定義 |
| UseDashboardItems.tsx | `src/frontend/src/hooks/UseDashboardItems.tsx` | ソース | ウィジェット読み込みフック |
| LocalState.tsx | `src/frontend/src/states/LocalState.tsx` | ソース | ローカル状態管理（ウィジェット/レイアウト） |
| router.tsx | `src/frontend/src/router.tsx` | ソース | ルーティング定義 |
| PageTitle.tsx | `src/frontend/src/components/nav/PageTitle.tsx` | ソース | ページタイトルコンポーネント |
