# 通知設計書 58-バーコードスキャナー入力選択

## 概要

本ドキュメントは、InvenTreeアプリにおける「バーコードスキャナー入力ソース選択」ダイアログの設計仕様を定義する。ユーザーがバーコードスキャンに使用する入力デバイス（内蔵カメラまたは外部スキャナー）を選択するためのダイアログを表示する。

### 本通知の処理概要

バーコードスキャナー入力選択ダイアログは、ユーザーがバーコードスキャンに使用するデバイスを選択できるようにする機能である。この選択ダイアログは、使用環境や機器構成に応じて最適な入力方法を選択できるインターフェースを提供する。

**業務上の目的・背景**：在庫管理の現場では、様々なバーコードスキャン方法が使用される。モバイルデバイスの内蔵カメラでスキャンする場合もあれば、Bluetooth接続の外部バーコードスキャナー（ウェッジデバイス）を使用する場合もある。外部スキャナーはキーボードエミュレーションでバーコードを入力するため、内蔵カメラとは異なる処理が必要になる。このため、ユーザーが自身の機器構成に合わせて入力ソースを選択できる機能を提供している。

**通知の送信タイミング**：ユーザーがバーコード設定画面で「Barcode Scan Controller」項目をタップした時点で、即座に選択ダイアログが表示される。

**通知の受信者**：現在の操作を行っているユーザー自身。すべてのユーザーがバーコード入力設定を変更可能。

**通知内容の概要**：タイトルとして「Barcode Scan Controller」を表示し、2つの選択肢（Internal Camera、External Scanner）を提示する。各選択肢には説明テキストも表示される。

**期待されるアクション**：ユーザーは2つの選択肢の中から1つを選択する。選択を行うと設定が保存され、画面が更新される。

## 通知種別

アプリ内選択ダイアログ（AlertDialog with choices）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（ユーザー操作による即時表示） |
| 優先度 | 中（ユーザー操作に対する応答） |
| リトライ | 無（ダイアログ表示の失敗は考慮しない） |

### 送信先決定ロジック

- 現在アプリを操作しているユーザー
- 条件：なし（すべてのユーザーが設定変更可能）

## 通知テンプレート

### ダイアログ構成

| 項目 | 内容 |
|-----|------|
| タイトル | L10().barcodeScanController |
| 形式 | AlertDialog with list choices |
| キャンセルボタン | L10().cancel |

### 選択肢一覧

| 選択肢 | アイコン | タイトル | 説明 | 値 |
|-------|---------|---------|------|-----|
| Internal Camera | TablerIcons.camera | L10().cameraInternal | L10().cameraInternalDetail | BARCODE_CONTROLLER_CAMERA (0) |
| External Scanner | Icons.barcode_reader | L10().scannerExternal | L10().scannerExternalDetail | BARCODE_CONTROLLER_WEDGE (1) |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| barcodeScanController | ダイアログタイトル | L10()（ローカライズ文字列） | Yes |
| cameraInternal | 内蔵カメラオプションのタイトル | L10()（ローカライズ文字列） | Yes |
| cameraInternalDetail | 内蔵カメラオプションの説明 | L10()（ローカライズ文字列） | Yes |
| scannerExternal | 外部スキャナーオプションのタイトル | L10()（ローカライズ文字列） | Yes |
| scannerExternalDetail | 外部スキャナーオプションの説明 | L10()（ローカライズ文字列） | Yes |
| cancel | キャンセルボタンテキスト | L10()（ローカライズ文字列） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | バーコードスキャンコントローラー項目タップ | なし | バーコード設定画面のBarcode Scan Controller項目をタップ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| hasContext() == false | アプリコンテキストが利用できない場合（テスト環境等） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーがBarcode Scan Controller項目をタップ] --> B[choiceDialog表示]
    B --> C{ユーザーの選択}
    C -->|Internal Camera| D[idx = 0]
    C -->|External Scanner| E[idx = 1]
    C -->|Cancel| F[ダイアログを閉じる]
    D --> G[InvenTreeSettingsManager.setValue]
    E --> G
    G --> H{mountedチェック}
    H -->|Yes| I[setState実行]
    H -->|No| J[処理終了]
    I --> K[画面更新完了]
    F --> L[終了]
    J --> L
    K --> L
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| Settings（ローカルDB） | 現在のバーコードスキャンタイプ設定 | Sembast NoSQLデータベース |

