# 画面設計書 12-バーコードスキャン画面

## 概要

本ドキュメントは、InvenTreeフロントエンドアプリケーションの「バーコードスキャン画面」に関する設計仕様を記載する。

### 本画面の処理概要

本画面は、バーコードをスキャンして在庫アイテムや部品、ロケーションなどのオブジェクトを検索・識別するための画面である。

**業務上の目的・背景**：在庫管理業務において、物理的な部品や在庫アイテムに貼付されたバーコードをスキャンすることで、システム上の対応するレコードを素早く特定し、在庫操作（移動、カウント、調整等）を効率化する。入出庫作業、棚卸し作業、ピッキング作業などで広く活用される。

**画面へのアクセス方法**：ヘッダーメニューのスキャンアイコンをクリック、またはURL `/scan/` に直接アクセスする。ホームダッシュボードからも遷移可能。

**主要な操作・処理内容**：
1. バーコードの入力（キーボード入力またはカメラスキャン）
2. スキャン結果の一覧表示
3. スキャン済みアイテムの選択
4. 選択したアイテムに対する一括アクション（カウント等）
5. スキャン履歴の管理（削除）
6. スキャン履歴のローカルストレージ保存

**画面遷移**：
- 遷移元：ホームダッシュボード、ヘッダーメニュー
- 遷移先：部品詳細画面、在庫アイテム詳細画面、ロケーション詳細画面など（スキャン結果のアイテム種別に応じて）

**権限による表示制御**：認証済みユーザーのみアクセス可能。スキャン結果のアイテムへの遷移は、対象モデルへの表示権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | バーコードスキャン | 主機能 | バーコード入力・スキャン、アイテム検索・識別処理 |
| 41 | バーコード生成 | API連携 | スキャン結果からのオブジェクト情報取得 |

## 画面種別

操作画面（スキャン入力＋一覧表示）

## URL/ルーティング

`/scan/`

## 入出力項目

### 入力項目

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| バーコード | テキスト入力/カメラスキャン | 文字列 | ○ | スキャン対象のバーコードデータ |

### 出力項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| スキャン結果一覧 | テーブル | スキャンしたアイテムの履歴一覧 |
| 選択中アイテム数 | 数値 | 現在選択されているアイテムの数 |
| アクションパネル | UI要素 | 選択したアイテムに対する操作ボタン |

## 表示項目

### スキャン結果テーブル

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| アイテム（Item） | コンポーネント | スキャン結果のオブジェクト表示（RenderInstance） |
| モデル（Model） | 文字列 | オブジェクトのモデルタイプ（part, stockitem等） |
| バーコード（Barcode） | 文字列 | スキャンしたバーコード文字列 |
| タイムスタンプ（Timestamp） | 日時 | スキャン実行日時 |

### バーコード入力パネル

| 項目名 | 説明 |
|--------|------|
| 入力タイプ切り替え | カメラ入力/スキャナー入力の切り替え |
| バーコードデータ表示 | 最後にスキャンしたバーコードデータ |
| エラー表示 | スキャンエラー時のメッセージ |

### アクションパネル

| 項目名 | 説明 |
|--------|------|
| 選択なし時 | 「Scan and select items to perform actions」メッセージ |
| 選択あり（同一タイプ） | Countボタン等のアクションボタン |
| 選択あり（複数タイプ） | 「Multiple object types selected」警告 |

## イベント仕様

### 1-バーコードスキャン

バーコード入力後の処理。

**処理フロー**：
1. `POST /api/barcode/` にバーコードデータを送信
2. レスポンスからモデルタイプとPKを抽出
3. 該当するモデルタイプのAPIエンドポイントからインスタンス詳細を取得
4. 履歴リストに追加
5. 重複の場合は「Item already scanned」通知を表示

### 2-アイテム選択

テーブル行のチェックボックス操作。

**処理フロー**：
1. 選択状態を更新
2. アクションパネルの表示を更新
3. 選択されたアイテムの種類を判定

### 3-アイテム削除

選択したアイテムの削除ボタン押下時の処理。

**処理フロー**：
1. 選択されたアイテムIDリストを取得
2. 履歴リストから該当アイテムを削除
3. ローカルストレージを更新
4. 選択状態をクリア

### 4-アイテム詳細表示

行アクション「View Item」押下時の処理。

**処理フロー**：
1. アイテムのモデルタイプとPKを取得
2. 対応する詳細画面URLに遷移

### 5-カウントアクション

選択アイテムに対するCountボタン押下時の処理。

**処理フロー**：
1. 選択されたアイテムが同一モデルタイプか確認
2. カウント処理を実行（現在は未実装: notYetImplemented）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| バーコードスキャン | - | SELECT | バーコードに紐づくオブジェクトの検索のみ（更新なし） |

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

本画面ではデータベースの更新は行わない。スキャン履歴はブラウザのローカルストレージに保存される。

#### ローカルストレージ

| キー | 値 | 説明 |
|-----|---|------|
| scan-history | BarcodeScanItem[] | スキャン履歴アイテムの配列 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| 警告 | 重複スキャン | Duplicate - Item already scanned |
| エラー | API通信エラー | Failed to scan barcode / Scan Error |
| エラー | インスタンス取得エラー | Failed to fetch instance data / API Error |
| 情報 | アイテム未選択 | No Items Selected - Scan and select items to perform actions |
| 警告 | 複数タイプ選択 | Multiple object types selected |
| 警告 | 不明なアイテム | Selected elements are not known |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| バーコード認識不可 | 空の結果（モデルなし）として履歴に追加 |
| API通信エラー | showApiErrorMessageでエラー通知を表示 |
| インスタンス取得エラー | showApiErrorMessageでエラー通知を表示 |
| カメラ利用不可 | スキャナー入力モードで利用（設定で制御） |

