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

## 概要

本ドキュメントは、InvenTreeシステムにおけるダッシュボード表示機能の設計仕様を定義する。この機能は、ホーム画面においてユーザーがカスタマイズ可能なウィジェットを配置し、在庫状況や業務サマリーを可視化する。

### 本機能の処理概要

**業務上の目的・背景**：
在庫管理業務では、日々の在庫状況、発注・受注の進捗、低在庫アラートなど、様々な情報を迅速に把握する必要がある。本機能は、ログイン直後のホーム画面でこれらの重要情報をダッシュボードとして一覧表示し、業務の効率的な意思決定を支援する。ウィジェットの追加・削除・配置変更により、ユーザーごとに最適な画面構成をカスタマイズできる。

**機能の利用シーン**：
- ログイン後に在庫状況の概要を確認する
- 期限切れ在庫や低在庫の件数を把握する
- 自分に割り当てられた発注・受注を確認する
- ウィジェットを追加・削除してダッシュボードをカスタマイズする

**主要な処理内容**：
1. ダッシュボードレイアウトの読み込み（ローカルストレージ）
2. 組み込みウィジェットの表示
3. プラグイン提供ウィジェットの読み込み
4. ウィジェットの追加・削除・配置変更
5. レイアウトの保存

**関連システム・外部連携**：
- プラグインシステム（PluginUIFeatureType.dashboard）
- ローカルストレージ（レイアウト・ウィジェット選択の保存）
- 各種データAPIとの連携（在庫、発注、受注等）

**権限による制御**：
- ウィジェットの表示はユーザーの閲覧権限に依存
- 各ウィジェットが参照するモデルの閲覧権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ホーム画面（ダッシュボード） | 主機能 | ウィジェット表示、カスタマイズ |

## 機能種別

データ表示 / 設定管理 / UI構成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| widgets | array | No | 選択されたウィジェットのラベル配列 | |
| layouts | object | No | レスポンシブレイアウト定義 | |

### 入力データソース

- ローカルストレージ（widgets, layouts）
- プラグインAPI（plugin_ui_features_list）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ウィジェット | ReactComponent | 各ウィジェットのレンダリング結果 |
| レイアウト | object | react-grid-layout形式のレイアウト定義 |

### 出力先

- ホーム画面（ダッシュボード）
- ローカルストレージ（設定保存時）

## 処理フロー

### 処理シーケンス

```
1. ダッシュボードページ読み込み
   └─ DashboardLayout コンポーネント
2. 組み込みウィジェット定義の取得
   └─ DashboardWidgetLibrary()
3. プラグインウィジェットの取得（有効時）
   └─ GET /api/plugins/ui/
4. ローカルストレージからレイアウト読み込み
   └─ useLocalState
5. ウィジェットのフィルタリング
   └─ ユーザー権限に基づく
6. ダッシュボードのレンダリング
   └─ ReactGridLayout
```

### フローチャート