### テーブル別参照項目詳細

#### Settings

| 参照項目（キー） | 用途 | デフォルト値 |
|----------------|------|------------|
| INV_BARCODE_SCAN_TYPE | 現在のバーコード入力タイプ | BARCODE_CONTROLLER_CAMERA (0) |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| Settings（ローカルDB） | UPDATE | バーコード入力タイプ設定の更新 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 設定保存失敗 | データベース操作失敗 | エラーは暗黙的に処理される |
| マウント解除 | ウィジェットがアンマウント | mountedチェックで回避 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（ダイアログ表示はリトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（ユーザー操作による即時表示）

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

- バーコード入力設定はローカルのみで完結し、サーバーには影響しない
- 個人情報は含まれない

## 備考

- 選択成功後、画面が即座に更新される（setState呼び出し）
- 選択したスキャンタイプに応じて、ListTileのtrailingアイコンが更新される
- ローカライズ対応により多言語での表示が可能

---

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

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

### 推奨読解順序

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

設定値の定義と、ダイアログで使用される定数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | preferences.dart | `lib/preferences.dart` | INV_BARCODE_SCAN_TYPE, BARCODE_CONTROLLER_* 定数の定義 |
| 1-2 | dialogs.dart | `lib/widget/dialogs.dart` | choiceDialog関数のパラメータと動作 |

**読解のコツ**: バーコードコントローラーの2つの定数値（CAMERA=0, WEDGE=1）を覚えておくと良い。

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

ユーザーが設定変更を開始する起点となるコードを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | barcode_settings.dart | `lib/settings/barcode_settings.dart` | build()メソッドでのListTile生成、choiceDialog呼び出し |

**主要処理フロー**:
1. **130-162行目**: ListTile.onTapでのchoiceDialog呼び出し
2. **136-149行目**: choiceDialogの選択肢リスト構成
3. **150-159行目**: onSelectedコールバックでの設定保存

#### Step 3: ダイアログ表示処理を理解する

選択ダイアログの表示ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dialogs.dart | `lib/widget/dialogs.dart` | choiceDialog()関数（15-56行目）の実装詳細 |

**主要処理フロー**:
- **15-19行目**: 関数シグネチャとパラメータ
- **21-34行目**: GestureDetectorによる選択肢の構成
- **40-55行目**: AlertDialogの表示

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

```
InvenTreeBarcodeSettingsWidget (barcode_settings.dart)
    |
    +-- build() [110-196行目]
    |       |
    |       +-- ListTile.onTap [135-161行目]
    |               |
    |               +-- choiceDialog() [dialogs.dart:15-56行目]
    |               |       |
    |               |       +-- OneContext().showDialog()
    |               |       |
    |               |       +-- onSelected callback [150-159行目]
    |               |               |
    |               |               +-- InvenTreeSettingsManager.setValue()
    |               |               |
    |               |               +-- setState()
```

### データフロー図

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

Barcode Controller項目タップ ──> choiceDialog表示 ────> 選択肢一覧
                                                              |
                                                              v
                                                    ユーザー選択待ち
                                                              |
                    +------------------------+----------------+
                    |                        |                |
                    v                        v                v
            [Internal Camera]      [External Scanner]    [Cancel]
                    |                        |                |
                    v                        v                v
                 idx=0                    idx=1       ダイアログ閉じる
                    |                        |
                    +------------------------+
                              |
                              v
                      設定値をローカルDBに保存
                              |
                              v
                       mountedチェック
                              |
                              v
                         setState()実行
                              |
                              v
                        画面更新完了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| barcode_settings.dart | `lib/settings/barcode_settings.dart` | ソース | バーコード設定画面、入力ソース選択の起点 |
| dialogs.dart | `lib/widget/dialogs.dart` | ソース | choiceDialog関数の実装 |
| preferences.dart | `lib/preferences.dart` | ソース | INV_BARCODE_SCAN_TYPE定数、InvenTreeSettingsManager |
| l10.dart | `lib/l10.dart` | ソース | ローカライズヘルパー関数 |