## 備考

- スキャン履歴はブラウザのローカルストレージに永続化される
- カメラ入力はグローバル設定 `BARCODE_WEBCAM_SUPPORT` で有効/無効を制御
- 入力タイプ（カメラ/スキャナー）の選択状態もローカルストレージに保存
- バーコードで認識可能なモデルタイプは ModelInformationDict で定義されている

---

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

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

### 推奨読解順序

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

バーコードスキャンアイテムの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BarcodeScanItem.ts | `src/frontend/src/components/barcodes/BarcodeScanItem.ts` | スキャン結果アイテムの型定義（id, barcode, model, pk, instance, timestamp等） |
| 1-2 | ModelInformation.ts | `src/frontend/lib/enums/ModelInformation.ts` | モデルタイプとAPIエンドポイントの対応定義 |

**読解のコツ**: BarcodeScanItemは各スキャン結果を表すデータ構造。model/pkでオブジェクトを識別し、instanceに詳細データを格納する。

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

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Scan.tsx | `src/frontend/src/pages/Index/Scan.tsx` | メイン画面コンポーネント。state管理、スキャン処理ロジックを確認 |

**主要処理フロー**:
1. **40-47行**: useListState/useLocalStorageでスキャン履歴を管理
2. **52-88行**: fetchInstance関数（モデルインスタンスの取得）
3. **91-136行**: scanBarcode関数（バーコードスキャン処理のメイン）
4. **139-147行**: 履歴のローカルストレージ同期
5. **150-152行**: 選択アイテムの抽出
6. **155-190行**: SelectedActionsコンポーネント（選択状態に応じたUI）
7. **192-257行**: レンダリング部分（BarcodeInput + BarcodeScanTable）

#### Step 3: バーコード入力コンポーネントを理解する

バーコード入力UIの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BarcodeInput.tsx | `src/frontend/src/components/barcodes/BarcodeInput.tsx` | 入力タイプ切り替え、カメラ/キーボード入力の統合 |
| 3-2 | BarcodeCameraInput.tsx | `src/frontend/src/components/barcodes/BarcodeCameraInput.tsx` | カメラを使ったバーコード読み取り |
| 3-3 | BarcodeKeyboardInput.tsx | `src/frontend/src/components/barcodes/BarcodeKeyboardInput.tsx` | キーボード/スキャナーからの入力 |

#### Step 4: スキャン結果テーブルを理解する

結果表示テーブルの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BarcodeScanTable.tsx | `src/frontend/src/tables/general/BarcodeScanTable.tsx` | テーブル列定義、行アクション、選択機能を確認 |

**主要処理フロー**:
- **31-67行**: テーブル列定義（instance, model, barcode, timestamp）
- **69-85行**: rowActions定義（View Item）
- **87-100行**: tableActions定義（削除ボタン）
- **106-122行**: InvenTreeTableコンポーネントの利用

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

```
Scan (Scan.tsx:39)
    │
    ├─ useListState<BarcodeScanItem>() - スキャン履歴state
    │
    ├─ useLocalStorage('scan-history') - 永続化
    │
    ├─ scanBarcode(barcode) (91-136行)
    │      ├─ api.post(ApiEndpoints.barcode)
    │      │      └─ バーコード解析API呼び出し
    │      │
    │      └─ fetchInstance(item) (52-88行)
    │             └─ api.get(model_info.api_endpoint)
    │                    └─ インスタンス詳細取得
    │
    ├─ BarcodeInput
    │      ├─ BarcodeCameraInput
    │      │      └─ onScan callback
    │      │
    │      └─ BarcodeKeyboardInput
    │             └─ onScan callback
    │
    └─ BarcodeScanTable
           └─ InvenTreeTable
                  ├─ RenderInstance (アイテム表示)
                  └─ RowViewAction (詳細遷移)
```

### データフロー図

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

バーコード入力 ───▶ scanBarcode() ───▶ 履歴リスト更新
(カメラ/キーボード)        │                    │
                           ▼                    ▼
                    POST /api/barcode/    ローカルストレージ
                           │                    │
                           ▼                    ▼
                    fetchInstance()      BarcodeScanTable表示
                           │
                           ▼
                    GET /api/{model}/{pk}/
                           │
                           ▼
                    インスタンス詳細取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Scan.tsx | `src/frontend/src/pages/Index/Scan.tsx` | ソース | バーコードスキャン画面メインコンポーネント |
| BarcodeScanItem.ts | `src/frontend/src/components/barcodes/BarcodeScanItem.ts` | ソース | スキャンアイテムの型定義 |
| BarcodeInput.tsx | `src/frontend/src/components/barcodes/BarcodeInput.tsx` | ソース | バーコード入力コンポーネント |
| BarcodeCameraInput.tsx | `src/frontend/src/components/barcodes/BarcodeCameraInput.tsx` | ソース | カメラ入力コンポーネント |
| BarcodeKeyboardInput.tsx | `src/frontend/src/components/barcodes/BarcodeKeyboardInput.tsx` | ソース | キーボード入力コンポーネント |
| BarcodeScanTable.tsx | `src/frontend/src/tables/general/BarcodeScanTable.tsx` | ソース | スキャン結果テーブルコンポーネント |
| ModelInformation.ts | `src/frontend/lib/enums/ModelInformation.ts` | ソース | モデル情報定義 |
| ApiEndpoints.ts | `src/frontend/lib/enums/ApiEndpoints.ts` | ソース | APIエンドポイント定義 |
| RenderInstance.tsx | `src/frontend/src/components/render/Instance.tsx` | ソース | インスタンス表示コンポーネント |
| notifications.ts | `src/frontend/src/functions/notifications.ts` | ソース | 通知表示関数 |