```mermaid
flowchart TD
    A[ダッシュボードアクセス] --> B[組み込みウィジェット取得]
    B --> C{プラグイン有効?}
    C -->|Yes| D[プラグインウィジェット取得]
    C -->|No| E[組み込みのみ]
    D --> F[ローカルストレージ読み込み]
    E --> F
    F --> G[ユーザー権限でフィルタ]
    G --> H{ウィジェット選択あり?}
    H -->|No| I[サンプルダッシュボード表示]
    H -->|Yes| J[選択されたウィジェット表示]
    I --> K[レンダリング]
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-46-01 | 権限ベースフィルタ | ユーザーの閲覧権限がないモデルのウィジェットは非表示 | ウィジェット一覧取得時 |
| BR-46-02 | レイアウト永続化 | レイアウト変更はローカルストレージに自動保存 | レイアウト変更時 |
| BR-46-03 | 最小サイズ制約 | 各ウィジェットは定義されたminWidth/minHeightを下回れない | リサイズ時 |
| BR-46-04 | サンプルダッシュボード | ウィジェット未選択時はサンプルを表示 | 初回表示時 |

### 計算ロジック

特になし（ウィジェット内の集計はAPIから取得）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ウィジェットデータ取得 | 各種テーブル | SELECT | ウィジェット内容の取得 |
| プラグインウィジェット取得 | plugin_pluginconfig | SELECT | プラグイン情報取得 |

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

ダッシュボードレイアウト自体はローカルストレージに保存されるため、直接的なデータベース操作は限定的。各ウィジェットが個別にAPIを呼び出してデータを取得する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | LoadError | プラグインウィジェット読み込み失敗 | エラーアラートを表示 |
| - | RenderError | ウィジェットレンダリング失敗 | 該当ウィジェットを非表示 |

### リトライ仕様

プラグインウィジェットの読み込みは再マウント時に再試行。

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

ダッシュボード表示自体にトランザクション管理は不要。

## パフォーマンス要件

- 初回レンダリング：500ms以内
- ウィジェット追加・削除：100ms以内
- レイアウト変更：即時反映

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

- 認証済みユーザーのみアクセス可能
- ウィジェットは閲覧権限に基づいてフィルタリング
- プラグインウィジェットはサンドボックス内で実行

## 備考

- レスポンシブ対応：lg, md, sm, xs, xxsの5段階ブレークポイント
- キーボードショートカット：Ctrl+Eで編集モード切替

---

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

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

### 推奨読解順序

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

ダッシュボードのメインコンポーネントを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Home.tsx | `src/frontend/src/pages/Index/Home.tsx` | Homeページコンポーネント |
| 1-2 | DashboardLayout.tsx | `src/frontend/src/components/dashboard/DashboardLayout.tsx` | ダッシュボードレイアウト（25-369行目） |

**読解のコツ**:
- `useLocalState`でローカルストレージからwidgets/layoutsを読み込み
- `useDashboardItems()`で組み込み+プラグインウィジェットを取得
- `ReactGridLayout`でドラッグ&ドロップ対応のグリッド表示
- `editing`状態で編集モード切替

#### Step 2: ウィジェットライブラリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DashboardWidgetLibrary.tsx | `src/frontend/src/components/dashboard/DashboardWidgetLibrary.tsx` | 組み込みウィジェット定義（17-224行目） |

**主要処理フロー**:
1. **17-187行目**: BuiltinQueryCountWidgets - 数量カウントウィジェット群
2. **189-207行目**: BuiltinGettingStartedWidgets - 初期ウィジェット
3. **210-212行目**: BuiltinSettingsWidgets - 設定ウィジェット
4. **218-224行目**: DashboardWidgetLibrary - 全ウィジェット統合

#### Step 3: プラグインウィジェット読み込みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | UseDashboardItems.tsx | `src/frontend/src/hooks/UseDashboardItems.tsx` | useDashboardItemsフック（31-114行目） |

**主要処理フロー**:
- **42-57行目**: プラグインウィジェットのAPI取得
- **62-88行目**: プラグインデータをDashboardWidgetPropsに変換
- **90-94行目**: 組み込み+プラグインウィジェットの統合

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

```
Home
    │
    └─ DashboardLayout
           │
           ├─ useDashboardItems()
           │      │
           │      ├─ DashboardWidgetLibrary()
           │      │      ├─ BuiltinQueryCountWidgets()
           │      │      ├─ BuiltinGettingStartedWidgets()
           │      │      └─ BuiltinSettingsWidgets()
           │      │
           │      └─ useQuery(plugin_ui_features)
           │
           ├─ useLocalState (widgets, layouts)
           │
           ├─ DashboardMenu
           │      └─ onAddWidget, onClear, etc.
           │
           └─ ReactGridLayout
                  │
                  └─ DashboardWidget (for each widget)
                         └─ widget.render()
```

### データフロー図

```
[データソース]           [処理]                    [出力]

LocalStorage       ───▶ useLocalState         ───▶ widgets, layouts
  (widgets, layouts)

DashboardWidget    ───▶ DashboardWidgetLibrary ───▶ builtin widgets
Library

Plugin API         ───▶ useQuery              ───▶ plugin widgets
  (/api/plugins/ui/)

                              │
                              ▼
                   DashboardLayout
                              │
                              ▼
                   ReactGridLayout  ───▶ 画面描画
                              │
                              ▼
                   onLayoutChange ───▶ LocalStorage保存
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Home.tsx | `src/frontend/src/pages/Index/Home.tsx` | ソース | ホームページ |
| DashboardLayout.tsx | `src/frontend/src/components/dashboard/DashboardLayout.tsx` | ソース | ダッシュボードレイアウト |
| DashboardWidgetLibrary.tsx | `src/frontend/src/components/dashboard/DashboardWidgetLibrary.tsx` | ソース | 組み込みウィジェット |
| UseDashboardItems.tsx | `src/frontend/src/hooks/UseDashboardItems.tsx` | ソース | ウィジェット取得フック |
| DashboardWidget.tsx | `src/frontend/src/components/dashboard/DashboardWidget.tsx` | ソース | ウィジェットコンポーネント |
| DashboardMenu.tsx | `src/frontend/src/components/dashboard/DashboardMenu.tsx` | ソース | ダッシュボードメニュー |
| DashboardWidgetDrawer.tsx | `src/frontend/src/components/dashboard/DashboardWidgetDrawer.tsx` | ソース | ウィジェット選択ドロワー |
